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。

相关文档