Anthropic API/Anthropic Messages 请求参数与消息格式

Anthropic Messages 顶层请求参数、消息格式与内容块规范化完整参考。

Anthropic Messages 请求参数与消息格式

本文档详细说明通过 UniGateway 调用 Anthropic Messages API(POST /v1/messages)时的完整顶层请求参数定义、Messages 消息列表结构、多模态内容块格式及网关规范化规则。


章节导引

本篇为 Anthropic Messages API 参考的第 2 章节:

  1. Messages 概述与快速开始
  2. 请求参数与消息格式(当前章节)
  3. 扩展推理 Thinking
  4. 提示词缓存 Prompt Caching
  5. 工具调用与 Computer Use
  6. 响应、流式与错误处理

顶层请求参数一览

在向 POST https://api.unigateway.ai/v1/messages 发送 JSON 请求体时,支持以下顶层参数:

参数名类型必填默认值说明
modelstring是无目标模型标识符(如 claude-sonnet-5-5、claude-sonnet-4-6)
messagesarray是无对话历史与当前轮消息列表,详见下文 Messages 消息结构
max_tokensinteger是无单次响应生成的最大 Token 上限,必须为 >= 1 的整数
systemstring | array否无系统提示词,支持纯文本字符串或结构化内容块数组
thinkingobject否视模型而定扩展推理模式配置,详见 扩展推理 Thinking
output_configobject否无控制推理强度(effort)与结构化输出格式(format)
toolsarray否无可供模型调用的工具定义列表,详见 工具调用与 Computer Use
tool_choiceobject否{"type":"auto"}工具选择策略(auto / any / tool / none)
temperaturenumber否1.0采样温度(0.0 至 1.0);在 Claude 4.7+ / 5.x / 5.5 系列上已弃用
top_pnumber否无核采样概率;在 Claude 4.7+ / 5.x / 5.5 系列上已弃用
top_kinteger否无采样候选数;在 Claude 4.7+ / 5.x / 5.5 系列上已弃用
cache_controlobject否无顶层缓存控制配置,详见 提示词缓存 Prompt Caching
stop_sequencesarray[string]否无自定义停止序列数组,模型遇到匹配字符串时立即停止生成
streamboolean否false是否启用 Server-Sent Events (SSE) 流式传输
metadataobject否无请求元数据(如 {"user_id": "cust_123"})
service_tierstring否"auto"算力容量档位("auto" / "standard_only")
speedstring否"standard"推理速度模式("standard" / "fast")
context_managementobject否无上下文压缩与清理策略(Beta)
anthropic_versionstring否无协议版本,请求头未传时网关自动注入 2023-06-01
anthropic_betastring | array否无特性标识,网关根据上游通道自动对齐

核心参数三维规范对比

UniGateway 对所有入站请求严格对齐 Anthropic 官方规范与 Migration Guide,并在转发多云上游时提供确定性的协议规范化保障:

1. model(模型标识)

场景Anthropic 官方规范与 Migration GuideUniGateway 处理规则
模型标识与回显请求需指定有效的 Claude 模型 ID。网关按模型 ID 匹配代际能力配置;响应体与错误消息中的 model 字段保持为客户端请求时的原始名称,不返回底层云平台映射后的内部 ID(如 Bedrock ARN)。
后续同档模型代际继承同系列后续小版本或新代际默认沿用最新一代协议规范。对于高于 5.5 的同档位 Claude 模型(如 claude-opus-5-8、claude-opus-6、claude-sonnet-7、claude-haiku-6),网关默认应用对应档位 5.5 代际的能力与迁移规则;旧版 Claude 3.x 或仅含日期后缀的模型名则保持原样透传。

2. max_tokens(最大生成 Token 数)

场景Anthropic 官方规范与 Migration GuideUniGateway 处理规则
必填校验与取值下界max_tokens 为必填正整数,必须满足 >= 1。若请求缺失 max_tokens 或传入 <= 0,网关在入口校验时直接返回 400(type: invalid_request_error,code: integer_below_min_value)。
模型输出上限各模型有固定的最大生成限制(如 Claude 4.5/4.6 为 8,192 或 16,384;Claude 5.x/5.5 最高可达 64K / 128K)。若客户端传入的 max_tokens 超过目标模型在当前渠道支持的物理最大值,网关自动将出站参数限制在该模型上限内,避免因越界触发上游 400 阻断。

3. system(系统提示词)

场景Anthropic 官方规范与 Migration GuideUniGateway 处理规则
数据类型支持支持纯字符串(string)或文本内容块数组(array)。两种格式均受完全支持。当使用内容块数组时,允许在系统提示块上配置 cache_control(详见 提示词缓存)。
多段文本合并数组中可传入多个 type: "text" 块。网关保持原样透传;若目标上游通道仅支持单一系统字符串,网关在出站时自动按标准换行符将其合并。

4. output_config(推理强度与结构化输出)

场景Anthropic 官方规范与 Migration GuideUniGateway 处理规则
output_config.effort 档位控制模型的思考强度。Claude 4.5 仅 Opus 支持 3 档(low/medium/high);Claude 4.6 支持 4 档(新增 max);Claude 4.7+ / 5.x / 5.5 支持 5 档(low/medium/high/xhigh/max)。若客户端向仅支持 3 档的模型传入了 xhigh 或 max,或向仅支持 4 档的模型传入了 xhigh,网关在出站时安全降级至目标模型支持的最高档位(如 high 或 max),并在响应头 x-gateway-modified-output-config: effort_downgraded 中如实审计。
output_config.format 结构化输出官方支持传入 {"type": "json_schema", "schema": {...}} 以约束输出符合 JSON Schema。网关严格校验 JSON Schema 语法的合法性,移除上游不支持的正则环视(lookaround)断言,并在跨平台转发时转换为目标载体格式。

5. temperature / top_p / top_k(采样参数)

场景Anthropic 官方规范与 Migration GuideUniGateway 处理规则
Claude 4.5 / 4.6 约束temperature 与 top_p 不得同时传入(互斥校验)。若客户端同时传入了 temperature 与 top_p,网关在出站时自动剔除 top_p,保留 temperature 并通过 x-gateway-modified-sampling 提示。
Claude 4.7+ / 5.x / 5.5 弃用官方在新代际推理模型上全面弃用采样参数;请求体若包含任何非空采样字段,上游直接拒绝并返回 400。当请求发往 Claude 4.7+ / 5.x / 5.5 系列模型时,网关在出站前自动剥离 temperature、top_p 与 top_k,确保请求顺利完成。

6. 其它顶层参数

  • stop_sequences:自定义停止序列,数组内每项必须为非空字符串。遇到匹配项时,模型提前终止并返回 stop_reason: "stop_sequence"。
  • stream:布尔值。为 true 时启用 SSE 流式传输,详见 响应、流式与错误处理。
  • service_tier:可选 "auto" 或 "standard_only",用于控制上游算力通道的选择策略。
  • metadata:支持传入 {"user_id": "..."} 用于会话标识与风控审计。当上游账号配置了 metadata.user_id 归因补齐且客户端未传入时,网关基于会话亲和信号或账号 HMAC-SHA256 派生的确定性 UUIDv4 自动填入 metadata.user_id;在发往不支持该字段的云通道(如 AWS Bedrock)时在出站前自动剥离。

Messages 消息结构

messages 字段是 Anthropic API 的核心对话载体,由若干按时间顺序排列的消息对象组成。

消息对象字段

字段名类型必填说明
rolestring是消息发送方角色,必须为 "user" 或 "assistant"
contentstring | array是消息内容,支持纯文本字符串或多模态内容块数组

内容块类型

在多轮对话、多模态或工具调用场景下,content 推荐使用内容块数组(Content Blocks):

[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "请分析图中的图表数据。"
      },
      {
        "type": "image",
        "source": {
          "type": "base64",
          "media_type": "image/png",
          "data": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
      }
    ]
  }
]

内容块规范化规则

  1. 缺省类型补全:若客户端传入的内容块对象缺少 type 字段但包含 text 属性,网关自动补全 "type": "text",避免直接被上游校验打回。
  2. 助手预填(Assistant Prefill):
    • 在 Claude 4.5 系列中,允许最后一条消息为 role: "assistant" 用于引导模型输出前缀(但当启用手动 Thinking 时官方不支持预填)。
    • 在 Claude 4.6 及以上模型中,官方全面弃用末轮 Assistant Prefill;网关检测到时会自动将其重构为 User 提示或利用 output_config.format 进行引导,并在 x-gateway-modified-messages: prefill_migrated 中记录。
  3. 工具调用历史配对(tool_use 与 tool_result):
    • 历史消息中出现的 tool_use 块必须紧随其后由一条 role: "user" 消息提供对应 tool_use_id 的 tool_result 块。
    • 若客户端因中断未能提供配对的 tool_result,网关在协议适配时会自动补齐空结果,确保上下文合法。
  4. 历史思考块与签名(thinking / redacted_thinking):
    • 多轮对话中包含此前轮次模型返回的 thinking 块时,必须连同其 signature 原样回传。
    • 客户端回传时应保持思考块文本与签名完整,修改思考文本或伪造签名会导致上游签名校验失败(400)。

下一步