Messages（Anthropic 兼容）

兼容 Anthropic Messages API。底层与 Chat Completions 是同一条路由管线，只是请求/响应格式适配为 Anthropic 风格。

本页按「场景」组织：先看场景总览，再到对应小节看请求、响应和注意事项。每个示例都标注了证据：已实测表示用线上测试账号真实调用过（2026-10-19），响应字段取自真实返回，id、思考文本等取值替换为占位；依官方文档（未实测）表示按 Anthropic 官方文档写成，我们没有真实调用验证。

场景总览

场景划分参照 Anthropic 官方的 Messages、Streaming、Tool use、Vision、Extended thinking、Prompt caching、Structured outputs 等文档。

基础对话

何时用：一问一答，或用顶层 system 设定角色和语气（Messages 的 system 不放进 messages）。

证据：已实测（线上测试账号，2026-10-19）。

请求

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 1500,
    "system": "用中文回答，简洁",
    "messages": [{"role": "user", "content": "用一句话解释量子纠缠"}]
  }'

max_tokens 必填且必须大于 0。思考模型的思考也算在 max_tokens 里，设得太小会在思考阶段被截断。

响应

取回复文本：content[] 里 type 为 text 的块的 text；结束原因 stop_reason；用量 usage。思考模型会在文本块前多一个 thinking 块，按 type 取，不要写死下标。

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "thinking", "thinking": "The user asks in Chinese to explain quantum entanglement in one sentence… (已省略)" },
    { "type": "text", "text": "量子纠缠是指两个或多个粒子形成一种关联状态后，无论相距多远，对其中一个粒子的测量会瞬间决定另一个粒子的状态，这种超越经典物理的关联性被爱因斯坦称为“幽灵般的超距作用”。" }
  ],
  "model": "glm-5.3-flash",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 23,
    "output_tokens": 80,
    "reasoning_tokens": 28
  }
}

注意事项

• stop_reason 在 OpenAI 兼容上游上只会是 end_turn / max_tokens / tool_use；命中 stop_sequences 也是 end_turn，stop_sequence 为 null，拿不到具体命中的序列。只有 Anthropic 原生上游才可能出现 stop_sequence / pause_turn / refusal。
• usage.reasoning_tokens 是平台扩展（官方用 output_tokens_details.thinking_tokens，平台不输出）。
• 下面的接口卡片由 OpenAPI 规范自动渲染（鉴权、Request body 参数表、Response schema）。

curl -X POST "https://example.com/messages" \  -H "anthropic-version: 2023-06-01" \  -H "Content-Type: application/json" \  -d '{    "model": "string",    "messages": [      {}    ],    "max_tokens": 1  }'

{  "id": "msg_xxxx",  "type": "message",  "role": "assistant",  "content": [    {      "type": "thinking",      "thinking": "The user asks in Chinese to explain quantum entanglement in one sentence. I should respond in Chinese, concisely, as requested."    },    {      "type": "text",      "text": "量子纠缠是指两个或多个粒子形成一种关联状态后，无论相距多远，对其中一个粒子的测量会瞬间决定另一个粒子的状态，这种超越经典物理的关联性被爱因斯坦称为“幽灵般的超距作用”。"    }  ],  "model": "glm-5.3-flash",  "stop_reason": "end_turn",  "stop_sequence": null,  "usage": {    "input_tokens": 23,    "output_tokens": 80,    "reasoning_tokens": 28  }}

多轮对话

何时用：需要上下文的连续对话。平台不保存对话，每次请求把完整历史放进 messages，角色交替为 user / assistant。

证据：依官方文档（未实测）。带工具的多轮已实测，见工具调用。

请求

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 1500,
    "messages": [
      {"role": "user", "content": "什么是量子纠缠？"},
      {"role": "assistant", "content": "两个粒子的状态相互关联，与距离无关。"},
      {"role": "user", "content": "它能用来超光速通信吗？"}
    ]
  }'

响应：与基础对话相同的结构。

注意事项

• 第一条消息的 role 必须是 user 或 assistant，否则 400。
• 以 assistant 结尾的「预填充（prefill）」是否被模型接受取决于上游，未实测。
• 回传思考块的规则见思考。

流式输出

何时用：逐 token 展示、降低首字延迟。

证据：已实测（线上测试账号，2026-10-19）。

请求

curl -N https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 600,
    "stream": true,
    "reasoning_effort": "low",
    "messages": [{"role": "user", "content": "只回复一个字：好"}]
  }'

响应

每个事件是 event: + data: 两行。拼接 text_delta.text 得到文本；没有 [DONE]，以 message_stop 结束。

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxxx","type":"message","role":"assistant","content":[],"model":"glm-5.3-flash","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"output_tokens":0}}}

event: ping
data: {"type":"ping"}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"thinking":"","type":"thinking"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Simple"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":": reply \"好\"."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"text":"","type":"text"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"好"}}

event: content_block_stop
data: {"index":1,"type":"content_block_stop"}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":18,"output_tokens":9,"reasoning_tokens":6}}

event: message_stop
data: {"type":"message_stop"}

注意事项

• message_start 里的 usage 此时尚无真实用量（均为 0）；以 message_delta.usage 为准。
• 事件序列是 message_start → content_block_start → content_block_delta（多次）→ content_block_stop → message_delta → message_stop。
• 本例思考块的增量里没有 signature_delta；只有上游给出签名时才有。
• 流内错误会发出 event: error，见下方「错误」。

工具调用

何时用：让模型决定调用你定义的工具。流程：声明 tools → 模型返回 tool_use 块 → 你执行 → 回填 tool_result → 模型给出最终回答。

证据：已实测（线上测试账号，2026-10-19）：单个调用、回填结果。tool_choice 的 any / tool 依官方文档（未实测）；tool_choice: none 与 disable_parallel_tool_use 的转换由单元测试覆盖（未线上实测）。

请求（第一轮）

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 1500,
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }],
    "messages": [{"role": "user", "content": "杭州明天天气怎么样？"}]
  }'

响应（第一轮）

stop_reason 为 tool_use，工具参数是已解析的对象 input（不是字符串）。

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "thinking", "thinking": "The user is asking about tomorrow's weather in Hangzhou… (已省略)" },
    {
      "type": "tool_use",
      "id": "chatcmpl-tool-xxxxxxxx",
      "name": "get_weather",
      "input": { "city": "杭州" }
    }
  ],
  "model": "glm-5.3-flash",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": { "input_tokens": 160, "output_tokens": 86, "reasoning_tokens": 74 }
}

回填工具结果（第二轮）

把 assistant 消息的 content 原样加回，再发一条 user 消息，内含 tool_result 块并用 tool_use_id 对应；tool_result 块要放在该消息内容的最前面。

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 1500,
    "tools": [ ... 同第一轮 ... ],
    "messages": [
      {"role": "user", "content": "杭州明天天气怎么样？"},
      {"role": "assistant", "content": [
        {"type": "tool_use", "id": "chatcmpl-tool-xxxxxxxx", "name": "get_weather", "input": {"city": "杭州"}}
      ]},
      {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": "chatcmpl-tool-xxxxxxxx", "content": "多云 7~13°C"}
      ]}
    ]
  }'

第二轮响应是普通的成功响应（已实测，本次请求带了 reasoning_effort: "low"，所以没有思考块）：

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "杭州明天天气为**多云**，气温在 **7~13°C** 之间。早晚偏凉，建议适当添加衣物保暖。" }
  ],
  "model": "glm-5.3-flash",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 182, "output_tokens": 31 }
}

流式下，tool_use 块在 content_block_start 里给出 id 与 name（input 为空对象），参数以 input_json_delta.partial_json 片段到达，拼接后解析（依官方文档，未实测）：

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_xxxx","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"{\"city\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"\"Hangzhou\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

注意事项

• tool_choice：auto → auto，any → required，tool → 指定函数。none → none；disable_parallel_tool_use: true → parallel_tool_calls: false。
• tool_use.id 的格式取决于上游（本例是 chatcmpl-tool- 前缀），原样回填即可。
• tool_result 的 is_error 不会传给 OpenAI 兼容上游。
• 只转换自定义工具（name + input_schema）；服务端工具与内置工具不转换，见场景总览。

思考（thinking）

何时用：需要模型先推理再回答。

证据：已实测（线上测试账号，2026-10-19）：glm-5.3-flash 默认返回 thinking 块，reasoning_effort: "low" 时思考几乎为空。thinking: {"type":"enabled","budget_tokens":N} 的效果依上游，未实测。

请求：思考是否开启、强度如何控制，取决于模型。GLM 系列强制思考，用顶层 reasoning_effort 控制强度（Python SDK 放 extra_body，平台原样转发）；其他模型的取值见各厂商页。

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "max_tokens": 1500,
    "reasoning_effort": "low",
    "messages": [{"role": "user", "content": "用一句话解释量子纠缠"}]
  }'

响应：思考过程是 content[] 里 type 为 thinking 的块，排在 text / tool_use 之前，真实响应见基础对话；流式下思考是 thinking_delta，先于正文，真实事件见流式输出。

注意事项

• 平台不会默认开启或关闭思考。你传了 thinking，就原样转发（GPT 系列除外，见下）；不传，则由上游默认决定。
• thinking: {"type": "adaptive"} 是 Anthropic 专用取值：对 MiniMax 原样转发，对其他 OpenAI 兼容模型会被丢弃，上游走自己的默认；同时带 output_config.effort 时，平台把它转成 reasoning_effort（MiniMax 除外）。
• budget_tokens 不会被换算成 reasoning_effort（GPT / o 系列例外，会按预算分档为 low / medium / high）。想控制强度，在请求体里直接加上游支持的顶层字段，如 reasoning_effort。
• 思考块没有 signature：实测 OpenAI 兼容上游返回的 thinking 块不带 signature。Anthropic 原生上游才会带签名，此时多轮对话需把 thinking 块（含 signature）原样放回历史。
• 思考内容回传：历史 assistant 消息里的 thinking 内容块，会被转成 reasoning_content 发给需要回传的模型（DeepSeek、GLM、Qwen、MiniMax）；其他模型会丢弃它们。客户端仍须在多轮（尤其工具调用）里把上一轮的思考内容完整放回历史。（这几条的转换逻辑依赖尚未发布的代码。）
• 各模型的取值与限制见 DeepSeek、GLM、Qwen、MiniMax。

图像输入

何时用：让视觉模型看图回答。需选支持图像输入的模型（如 qwen3-vl-plus）。

证据：base64 来源已实测（线上测试账号，2026-10-19，qwen3-vl-plus）；url 来源依官方文档（未实测）。

请求

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "max_tokens": 300,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..."}},
        {"type": "text", "text": "这张图里有什么？一句话回答。"}
      ]
    }]
  }'

响应

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "一个红色的实心圆。" }
  ],
  "model": "qwen3-vl-plus",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 16, "output_tokens": 8 }
}

注意事项

• 本端点返回的 usage.input_tokens 只含文本部分，不含图像 token：同一张图在 Chat Completions 里 prompt_tokens 为 82（其中 image_tokens 66），这里 input_tokens 只有 16。需要完整的输入用量请用 Chat Completions，或以账单为准。
• source.type 为 url 时要求上游能访问该地址；不确定时用 base64。不支持 file_id（Files API）。

文档输入（PDF）

何时用：把 PDF 等文档作为输入块交给模型。

证据：依官方文档（未实测）。

请求

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "max_tokens": 600,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "JVBERi0xLjQK..."}},
        {"type": "text", "text": "总结这份文档"}
      ]
    }]
  }'

响应：与基础对话相同的结构。

注意事项

• 只有 base64 来源的 document 会被转成 file 内容部件；url、text、content 来源和 file_id 来源不转换，原样转发，上游通常不认识。
• 上游是否支持读取 PDF、对页数和大小有什么限制，因模型而异，未验证。

提示缓存

何时用：多次请求共享很长的前缀（系统提示、文档、工具定义）时降低成本和延迟。

证据：已实测（线上测试账号，2026-10-19，deepseek-v4.1-flash）：在 system 文本块上带 cache_control，同一个约 2900 token 的前缀已有缓存时，cache_read_input_tokens 为 2816。

请求

curl https://api.modelsite.ai/v1/messages \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "max_tokens": 300,
    "reasoning_effort": "low",
    "system": [{
      "type": "text",
      "text": "你是客服助手。参考以下条款回答问题：\n（此处是约 2900 token 的长文本）",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "第3条说了什么？一句话。"}]
  }'

响应

{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "thinking", "thinking": "我们需要回答用户中文问题… (已省略)" },
    { "type": "text", "text": "第3条规定：平台对所有请求按实际用量计费，调用方应当在客户端保存请求编号以便对账。" }
  ],
  "model": "deepseek-v4.1-flash",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 87,
    "output_tokens": 91,
    "cache_read_input_tokens": 2816,
    "reasoning_tokens": 66
  }
}

注意事项

• Anthropic 口径下 input_tokens 不含缓存部分：本例 87 + 2816 = 2903，等于总输入。
• 缓存由上游决定。这个模型的缓存是上游自动完成的，请求里的 cache_control 对它没有作用（会被删除），没带标记同样会命中。
• 显式 cache_control：claude / gemini 前缀的模型保留；Qwen 保留但规整为 {"type":"ephemeral"}（ttl 去掉）；其他模型删除。顶层 cache_control 不转换。Qwen 一条依赖尚未发布的代码。
• 有缓存写入的上游，用量里还会出现 cache_creation_input_tokens 与按 TTL 拆分的 cache_creation。
• 官方的 max_tokens: 0（只预热缓存）不支持。

Token 计数

何时用：发请求前估算输入 token 数。

证据：已实测（线上测试账号，2026-10-19）：对 glm-5.3-flash 发 Hi，返回 {"input_tokens": 8}。计数口径与该模型实际计费的 input_tokens 是否一致，未验证。

请求

curl https://api.modelsite.ai/v1/messages/count_tokens \
  -H "Authorization: Bearer $MODELSITE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [{"role": "user", "content": "Hi"}]
  }'

响应

{ "input_tokens": 8 }

错误

401 密钥无效或缺失

{"type":"error","error":{"type":"authentication_error","message":"invalid API key"}}

缺少 Authorization 头时 message 为 missing or invalid authorization header。

402 余额不足

{"type":"error","error":{"type":"billing_error","message":"insufficient balance"}}

429 触发限流

{"type":"error","error":{"type":"rate_limit_error","message":"too many requests"}}

响应头带 Retry-After（秒），按它退避重试。

400 模型不存在

{"type":"error","error":{"type":"invalid_request_error","message":"unknown model: not-a-model"}}

model 填错或未上线时是 400（不是 404）。

400 参数错误（Anthropic 格式）

{"type":"error","error":{"type":"invalid_request_error","message":"max_tokens is required and must be > 0"}}

平台自己校验的 400 包括：max_tokens 缺失或不大于 0；第一条消息的 role 不是 user / assistant；tool_choice.type 为 tool 却没给 name。

403 无权调用该模型

{"type":"error","error":{"type":"permission_error","message":"model 'glm-5.3-flash' is not allowed for this API key"}}

503 网关容量已满

{"type":"error","error":{"type":"overloaded_error","message":"gateway at capacity, retry later"}}

同样带 Retry-After: 5。

上游暂不可用（502 / 503）：上游临时不可用时返回 502（error.type 为 server_error），所有上游都处于临时冷却时返回 503（error.code 为 no_upstream_available）。这两类在 Chat Completions 上已实测遇到，稍后重试即可。

注意：本端点（含 /v1/messages/count_tokens）上，网关产生的错误（401 / 402 / 403 / 429 / 模型不存在 / 503 容量满）与路由层产生的错误（参数、上游失败等）都使用 Anthropic 风格外壳，type 取官方名称，余额不足为 billing_error。

流式请求在已经开始输出后失败，HTTP 状态码已是 200，错误会作为流内事件发出：event: error，数据为 {"type":"error","error":{"type":"<类型>","message":"<信息>"}}。完整错误码与处理建议见 错误码。

选哪种格式？

两个入口调到的是同一批模型。

不支持或有差异的参数

请求先被转换成 Chat Completions 形态再转给上游。平台不会按「参数清单」丢弃参数，也不会钳制取值：除下表列出的、代码里写死的转换外，官方参数不做转换，按未知顶层字段原样转发给上游，上游是否认识、忽略还是报错（4xx）由它决定。

平台扩展

下面是平台自己定义、Anthropic 官方没有的内容。

鉴权与请求头

• 鉴权用 Authorization: Bearer，不用官方的 x-api-key（见页首说明）。
• 网关只放行这些请求头，其余一律丢弃：Authorization、Content-Type、Accept、Accept-Encoding、Origin、User-Agent、Anthropic-Beta、OpenAI-Beta。Anthropic-Beta 会透传给上游；anthropic-version 不校验也不转发。
• X-Request-ID：你带的值会被沿用并回显在响应头，没带则平台生成。

请求参数

响应头

平台不返回 X-RateLimit-* 或 anthropic-ratelimit-* 一类的限流额度头。

响应字段

自动行为

• 流式请求内部自动开启 include_usage，用量在 message_delta.usage 里。
• 上游失败时的自动重试、换上游规则与 Chat Completions 相同：只在你收到任何响应内容之前发生，参数错误与内容安全拦截不重试。
• 余额在流式输出途中耗尽时流会被切断，随后收到一个 data: {"error":{"type":"insufficient_quota","message":"balance exhausted"}} 帧和 data: [DONE]，这一帧是 OpenAI 风格而不是 Anthropic 的 event: error。