Anthropic 兼容接口

平台兼容 Anthropic Messages 协议。已有 Anthropic SDK 代码通常只需修改 base_url 和 api_key；请求参数、响应内容块、工具调用和 SSE 流式事件继续使用 Anthropic 协议结构。

快速接入

Anthropic SDK 的 Base URL：

https://runtime-api.invalid/v1/compatible-mode

SDK 会自动在 Base URL 后追加 /v1。使用 api_key 初始化时，SDK 会发送：

X-Api-Key: sk_your_api_key

API Key 已绑定工作空间，不需要传入其他工作空间请求头。

Python SDK

安装官方 SDK：

pip install anthropic

设置环境变量，其中 AIADP_MODEL_ID 必须使用模型列表返回的模型 ID：

export AIADP_MODEL_BASE_URL="https://runtime-api.invalid/v1/compatible-mode"
export AIADP_API_KEY="sk_your_api_key"
export AIADP_MODEL_ID="your-model-id"

发起 Messages 请求：

import os

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["AIADP_API_KEY"],
    base_url=os.environ["AIADP_MODEL_BASE_URL"],
)

message = client.messages.create(
    model=os.environ["AIADP_MODEL_ID"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，请用一句话介绍你自己。"},
    ],
)

print(message.content)

cURL

先查看支持 Anthropic Messages 的模型：

curl 'https://runtime-api.invalid/v1/compatible-mode/v1/models' \
  -H 'X-Api-Key: sk_your_api_key' \
  -H 'anthropic-version: 2023-06-01'

选择返回的模型 ID 后发起请求：

curl -X POST 'https://runtime-api.invalid/v1/compatible-mode/v1/messages' \
  -H 'X-Api-Key: sk_your_api_key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "your-model-id",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你自己。"}
    ]
  }'

支持的接口

下列路径均相对于 https://runtime-api.invalid/v1/compatible-mode：

方法	路径	能力	说明
POST	/v1/messages	Messages	创建消息，支持非流式和流式响应
POST	/v1/messages/count_tokens	Token 计数	计算 Messages 请求的输入 Token 数量
GET	/v1/models	模型列表	分页返回当前 API Key 可调用的 Anthropic 兼容模型
GET	/v1/models/{model_id}	模型详情	获取指定模型的信息和能力；ID 可以包含 /

请求与响应字段遵循 Anthropic 对应协议，接入方无需使用平台私有的响应包装结构。

请求头

请求头	必填	说明
X-Api-Key	是	平台 API Key。Anthropic SDK 的 api_key 参数会自动设置此头
anthropic-version	否	Anthropic 协议版本；未传时平台使用 2023-06-01
anthropic-beta	否	需要使用 Beta 协议能力时传入，平台会按原值转发
Content-Type	POST 请求是	使用 application/json

也可以使用 Authorization: Bearer sk_* 代替 X-Api-Key，但为了与 Anthropic SDK 的默认行为一致，推荐使用 X-Api-Key。

WARNING

同一个请求不能同时传入 Authorization 和 X-Api-Key，否则网关返回 400 Bad Request。

模型名称与分页

GET /v1/models 只返回当前 API Key 可访问且支持 Anthropic Messages 的模型。每个模型包含公开 id、展示名称、创建时间、最大输入/输出 Token 数以及 capabilities 能力声明；分页信息通过 has_more、first_id 和 last_id 返回。

模型列表支持游标分页：

Query 参数	类型	必填	说明
limit	integer	否	每页数量，默认 20，范围 1～1000
after_id	string	否	返回指定模型之后的数据
before_id	string	否	返回指定模型之前的数据

after_id 和 before_id 不能同时使用；游标指向的模型必须存在于当前可用模型列表中。

Token 计数

使用 SDK 计算 Messages 请求的输入 Token：

count = client.messages.count_tokens(
    model=os.environ["AIADP_MODEL_ID"],
    messages=[
        {"role": "user", "content": "你好，请介绍一下成都。"},
    ],
)

print(count.input_tokens)

Token 计数的输入结构与 Messages 协议保持一致。不同模型接入方式可能使用上游精确计数或平台估算，调用方应将结果用于容量预估，不应作为计费凭证。

流式响应

POST /v1/messages 支持 Anthropic SSE 流式事件。只有包含流式能力的模型可以使用 stream=True：

with client.messages.stream(
    model=os.environ["AIADP_MODEL_ID"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "介绍一下成都。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Token 计数不支持流式响应。流式传输异常时，服务会按 Anthropic SSE 格式发送 event: error。

错误响应

请求进入模型服务后，错误使用 Anthropic 兼容结构，并返回可用于排查的 request_id：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "model 字段不能为空"
  },
  "request_id": "req_01965de119207fe4aa382e6836c46f22"
}

HTTP 状态码	error.type	说明
400	invalid_request_error	请求体、必填字段或分页参数无效
401	authentication_error	API Key 缺失、格式错误或不可用；鉴权阶段可能由网关直接返回
403	permission_error	API Key 无权访问请求资源
404	not_found_error	模型不存在、未开放或不支持 Anthropic Messages
413	request_too_large	请求体超过 32 MiB
429	rate_limit_error	上游模型限流
502、504	api_error	上游响应无效或模型请求超时
529	overloaded_error	上游模型过载

接入说明

• 请求体必须是单个 JSON 对象，最大为 32 MiB。
• Messages 请求必须包含一个非空字符串 model 和一个正整数 max_tokens；两个字段都只能出现一次。
• Token 计数请求必须包含一个非空字符串 model，不要求 max_tokens。
• stream 如出现，必须是布尔值且只能出现一次；只有 Messages 会启用流式传输。
• 平台 API Key、Authorization 和 X-Api-Key 不会转发给上游模型。
• 成功响应的状态码、响应体与常用协议头由上游模型透传。
• Anthropic SDK 初始化参数及调用方式可参考官方 Python SDK。