Anthropic 兼容-Messages
用 Anthropic Messages 协议调用模型。已有基于 Anthropic 官方 SDK 的代码,或在用 Claude Code 等工具,只需把 Base URL 和 API Key 换成平台的即可。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/messages |
| Base URL(SDK 用) | https://www.nextai-code.com(不带 /v1,SDK 会自动拼接 /v1/messages) |
| 鉴权 | x-api-key: YOUR_API_KEY 或 Authorization: Bearer YOUR_API_KEY(二选一) |
| 版本头 | anthropic-version: 2023-06-01(建议携带) |
| Content-Type | application/json |
快速示例
cURL
BASH
curl https://www.nextai-code.com/v1/messages \
-H "x-api-key: $NEXTAI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": "你是一名简洁严谨的 Go 工程师。",
"messages": [
{"role": "user", "content": "用三句话解释 Go 的 channel。"}
]
}'
Python(anthropic SDK)
PYTHON
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com",
)
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "用三句话解释 Go 的 channel。"}],
)
print(message.content[0].text)
Node.js(@anthropic-ai/sdk)
JAVASCRIPT
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.NEXTAI_API_KEY,
baseURL: "https://www.nextai-code.com",
});
const message = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "用三句话解释 Go 的 channel。" }],
});
console.log(message.content[0].text);
示例模型名仅作示意,实际可用模型以 模型列表(
GET /v1/models)为准。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
x-api-key |
二选一 | 平台 API Key |
Authorization |
二选一 | Bearer YOUR_API_KEY,与 x-api-key 等效 |
anthropic-version |
否 | 建议固定为 2023-06-01。官方 SDK 会自动携带 |
anthropic-beta |
否 | 开启 Anthropic Beta 功能,转发给模型服务商;是否生效取决于模型 |
x-session-id |
否 | 会话标识(也可用 x-conversation-id / x-client-session-id)。同一会话固定传同一个值,平台会尽量让这些请求保持在同一条服务线路上,有利于 Prompt 缓存命中 |
Anthropic SDK 的 Beta 接口会在 URL 上加 ?beta=true,平台支持该写法。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型 ID |
messages |
array | 是 | 对话消息,不能为空。role 为 user / assistant;content 为字符串或内容块数组(见下表) |
max_tokens |
integer | 否 | 最大输出 Token。平台不强制必填,未传时使用平台默认值;超过平台允许的上限时自动下调到上限,不会报错。建议显式传入。也兼容旧字段 max_tokens_to_sample |
system |
string / array | 否 | 系统提示词。数组形式为 text 内容块列表,可带 cache_control |
stream |
boolean | 否 | 是否以 SSE 流式返回,默认 false |
temperature |
number | 否 | 采样温度 |
top_p |
number | 否 | 核采样 |
top_k |
integer | 否 | Top-K 采样 |
stop_sequences |
string[] | 否 | 自定义停止序列 |
tools |
array | 否 | 工具定义,每项含 name、description、input_schema。也可传 Anthropic 服务端工具(如 web search),是否生效取决于模型 |
tool_choice |
object | 否 | 工具选择策略,如 {"type":"auto"}、{"type":"any"}、{"type":"tool","name":"..."},可带 disable_parallel_tool_use |
thinking |
object | 否 | 扩展思考:{"type":"enabled","budget_tokens":N},见 扩展思考 |
metadata |
object | 否 | 如 {"user_id":"..."},转发给模型服务商 |
context_management |
object | 否 | 转发给模型服务商,是否生效取决于模型 |
mcp_servers |
array | 否 | 转发给模型服务商,是否生效取决于模型 |
service_tier |
string | 否 | 平台不保证转发,请勿依赖 |
content 内容块
type |
主要字段 | 说明 |
|---|---|---|
text |
text、cache_control |
文本 |
image |
source |
图片,见 图片输入 |
tool_use |
id、name、input |
助手发起的工具调用(回传历史时使用) |
tool_result |
tool_use_id、content |
工具执行结果,放在 user 消息中 |
thinking |
thinking、signature |
思考块(多轮对话回传历史时原样带回) |
响应
非流式
JSON
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5-5",
"content": [
{"type": "text", "text": "channel 是 goroutine 之间传递数据的管道……"}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 28,
"output_tokens": 86,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 消息 ID |
type |
string | 固定 message |
role |
string | 固定 assistant |
model |
string | 实际响应的模型 |
content |
array | 输出内容块:text、thinking、tool_use 等 |
stop_reason |
string | end_turn、max_tokens、stop_sequence、tool_use 等 |
usage.input_tokens |
integer | 输入 Token(不含缓存部分) |
usage.output_tokens |
integer | 输出 Token |
usage.cache_creation_input_tokens |
integer | 写入缓存的输入 Token |
usage.cache_read_input_tokens |
integer | 命中缓存的输入 Token |
usage.cache_creation |
object | 按 TTL 拆分的缓存写入:ephemeral_5m_input_tokens、ephemeral_1h_input_tokens(模型服务商返回时才有) |
使用 Claude 模型时,响应字段与 Anthropic 官方接口一致。
流式
stream: true 时返回 text/event-stream,每个事件为 event: + data: 两行:
CODE
event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","model":"claude-sonnet-5-5","content":[],"usage":{"input_tokens":28,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"channel 是"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":86}}
event: message_stop
data: {"type":"message_stop"}
- 事件顺序:
message_start→ 若干组(content_block_start→content_block_delta… →content_block_stop)→message_delta→message_stop。以message_stop作为结束标志,没有[DONE]。 delta.type取值:text_delta(文本)、thinking_delta/signature_delta(思考)、input_json_delta(工具参数,partial_json需自行拼接)。- 用量:输出 Token 以最后一个
message_delta.usage.output_tokens为准;输入与缓存用量优先读message_delta.usage,没有时读message_start.message.usage。 - 流已开始后出错时,会收到
event: error,data为{"type":"error","error":{"type":"...","message":"..."}}。 - 可能收到以
:开头的保活注释行(如: PING),按 SSE 规范忽略即可。
进阶用法
扩展思考(Extended Thinking)
JSON
{
"model": "claude-sonnet-5-5",
"max_tokens": 16000,
"thinking": {"type": "enabled", "budget_tokens": 8000},
"messages": [{"role": "user", "content": "证明根号 2 是无理数。"}]
}
budget_tokens须小于max_tokens,具体约束以 Anthropic 官方为准。- 响应
content中会先出现{"type":"thinking","thinking":"...","signature":"..."}块,再出现text块。 - 多轮对话 / 工具调用续写时,需把上一轮的
thinking块(含signature)原样放回assistant消息。 - 若 模型列表 中有带
-thinking后缀的模型,直接调用它且不传thinking时,平台会自动开启扩展思考并把temperature固定为 1。需要精确控制思考预算时,请改用不带后缀的模型并显式传thinking。
工具调用(Tool Use)
PYTHON
tools = [{
"name": "get_weather",
"description": "查询城市天气",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
messages = [{"role": "user", "content": "上海今天天气怎么样?"}]
resp = client.messages.create(
model="claude-sonnet-5-5", max_tokens=1024, tools=tools, messages=messages,
)
if resp.stop_reason == "tool_use":
call = next(b for b in resp.content if b.type == "tool_use")
result = {"city": call.input["city"], "weather": "晴 22℃"} # 你的工具执行结果
messages += [
{"role": "assistant", "content": resp.content},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": call.id, "content": str(result)}
]},
]
final = client.messages.create(
model="claude-sonnet-5-5", max_tokens=1024, tools=tools, messages=messages,
)
print(final.content[0].text)
stop_reason 为 tool_use 表示模型要求调用工具;把 tool_result 回传后模型继续生成。
图片输入
JSON
{
"role": "user",
"content": [
{
"type": "image",
"source": {"type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..."}
},
{"type": "text", "text": "描述这张图片。"}
]
}
- 推荐统一使用
base64(media_type+data),所有模型都支持。 - Claude 模型还支持
{"type":"url","url":"https://..."},由模型服务商拉取图片;非 Claude 模型只支持 base64。
Prompt 缓存(cache_control)
在 system 或 messages 的内容块上加 cache_control:
JSON
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "<很长的系统提示 / 文档>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "根据文档回答:……"}]
}
{"type":"ephemeral"}默认缓存 5 分钟,可加"ttl":"1h";1 小时缓存是否支持取决于模型,可能需要anthropic-beta头。- 缓存单独计费:
cache_read_input_tokens(命中)与cache_creation_input_tokens(写入,含 5m / 1h 拆分)按各自的缓存价格计费,不按普通输入价计。具体价格见控制台模型价格页。 - 提高命中率:保持被缓存的前缀完全一致,并为同一会话携带固定的
x-session-id请求头。
非 Claude 模型能否走此接口
可以,但平台会做格式转换,能力有损:
- 会被转换的内容:文本、
system、tools/tool_use/tool_result、base64 图片、stop_sequences、temperature、top_p、max_tokens。流式事件同样按 Messages 格式返回。 top_k、metadata、tool_choice、thinking等 Anthropic 特有字段不保证生效;usage中的缓存字段取决于模型服务商是否返回。- 部分模型不支持此接口,调用会报错。需要完整 Anthropic 语义时请使用 Claude 模型;通用场景也可直接用 OpenAI 兼容-Chat。
错误
错误体为 Anthropic 格式(完整说明见 错误码):
JSON
{
"type": "error",
"error": {"type": "authentication_error", "message": "令牌无效或已过期,请检查令牌"},
"request_id": "..."
}
| HTTP | error.type |
场景 |
|---|---|---|
| 400 | invalid_request_error 或 new_api_error |
请求体不是合法 JSON、messages 为空、缺少 model、max_tokens 数值异常 |
| 401 | authentication_error |
API Key 无效或已过期,请到控制台「API Keys」页检查 |
| 402 | billing_error |
API Key 额度或账户余额不足 |
| 403 | permission_error |
调用 IP 不在 API Key 的白名单内、API Key 无权访问该模型、账户被禁用等 |
| 429 | rate_limit_error |
触发限流 |
- 鉴权、额度、限流等在请求发往模型前就被拦截的错误,响应头带
request-id;其中 400 / 401 / 402 / 403 / 404 / 413 / 422 还会带x-should-retry: false,官方 SDK 据此不重试。 - 部分参数校验错误的
error.type为new_api_error,请以 HTTP 状态码判断错误类别。 - 模型服务商返回的错误会尽量保留原始
error.type。
相关文档
- 计算 Token(
POST /v1/messages/count_tokens) - OpenAI 兼容-Chat
- 模型列表:带
x-api-key与anthropic-version请求GET /v1/models时返回 Anthropic 格式列表 - 获取与配置 API Key · Base URL 总览 · 错误码