Anthropic Messages API · Schema 完整参考

概览

1. 端点与认证

POST https://api.anthropic.com/v1/messages
x-api-key: <ANTHROPIC_API_KEY>
anthropic-version: 2023-06-01          // ★ 必填！显式版本头
content-type: application/json

2. 请求对象 MessagesRequest

type MessagesRequest = {
  // —— 必填 ——
  model: string,                          // "claude-sonnet-4-5" / "claude-opus-4-1" / "claude-haiku-4-5" ...
  messages: MessageParam[],               // 对话历史
  max_tokens: number,                     // ★ 必填！强制显式声明资源上限

  // —— 系统指令（顶层，不进 messages）——
  system?: string
        | { type: "text", text: string, cache_control?: CacheControl }[],

  // —— 采样 ——
  temperature?: number,                   // [0, 1]
  top_p?: number,
  top_k?: number,
  stop_sequences?: string[],

  // —— 流式 ——
  stream?: boolean,

  // —— 工具 ——
  tools?: ToolDefinition[],
  tool_choice?: { type: "auto" }
              | { type: "any" }
              | { type: "tool", name: string },   // 注意：结构化对象

  // —— 元信息 ——
  metadata?: { user_id?: string }
}

type CacheControl = { type: "ephemeral" }  // ★ 显式缓存断点（schema 级缓存建模）

3. 消息与内容块（判别联合）

Anthropic 的消息和内容块都是判别联合。只有 user 和 assistant 两种 role，系统指令在 system 顶层参数里，工具结果嵌在 user 消息的 content 数组里。

type MessageParam = {
  role: "user" | "assistant",             // ★ 只有两种 role
  content: string | ContentBlock[]        // 空字符串不允许；块可为空数组占位
}

4. 工具定义 ToolDefinition

type ToolDefinition = {
  name: string,                           // ^[a-zA-Z0-9_-]{1,128}
  description?: string,                   // 工具描述
  input_schema: JSONSchema,               // ★ 命名直白："输入的 schema"
  cache_control?: CacheControl            // 工具定义也可打缓存断点
}

{
  "name": "get_weather",
  "description": "查指定城市的当前天气。返回温度、天气状况、湿度。",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名，如 '北京' / '上海'"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度单位"
      }
    },
    "required": ["city"]
  }
}

5. 响应对象 Message

type Message = {
  id: string,                             // "msg_..."
  type: "message",
  role: "assistant",
  model: string,
  content: OutputBlock[],                 // ★ 必为数组（text + tool_use 可同轮并存）
  stop_reason: "end_turn" | "max_tokens" | "stop_sequence"
             | "tool_use" | "refusal" | "pause_turn",
  stop_sequence: string | null,
  usage: {
    input_tokens: number,
    output_tokens: number,
    cache_creation_input_tokens?: number, // ★ 缓存计费一级公民
    cache_read_input_tokens?: number
  }
}

6. 流式事件（显式状态机）

Anthropic 的流式是显式状态机——每个事件带 type，事件有明确生命周期，且内建 ping 心跳。

type StreamEvent =
  | { type: "message_start",       message: Message }           // 整体骨架先到
  | { type: "content_block_start", index: number,
      content_block: OutputBlock }                              // 块开始（含 index）
  | { type: "content_block_delta", index: number,
      delta: { type: "text_delta", text: string }
            | { type: "input_json_delta",
                partial_json: string }    // 工具入参分片
            | { type: "thinking_delta", thinking: string }
            | { type: "signature_delta", signature: string } }
  | { type: "content_block_stop",  index: number }              // 块边界明确！
  | { type: "message_delta",
      delta: { stop_reason, stop_sequence }, usage }            // 收尾语义 + 最终 usage
  | { type: "message_stop" }                                     // 终止
  | { type: "ping" }                                             // 保活心跳（协议内建）

7. 完整往返示例（工具调用最小环）

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,                                        // ★ 必填
  "system": "你是测试助手",                                  // 顶层，不进 messages
  "messages": [
    {"role": "user", "content": "跑一下测试"}
  ],
  "tools": [
    {
      "name": "run_tests",
      "description": "运行测试",
      "input_schema": {
        "type": "object",
        "properties": {"suite": {"type": "string"}}
      }
    }
  ]
}

{
  "id": "msg_001",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5-20250514",
  "content": [
    {"type": "text", "text": "我先运行测试"},
    {"type": "tool_use", "id": "toolu_xyz",
     "name": "run_tests", "input": {"suite": "all"}}            // ★ input 是对象！
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 95,
    "output_tokens": 15,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "跑一下测试"},
    {"role": "assistant", "content": [                          // assistant 原样回放
      {"type": "text", "text": "我先运行测试"},
      {"type": "tool_use", "id": "toolu_xyz",
       "name": "run_tests", "input": {"suite": "all"}}
    ]},
    {"role": "user", "content": [                              // ★ tool_result 嵌在 user 里
      {"type": "tool_result", "tool_use_id": "toolu_xyz",      // 与 tool_use.id 严格配对
       "content": "42 passed"}
    ]}
  ]
}

// 如果 ② 步模型还输出了 thinking 块（extended thinking 模式）：
{
  "id": "msg_001",
  "content": [
    {"type": "thinking", "thinking": "我需要先看看测试...", "signature": "sig_abc..."},
    {"type": "tool_use", "id": "toolu_xyz", "name": "run_tests", "input": {"suite": "all"}}
  ]
}

// 回填时，thinking 块（含 signature）必须原样保留：
{
  "messages": [
    {"role": "user", "content": "跑一下测试"},
    {"role": "assistant", "content": [
      {"type": "thinking", "thinking": "我需要先看看测试...", "signature": "sig_abc..."},  // ★ 原样保留
      {"type": "tool_use", "id": "toolu_xyz", "name": "run_tests", "input": {"suite": "all"}}
    ]},
    {"role": "user", "content": [
      {"type": "tool_result", "tool_use_id": "toolu_xyz", "content": "42 passed"}
    ]}
  ]
}

8. 错误与异常

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",   // 错误类型
    "message": "messages: required field"  // 错误消息
  }
}

9. 字段速查表（按字母序）

10. 引用与配套资料