跳到主要内容

Anthropic 风格 Messages API

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

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

本指南说明代理 API 行为。可运行的 SDK 配置请参见 Anthropic SDK 快速上手。

客户端发送的内容​

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

  • base URL 指向 AISIX 代理 API，例如 http://127.0.0.1:3000。
  • 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。

Messages 请求​

通过 AISIX 发送 Messages 请求：

curl -sS -X POST "http://127.0.0.1:3000/v1/messages" \
  -H "x-api-key: YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-prod",
    "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 将流量路由到另一个受支持服务提供方协议族。

转换路径支持常见文本和工具调用流程，但不会在所有细节上完全匹配原生 Anthropic 行为。当应用依赖 Anthropic 专属内容块或服务提供方专属请求字段时，建议优先使用 Anthropic 上游模型。

路由行为​

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

流式请求使用第一个被选中的目标，并且在流开始后不会故障转移。通用流式行为请参见流式响应。

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

处理错误​

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

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

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

下一步​

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