Anthropic 风格 Messages API

Anthropic 风格代理路由适合已经发送 Anthropic Messages 请求，并希望由 AISIX 管理网关侧认证、模型别名、路由和策略的应用。

客户端保持 Anthropic 风格请求和响应格式。AISIX 成为客户端调用的端点，上游服务提供方可以是 Anthropic，也可以是其它受支持的服务提供方协议族。

本指南说明代理 API 行为。可运行的客户端集成请参见 Anthropic SDK。

客户端发送的内容

客户端会发送三个由 AISIX 管理的值：

base URL 是 AISIX 网关 Origin，末尾不包含斜杠或端点路径。
API Key 是 AISIX 调用方 API Key。
model 值是 AISIX 模型别名，例如 claude-prod。

请求体保持 Anthropic Messages 格式，包括 messages、max_tokens、tools 和 stream。调用方使用 AISIX 调用方 API Key，而不是上游 Anthropic 服务提供方密钥。

对于会发送这种形态的客户端，AISIX 也接受 messages[] 中的 system role。当上游路径需要 Anthropic 原生格式时，AISIX 会将开头的 system messages 映射到 Anthropic 顶层 system 字段。

Anthropic SDK 会以 x-api-key 发送调用方 API Key。对于直接 HTTP 客户端，AISIX 也接受 Bearer Token。

导出以下示例使用的网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="claude-prod"

Messages 请求

通过 AISIX 发送 Messages 请求：

curl -sS -X POST "${AISIX_PROXY}/v1/messages" \
  -H "x-api-key: ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "max_tokens": 128,
    "messages": [
      {
        "role": "user",
        "content": "Say hello from AISIX."
      }
    ]
  }'

成功响应使用 Anthropic Messages 格式。请求中的 model 值是 AISIX 模型别名，不一定是上游服务提供方模型 ID。

选择上游路径

与其它 AISIX 代理 API 一样，/v1/messages 让客户端请求格式在上游服务提供方变化时保持稳定。对于 Anthropic 风格请求，上游选择很重要，因为 Anthropic 上游模型会比转换后的上游保留更多 Anthropic 专属行为。

上游路径	能提供什么	适用场景
Anthropic 上游模型	原生 Anthropic 请求和响应行为，同时由 AISIX 处理调用方 API Key、服务提供方密钥和模型别名。	应用依赖 thinking blocks、图片块、缓存控制或精确工具使用语义等 Anthropic 专属行为。
转换后的上游	客户端侧保持 Anthropic 风格，AISIX 背后接入非 Anthropic 上游。	应用需要保持 Anthropic 风格客户端，同时由 AISIX 将流量路由到另一个受支持服务提供方协议族。

转换路径端到端支持文本、视觉和工具调用流程。text、image（base64 和 URL）以及 document 块会转换为上游线路上的多模态内容部分。assistant 的 tool_use 历史会变成上游工具调用，tool_result 块会变成上游期望的工具响应轮次，因此多轮工具循环能够跨服务提供方保留历史。

thinking 和 redacted_thinking 历史块在转换时会被丢弃，因为其他厂商无法重放 Anthropic 的签名推理块。当应用依赖这些推理块或其他服务提供方专属请求字段时，建议优先使用 Anthropic 上游模型。

转换路径上的请求字段

当上游不是 Anthropic 后端时，AISIX 会将 Anthropic 请求字段改写为上游协议族期望的形态，而不是原样转发：

Anthropic 字段	转换行为
`tools`, `tool_choice`	转换为 OpenAI 工具调用形态。
`stop_sequences`	作为 `stop` 发送。
`metadata.user_id`	作为 `user` 发送。
`thinking`、`output_config.effort`	映射为 `reasoning_effort`。解析顺序以及 AISIX 转发哪些档位，见推理力度。
`output_format`、`output_config.format`	`json_schema` 块会以 OpenAI 的 `json_schema` 形式作为 `response_format` 发送，并启用严格模式。严格模式要求 schema 中的每个对象都封闭其属性，因此 AISIX 会在每一层对象上加入 `additionalProperties: false`，并把所有已声明的属性列入 `required`。其他形状一律丢弃。请求同时携带这两个字段时，以 `output_format` 为准。
`context_management`, `top_k`, `mcp_servers`, `container`, `service_tier`, `betas` 以及其他 Anthropic 专属字段	丢弃。直接转发会让兼容 OpenAI 的上游因未知参数失败；丢弃后，较新的 Anthropic SDK 增加字段时请求仍能继续工作。

Anthropic 后端模型不会经过这层转换。除了解析 model 别名外，AISIX 会原样转发请求字段，因此每个 Anthropic 字段都保持原生行为。

推理力度

Anthropic 请求可以在两个位置携带推理深度。output_config.effort 是当前的控制字段，也是 Claude Opus 4.7 及以后的模型唯一接受的字段；thinking.budget_tokens 是更早的字段，在 Claude Opus 4.6 上已废弃。兼容 OpenAI 的上游只有 reasoning_effort 一个字段承载两者，因此 AISIX 按以下顺序解析：

thinking.type: disabled 发送 reasoning_effort: none。显式关闭推理是比深度档位更强的指令，同时出现的 output_config.effort 不会覆盖它。
output_config.effort 原档位发送为 reasoning_effort。
thinking.type: enabled 按 budget_tokens 映射档位：0-1023 为 minimal，1024-2047 为 low，2048-4095 为 medium，4096 及以上为 high。
thinking.type: adaptive 且未指定 output_config.effort 时发送 reasoning_effort: high，这也是请求省略 effort 时 Anthropic 自身采用的档位。

AISIX 按请求所要求的档位转发，不会拿它和上游模型的能力做校验。Anthropic 模型接受 max、xhigh 等档位，而许多兼容 OpenAI 的模型并不接受，上游不接受某个档位时会拒绝该请求。这个拒绝是有意为之：替换成上游恰好能接受的档位，会悄悄改变应用所要求的推理深度，而这比一个报错难发现得多。请选择上游模型支持的档位，具体范围以该服务提供方自己的文档为准。

完全不支持推理的上游模型会拒绝 reasoning_effort 字段本身，因此 thinking 和 effort 字段只应发送给具备推理能力的模型。

流式与非流式请求使用同一套转换逻辑。

路由行为

/v1/messages 可以使用直接和路由模型别名。非流式请求在遇到可重试上游失败时，可以故障转移到下一个目标。

流式请求可以在 AISIX 向客户端发送响应字节之前执行故障转移。客户端可见的流开始后，AISIX 不会切换目标。通用流式行为请参见流式响应。

POST /v1/messages/count_tokens 使用同一个 AISIX 调用方 API Key，并接受 Anthropic Token 计数请求格式。该路由只使用 Anthropic 上游目标。如果没有可用的 Anthropic 上游目标，AISIX 会拒绝请求。

处理错误

Messages 路由会以 Anthropic 风格信封返回错误。错误类型遵循与 Anthropic SDK 兼容的状态映射，因此 Anthropic 客户端可以用处理服务提供方错误的同一路径解析网关生成的错误。

原生 Anthropic 上游错误可能包含 request_id。AISIX 不会为网关生成的 Anthropic 风格错误添加该字段。

当输出安全护栏保留流式输出时，缓冲区中 AISIX 无法解析的帧会被丢弃，而不是未经扫描就放行。如果因此没有任何内容可返回，响应会以一个终止性 SSE error 事件结束。该事件和这条路由上的其他错误一样使用 Anthropic 信封。因此它携带的是 Anthropic 合法的 error.type 且没有 code 字段，而不是 OpenAI 风格路由会返回的 content_filter。原因写在消息里。参见 AISIX 无法扫描的帧和安全护栏拒绝。

完整错误和响应头参考请参见响应头与错误码。服务提供方定义的错误类型请参见 Anthropic 的错误文档。

下一步

你已经了解 Anthropic 风格客户端如何调用 AISIX。当应用依赖相关行为时，请继续阅读流式响应、工具调用或代理错误与重试。

客户端发送的内容​

Messages 请求​

选择上游路径​

转换路径上的请求字段​

推理力度​

路由行为​

处理错误​

下一步​