Messages

使用 Anthropic 兼容协议进行普通或流式对话，支持已配置的客户端工具与五分钟缓存。

最后更新: 2026-11-06

本页内容

POST/v1/messages

创建 JSON 或 SSE 对话。

接入地址

https://api.easerouter.com

SDK 基础地址填写 API 域名根地址，不要附加路径。原有 OpenAI 客户端继续使用 /v1/chat/completions，使用对应的 OpenAI 请求与响应格式。两种协议的能力范围不同，不能直接混用请求体。

请求头

参数	类型	要求	说明
`x-api-key`	string	必填	平台 API Key；也可改用 Authorization: Bearer YOUR_API_KEY。两种鉴权头只能选一种，密钥仅保存在服务端。
`Content-Type`	string	必填	application/json
`anthropic-version`	string	可选	可省略；提供时只接受 2023-06-01。暂不支持非空 anthropic-beta。
`Idempotency-Key`	string	可选	同一调用意图使用稳定编号；重复受理返回 HTTP 409 和原任务编号，不保证重放正文，也不跨协议重放。结果未知时先查询原调用，不要更换编号自动重试。

请求字段

参数	类型	要求	说明
`model`	string	必填	账户可用的基础模型或供应商服务编码。示例占位符必须替换为已配置路由和价格的真实编码。
`messages`	object[]	必填	按顺序传入 user、assistant 消息；content 使用文本或已支持的原生内容块。
`max_tokens`	integer	必填	输出 Token 上限，必须满足当前模型及执行配置限制。
`system`	string \| object[]	可选	系统提示放在顶层 system，不作为 messages 中的 system 角色。
`stream`	boolean	可选	默认 false；true 返回原生 Messages SSE 事件。
`tools / tool_choice`	array / object	可选	仅已配置的普通客户端工具；工具结果通过原生 tool_result 内容块回传。
`thinking / cache_control`	object	可选	仅在模型能力允许时使用。原生思考历史必须保留签名/脱敏块并绑定具体供应商服务编码；缓存创建首期仅支持默认或 5m，不支持 1h。

非流式请求

curl 'https://api.easerouter.com/v1/messages' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_MODEL_OR_SERVICE_CODE","max_tokens":128,"messages":[{"role":"user","content":"Hello"}]}'

{
  "id": "msg_example", "type": "message", "role": "assistant",
  "model": "YOUR_MODEL_OR_SERVICE_CODE",
  "content": [{ "type": "text", "text": "Hello!" }],
  "stop_reason": "end_turn", "stop_sequence": null,
  "usage": { "input_tokens": 14, "output_tokens": 5,
    "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 }
}

流式请求

curl -N 'https://api.easerouter.com/v1/messages' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_MODEL_OR_SERVICE_CODE","max_tokens":128,"stream":true,"messages":[{"role":"user","content":"Hello"}]}'

按 message_start、content_block_start/delta/stop、message_delta、message_stop 处理事件，期间可能有 ping；消息以实际 message_stop 结束，不使用 OpenAI [DONE]。流打开后仍可能返回 error 事件；HTTP 200 或首个内容块不代表完成。

用量、计费与异常处理

原生 input_tokens 不包含缓存读写；总输入 = input_tokens + cache_read_input_tokens + cache_creation_input_tokens。output_tokens 已包含思考用量，不重复累加。
流式 message_delta.usage 为累计用量，不逐帧相加。费用按原受理价格和实际分项结算，缺失或非法用量不当作零；最终扣费以调用记录与账单为准。
成功与错误采用 Messages 原生结构，不使用 code/msg/result 包装。请保留 request-id 及 X-EaseRouter-Task-Id；有任务编号时可通过 GET /api/v1/chat/invocation/{taskId} 核对状态，该查询使用平台统一响应且不返回正文。
缺少路由或价格时会明确拒绝调用；模型列表可见不代表已获权限或具备可用价格。当前不支持图像、文档、服务端搜索、计算机操作、代码执行、1h 缓存及非空 beta 扩展，不支持的参数在受理前拒绝。