API 参考/接口与请求示例/Messages

Messages

Anthropic Messages 兼容接口，Claude Code 和 Anthropic SDK 使用这个格式。请求必须带 max_tokens，system 是顶层字段，支持 thinking 和 cache_control 提示缓存。

POSThttps://api.wokey.ai/v1/messages· Anthropic Messages 兼容

本页内容expand_more

调用示例
请求头
请求参数
Wokey 的处理
响应
流式返回
错误格式

调用示例link

Anthropic SDK 和 Claude Code 的 Base URL 写 https://api.wokey.ai，不带 /v1，因为客户端会自己拼上 /v1/messages。

curl https://api.wokey.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

请求头link

Header	取值	说明
`x-api-key`必填	YOUR_API_KEY	你的 Wokey API Key。也可以改用 Authorization: Bearer YOUR_API_KEY，新版 Anthropic SDK 默认用这种写法。
`anthropic-version`	2023-06-01	可选。网关总是以 2023-06-01 访问上游，不传也可以。
`anthropic-beta`	string	可选。会合并转发给 Claude。上下文窗口为 1M 的模型不需要再加 context-1m beta。
`Content-Type`必填	application/json	请求体是 JSON。
`X-End-User-Id`	string	可选。你的终端用户 ID，1–128 个可见 ASCII 字符。传了之后，因反复违规触发的限制只作用于这个终端用户。

请求参数link

下表是网关读取或会改变行为的参数。其他 Anthropic 参数原样转发给 Claude。

参数	类型	说明
`model`必填	string	模型 ID，必须和模型列表里的 ID 完全一致。
`max_tokens`必填	integer	输出 token 上限，必须是正整数。缺少时返回 400，不会转发给上游。
`messages`必填	array	对话消息。每个 tool_use 都必须在下一条消息里有对应的 tool_result，否则网关直接返回 400。
`system`	string \| array	系统提示词，写在顶层，不放进 messages。
`thinking`	object	扩展思考设置。部分新模型只接受 adaptive 模式，网关会按模型规则调整不兼容的取值。output_config.effort 用来设置思考强度。
`cache_control`	object	写在内容块上的提示缓存断点，原样转发给 Claude。建议在 system 末尾和最后一条消息上打断点。
`stream`	boolean	为 true 时以 SSE 事件流返回。
`tools`	array	工具定义，tool_choice 同样支持。
`temperature`	number	只有 Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5、Haiku 4.5 接受，并会被限制在 0–1；更新的模型不转发。top_p、top_k 不转发给 Claude。
`metadata`	object	不会转发给上游。
`provider`	object	Wokey 扩展字段，用来指定或排除供应商，只用于路由，不会转发给上游。

Wokey 的处理link

网关在转发前后做的事，和直接调用官方接口不同的地方都写在这里。

Claude 模型直接按 Messages 格式转发，不做格式转换。网关会按模型规则调整少数参数（见上表），并在需要时自动添加提示缓存断点。
DeepSeek、Kimi、Grok 等提供原生 Messages 接口的模型也原样转发。GPT 等模型需要转换格式，这时 thinking 和 output_config 不生效，历史里的 thinking 块会被跳过。
document（PDF）内容块只对 Claude 模型有效。
发往 Claude 的请求体上限是 32 MiB，超出返回 413 request_body_too_large。
POST /v1/messages/count_tokens 用来统计输入 token 数。

同一个模型有多家供应商时，可以在请求体里加 provider 指定或排除供应商。指定供应商与顺序 →

响应link

JSON

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{ "type": "text", "text": "Hello! How can I help you today?" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 21,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 10
  }
}

响应头 x-wokey-request-id 是这次请求在 Wokey 的 ID，request-id 是上游 Anthropic 返回的 ID。排查问题时提供 x-wokey-request-id。
Claude 模型：input_tokens 不含缓存，缓存写入和读取分别在 cache_creation_input_tokens 和 cache_read_input_tokens 里。
GPT 等需要转换的模型：input_tokens 包含命中缓存的部分，cache_read_input_tokens 里重复给出命中的数量，这一点和 Anthropic 的口径不同。

流式返回link

事件顺序和 Anthropic 官方一致：message_start、content_block_*、message_delta、message_stop。

SSE

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"usage":{"input_tokens":21,"output_tokens":1}}}

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":"Hello!"}}

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

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

Claude 模型原样转发上游的事件流。
其他模型的事件由网关按同样的顺序生成：message_start 里的 usage 是 0，以 message_delta 里的 output_tokens 为准，工具调用块在最后给出。
流中出错时发送 event: error 事件。
等待上游首个字节时，网关会定期发送 SSE 注释行保持连接，客户端会自动忽略。

错误格式link

JSON

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required for Anthropic Messages requests. Add max_tokens or use /chat/completions for OpenAI-compatible requests."
  }
}

错误使用 Anthropic 格式，error.type 由状态码决定，例如 400 invalid_request_error、401 authentication_error、402 billing_error、429 rate_limit_error、529 overloaded_error。各状态码的含义和处理方法见错误码与排障 →