Messages API (Anthropic)

与 Anthropic Messages 协议兼容。anthropic 官方 SDK、Claude Code 以及一切说 Anthropic 协议的客户端都走这个端点。

POST https://www.apigoto.com/v1/messages

🔑

鉴权头与 Anthropic 官方不同

官方用 x-api-key，APIGOTO 只读 Authorization: Bearer。用官方 SDK 时必须传 auth_token= 而不是 api_key=，环境变量用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY。填错的表现是稳定的 40001 api_key is required。详见鉴权与 API Key。

请求头

Authorizationstring必填

Bearer sk-rouertcode-…

Content-Typestring必填

application/json

anthropic-versionstring可选

官方 SDK 会自动带上（如 2023-06-01）。网关透传给上游，不做校验——手写请求时带不带都能通。

请求体

modelstring必填

平台模型 ID。不限于 Anthropic 家的模型——网关会做协议转换。

messagesarray必填

对话消息，role 只能是 user 或 assistant—— 系统提示不在这里，走独立的 system 字段。

max_tokensinteger必填

最大输出 token 数。Anthropic 协议里这是必填的，这与 Chat Completions 的可选语义不同，漏填会被上游拒绝。

systemstring | array可选

系统提示。可以是字符串，也可以是带 cache_control 的 block 数组。

streamboolean可选

默认 false。置 true 返回具名事件流。

temperature / top_p / top_knumber可选

temperature 取值 0–1（上限是 1，不是 2）。

stop_sequencesarray可选

停止序列。字段名与 OpenAI 的 stop 不同。

tools / tool_choicearray | object可选

工具定义。参数模式字段名是 input_schema，不是 parameters。

thinkingobject可选

扩展思考配置，如 {"type": "enabled", "budget_tokens": 4000}。需满足 budget_tokens < max_tokens ≤ 模型输出上限。 网关不校验这组关系，越界时请求照常转发，由上游厂商裁定并返回其原始错误。

响应

200 OK

{
  "id": "msg_a1b2c3",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    { "type": "text", "text": "你好！有什么可以帮你的吗？" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 11
  }
}

字段	说明
content	永远是数组，元素类型可能是 `text` / `tool_use` / `thinking`
stop_reason	`end_turn` / `max_tokens` / `stop_sequence` / `tool_use`
usage	只有 `input_tokens` 与 `output_tokens`，没有 total，需要自己相加

调用示例

messages.sh

curl https://www.apigoto.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIGOTO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "system": "你是一个简洁的助手。",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API 网关"}],
    "max_tokens": 200
  }'

messages.py

import os
from anthropic import Anthropic

client = Anthropic(
    # 注意：不带 /v1，SDK 自己会拼 /v1/messages
    base_url="https://www.apigoto.com",
    # 必须用 auth_token（发 Authorization: Bearer）
    # 不能用 api_key —— 那会发 x-api-key，网关不读该头
    auth_token=os.environ["APIGOTO_API_KEY"],
)

msg = client.messages.create(
    model="claude-sonnet-5",
    system="你是一个简洁的助手。",
    messages=[{"role": "user", "content": "用一句话解释什么是 API 网关"}],
    max_tokens=200,
)
print(msg.content[0].text)

messages.mjs

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  baseURL: 'https://www.apigoto.com', // 不带 /v1
  authToken: process.env.APIGOTO_API_KEY, // 不是 apiKey
})

const msg = await client.messages.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: '用一句话解释什么是 API 网关' }],
  max_tokens: 200,
})
console.log(msg.content[0].text)

流式事件

Anthropic 的事件流是具名事件，结构比 OpenAI 细：

message stream

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","role":"assistant","content":[]}}

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":"你好"}}

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":11}}

event: message_stop
data: {"type":"message_stop"}

事件	要点
message_start	带初始 `usage.input_tokens`
content_block_delta	增量。`text_delta` 取 `text`；`input_json_delta` 取 `partial_json`（工具参数）
message_delta	带最终 `stop_reason` 与累计 `output_tokens`
message_stop	终止事件。没有 `[DONE]`——收到它才算成功
ping	保活心跳，忽略即可

⚠️

按 index 分桶累积

一次回复可能包含多个 content block（一段文本 + 一个工具调用）。 index 标识是哪一个块的增量，混在一起拼接会得到乱码般的结果。

工具调用

tool_use 响应片段

{
  "content": [
    { "type": "text", "text": "我来查一下天气。" },
    { "type": "tool_use",
      "id": "toolu_abc123",
      "name": "get_weather",
      "input": { "city": "杭州" } }
  ],
  "stop_reason": "tool_use"
}

与 OpenAI 的差别：input 是已解析的对象，不是 JSON 字符串。回传结果时用 role: "user" 的消息，内容为 {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "..."}。

与 Chat Completions 的字段对照

Chat Completions	Messages
system 放在 messages 里	独立的 system 字段
max_tokens（可选）	max_tokens（必填）
stop	stop_sequences
finish_reason	stop_reason
tools[].function.parameters	tools[].input_schema
tool_calls[].function.arguments（字符串）	tool_use.input（对象）
data: [DONE]	message_stop

可能的错误

最高频的是 40001——用了 x-api-key 而非 Authorization: Bearer。其余错误码与其它兼容端点一致，见错误码总表。