本文档详细说明通过 UniGateway 调用 Anthropic Messages API(POST /v1/messages)时的完整顶层请求参数定义、Messages 消息列表结构、多模态内容块格式及网关规范化规则。
章节导引#
本篇为 Anthropic Messages API 参考的第 2 章节:
- Messages 概述与快速开始
- 请求参数与消息格式(当前章节)
- 扩展推理 Thinking
- 提示词缓存 Prompt Caching
- 工具调用与 Computer Use
- 响应、流式与错误处理
顶层请求参数一览#
在向 POST https://api.unigateway.ai/v1/messages 发送 JSON 请求体时,支持以下顶层参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|
model | string | 是 | 无 | 目标模型标识符(如 claude-sonnet-5-5、claude-sonnet-4-6) |
messages | array | 是 | 无 | 对话历史与当前轮消息列表,详见下文 Messages 消息结构 |
max_tokens | integer | 是 | 无 | 单次响应生成的最大 Token 上限,必须为 >= 1 的整数 |
system | string | array | 否 | 无 | 系统提示词,支持纯文本字符串或结构化内容块数组 |
thinking | object | 否 | 视模型而定 | 扩展推理模式配置,详见 扩展推理 Thinking |
output_config | object | 否 | 无 | 控制推理强度(effort)与结构化输出格式(format) |
tools | array | 否 | 无 | 可供模型调用的工具定义列表,详见 工具调用与 Computer Use |
tool_choice | object | 否 | {"type":"auto"} | 工具选择策略(auto / any / tool / none) |
temperature | number | 否 | 1.0 | 采样温度(0.0 至 1.0);在 Claude 4.7+ / 5.x / 5.5 系列上已弃用 |
top_p | number | 否 | 无 | 核采样概率;在 Claude 4.7+ / 5.x / 5.5 系列上已弃用 |
top_k | integer | 否 | 无 | 采样候选数;在 Claude 4.7+ / 5.x / 5.5 系列上已弃用 |
cache_control | object | 否 | 无 | 顶层缓存控制配置,详见 提示词缓存 Prompt Caching |
stop_sequences | array[string] | 否 | 无 | 自定义停止序列数组,模型遇到匹配字符串时立即停止生成 |
stream | boolean | 否 | false | 是否启用 Server-Sent Events (SSE) 流式传输 |
metadata | object | 否 | 无 | 请求元数据(如 {"user_id": "cust_123"}) |
service_tier | string | 否 | "auto" | 算力容量档位("auto" / "standard_only") |
speed | string | 否 | "standard" | 推理速度模式("standard" / "fast") |
context_management | object | 否 | 无 | 上下文压缩与清理策略(Beta) |
anthropic_version | string | 否 | 无 | 协议版本,请求头未传时网关自动注入 2023-06-01 |
anthropic_beta | string | array | 否 | 无 | 特性标识,网关根据上游通道自动对齐 |
核心参数三维规范对比#
UniGateway 对所有入站请求严格对齐 Anthropic 官方规范与 Migration Guide,并在转发多云上游时提供确定性的协议规范化保障:
1. model(模型标识)#
| 场景 | Anthropic 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|
| 模型标识与回显 | 请求需指定有效的 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 Guide | UniGateway 处理规则 |
|---|
| 必填校验与取值下界 | 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 Guide | UniGateway 处理规则 |
|---|
| 数据类型支持 | 支持纯字符串(string)或文本内容块数组(array)。 | 两种格式均受完全支持。当使用内容块数组时,允许在系统提示块上配置 cache_control(详见 提示词缓存)。 |
| 多段文本合并 | 数组中可传入多个 type: "text" 块。 | 网关保持原样透传;若目标上游通道仅支持单一系统字符串,网关在出站时自动按标准换行符将其合并。 |
4. output_config(推理强度与结构化输出)#
| 场景 | Anthropic 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|
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 Guide | UniGateway 处理规则 |
|---|
| 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 的核心对话载体,由若干按时间顺序排列的消息对象组成。
消息对象字段#
| 字段名 | 类型 | 必填 | 说明 |
|---|
role | string | 是 | 消息发送方角色,必须为 "user" 或 "assistant" |
content | string | array | 是 | 消息内容,支持纯文本字符串或多模态内容块数组 |
内容块类型#
在多轮对话、多模态或工具调用场景下,content 推荐使用内容块数组(Content Blocks):
[
{
"role": "user",
"content": [
{
"type": "text",
"text": "请分析图中的图表数据。"
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAA..."
}
}
]
}
]
内容块规范化规则#
- 缺省类型补全:若客户端传入的内容块对象缺少
type 字段但包含 text 属性,网关自动补全 "type": "text",避免直接被上游校验打回。
- 助手预填(Assistant Prefill):
- 在 Claude 4.5 系列中,允许最后一条消息为
role: "assistant" 用于引导模型输出前缀(但当启用手动 Thinking 时官方不支持预填)。
- 在 Claude 4.6 及以上模型中,官方全面弃用末轮 Assistant Prefill;网关检测到时会自动将其重构为 User 提示或利用
output_config.format 进行引导,并在 x-gateway-modified-messages: prefill_migrated 中记录。
- 工具调用历史配对(
tool_use 与 tool_result):
- 历史消息中出现的
tool_use 块必须紧随其后由一条 role: "user" 消息提供对应 tool_use_id 的 tool_result 块。
- 若客户端因中断未能提供配对的
tool_result,网关在协议适配时会自动补齐空结果,确保上下文合法。
- 历史思考块与签名(
thinking / redacted_thinking):
- 多轮对话中包含此前轮次模型返回的
thinking 块时,必须连同其 signature 原样回传。
- 客户端回传时应保持思考块文本与签名完整,修改思考文本或伪造签名会导致上游签名校验失败(400)。
下一步#
- 深入了解 Claude 深度思考与推理强度配置:扩展推理 Thinking
- 配置断点以节省 API 调用成本:提示词缓存 Prompt Caching
- 为模型集成自定义工具与计算机操作能力:工具调用与 Computer Use