Claude Sonnet 5.5
Claude Sonnet 5.5 Messages API 参考：官方参数、自适应思考与工具调用之间的思考模式、提示缓存用量、响应字段，以及实测发现的兼容性限制。
使用 Anthropic Messages 格式调用 claude-sonnet-5-5。本文区分官方请求规范与兼容性测试中观察到的行为。部分高级选项目前尚未按规范生效；使用前请先查看相应限制。
查看模型页，了解当前输入、输出和缓存价格。
快速示例
curl https://api.seedrouter.ai/v1/messages \
-H "x-api-key: $SEEDROUTER_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Explain how a rainbow forms in three sentences."}]
}'POST /v1/messages 接受 x-api-key 或 Bearer 认证，并使用 anthropic-version: 2023-06-01。如某项功能的官方文档要求 beta 标头，请发送 anthropic-beta。凭证应保存在服务端代码中。
该模型也接受基本的 OpenAI Chat Completions（POST /v1/chat/completions）和 Responses（POST /v1/responses）请求。使用下述原生参数时，请采用 Messages 格式；OpenAI 格式转换并不涵盖 Anthropic 的所有功能。
官方参数规范
Sonnet 5.5 的上下文窗口为 1M token，同步请求的输出上限为 128000 token。Batch 专用的输出限制不适用于此端点。除非下表另有说明，应用不会为可选属性主动设置默认值。
| 参数 | 类型 / 必填性 | 官方约束与默认值 |
|---|---|---|
model | string，必填 | claude-sonnet-5-5。 |
max_tokens | integer，必填 | 0–128000，包括思考 token。按官方定义，0 会写入提示缓存而不生成输出；请查看下文的当前限制。 |
messages | object 数组，必填 | 至少一条对话消息，最多 100000 条。每条包含 role 和 content；content 可以是字符串或内容块数组。普通对话轮次使用 user/assistant。对话中途的 system 消息须遵循官方位置规则。 |
system | string 或文本块数组 | 顶层系统指令。文本块可以包含缓存断点。 |
thinking | object | 默认值：{"type":"adaptive"}。另一种支持的模式为 {"type":"between_tools"}。手动思考预算和 disabled 均会被拒绝。 |
thinking.display | enum | 仅适用于自适应模式：omitted（默认）或 summarized。省略思考摘要不代表禁用思考。 |
thinking.block_binding | object，beta | 仅适用于自适应模式。需要 thinking-binding-controls-2026-08-01；请遵循官方的思考内容保留规范。 |
output_config.effort | enum 或 null | low、medium、high、xhigh、max；默认 high。Null 保留默认行为。 |
output_config.format | object 或 null | JSON 结构化输出：{"type":"json_schema","schema":{...}}。请使用受支持的 JSON Schema 子集。 |
stream | boolean | 默认 false；true 返回 SSE 事件。 |
stop_sequences | string 数组 | 按官方定义，遇到匹配字符串时停止生成。当前兼容性测试中，该行为未生效。 |
temperature | number 或 null | 仅为兼容性接受 1；请省略此参数。其他非 null 值会被拒绝。 |
top_p | number 或 null | 仅为兼容性接受 0.99–1；请省略此参数。 |
top_k | 不接受非 null 值 | 不支持采样设置；请省略此属性。 |
tools | object 数组 | 客户端工具包含 name、input_schema，以及可选的描述和严格模式设置。服务端工具使用带版本号的官方定义。 |
tool_choice | object | auto（默认）或 none。any 和指定名称的强制 tool 均会被拒绝。auto 可以包含 disable_parallel_tool_use。 |
metadata.user_id | string 或 null | 最多 512 个字符；请使用不透明标识符。 |
cache_control | object 或 null | type: "ephemeral"；ttl: "5m"（默认）或 "1h"。Sonnet 5.5 至少需要 512 个可缓存 token。官方 API 也支持内容块级别的缓存断点。 |
diagnostics | object 或 null | previous_message_id：最多 256 个字符的字符串，或 null。用于请求缓存分歧诊断信息。 |
service_tier | enum | auto（默认）或 standard_only。 |
speed | enum 或 null | 省略此参数，或使用 standard / null。Sonnet 5.5 不支持 fast。 |
inference_geo | string 或 null | 官方默认值来自账户设置。请求被接受本身不能证明处理发生在指定地区。 |
fallbacks | string、object 数组或 null，beta | "default" 或最多三个回退项。每项必须包含 model；可选覆盖项为 max_tokens、thinking、output_config 和 speed。请参阅下文的回退规则。 |
fallback_credit_token | string、object 或 null | 来自先前拒绝响应的抵扣令牌，或 {"token":"...","mode":"strict"}。对象形式需要 fallback-credit-2026-07-01；mode 为 strict（默认）或 best_effort。不能与非 null 的 fallbacks 值同时使用。 |
container | string、object 或 null | 容器 ID，或包含可选 id 和 skills（最多 20 个）的容器配置。Skills 使用官方的类型、标识符和版本字段。 |
context_management | object 或 null | 官方上下文编辑配置，包括 edits；null 表示不设置此项。仍须遵循模型专属的编辑兼容性要求。 |
mcp_servers | object 数组 | 官方 MCP 服务器定义，须满足相应 beta 版本和服务器认证要求。空数组探测不能验证远程 MCP 执行。 |
compaction | object 或 null，beta | {"type":"summarize"}，配合 compact-2026-09-04 使用；null 表示不启用压缩。启用压缩后，不能同时设置非 null 的 context_management、停止序列或结构化输出格式。带签名的压缩行为未通过当前测试。 |
messages[].output_config.effort | enum，beta | 在 system 消息上设置逐消息思考强度；需要 mid-conversation-output-config-2026-07-01。仅设置思考强度的 system 消息可以出现在任何位置；带正文的 system 消息组须遵循官方位置规则。在 between_tools 模式下不得通过它更改思考强度。 |
between_tools 只接受自身的 type 属性，思考强度仅可使用 low、medium 或 high。不要同时发送 display、budget_tokens 或 block_binding。示例：
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"thinking": {"type": "between_tools"},
"output_config": {"effort": "medium"},
"messages": [{"role": "user", "content": "Explain this concept briefly."}]
}不支持 assistant 预填充。要继续 pause_turn，请原样回传返回的服务端工具 assistant 内容。压缩用于总结已有历史，不属于 assistant 预填充。请完整保留思考块及其签名；不要在模型间转移它们，也不要在未遵循官方绑定规则的情况下修改前文历史。
在原生 Claude API 上，计算机使用功能需要 computer_toolset_20260801；computer_20251124 会被拒绝。使用 claude-opus-4-8、claude-opus-4-7 或 claude-sonnet-5 的 Advisor 配置也会被此执行模型拒绝。
回退请求字段
官方 fallbacks beta 功能会对符合条件的分类器拒绝进行重试。它不会重试速率限制、过载或服务器错误，重试也可能仍被拒绝。发送 server-side-fallback-2026-07-01 标头可使用 "default" 或显式列表；server-side-fallback-2026-06-01 只支持列表。其他日期版本会被拒绝。
显式列表最多包含三个条目，模型各不相同，且均不能与请求的模型相同。允许的目标模型来自 beta Models API 的 allowed_fallback_models。每项只允许包含 model、max_tokens、thinking、output_config 和 speed；覆盖值必须对目标模型有效。发生相应回退时，七月版 beta 会将 Sonnet 5.5 的 between_tools 转换为 Sonnet 5 的 disabled，并省略 display。使用六月版 beta 时，需要自行提供 Sonnet 5 的思考模式覆盖值。
fallback_credit_token 用于遭拒后另行发起的重试。字符串形式采用严格抵扣；对象形式可额外指定 mode。在 strict 模式下，抵扣失败会拒绝重试。在 best_effort 模式下，抵扣令牌处理失败时可能按正常价格继续执行，并记录在 usage.fallback_credit 中；令牌格式错误或与 fallbacks 同时使用仍会失败。抵扣还须满足官方抵扣指南中关于合格请求、账户、工作区、平台及五分钟时限的要求。
一项无害请求使用 fallbacks: "default"、七月版 beta 标头和 speed: "standard"，返回了预期文本。这仅能证明请求被接受：此处尚未端到端验证回退执行或抵扣令牌的兑换。
媒体和工具输入
图像使用用户消息中的 image 块，PDF 使用 document 块。官方支持的来源类型包括公开 URL，以及带相应 MIME 类型的 base64。兼容性检查使用了 base64 PNG 和单页 base64 PDF，并核对了回答内容；并未覆盖所有 URL、文件大小、图像分辨率或 PDF 页数边界。
客户端工具采用标准的 tool_use → tool_result 交互。请保留工具调用 ID，并在用户消息中返回结果。严格模式工具示例成功，只能验证该示例的参数，不能验证所有受支持的 JSON Schema 关键字。
响应
非流式响应包含 id、type: "message"、role: "assistant"、model、content、stop_reason、stop_sequence 和 usage，以及可选的官方字段，例如 container、diagnostics、context_management、stop_details 和 beta 响应字段。内容可以包含文本、思考、工具调用、工具结果或其他官方内容块类型；不要假定第一个块就是文本。
流式响应需要处理 message_start、content_block_start、content_block_delta、content_block_stop、message_delta 和 message_stop。流中也可能发生错误。用量可以包含普通输入/输出 token、思考 token 明细、缓存读取，以及分别统计的 5 分钟 / 1 小时缓存写入量。
官方分类器拒绝会返回包含 stop_reason: "refusal" 和 stop_details 的正常响应，而不是 HTTP 错误。在回退响应中，model 标明实际作答的模型，fallback 内容块标记模型切换，usage.iterations 描述各次尝试。请检查这些字段，不要假定响应由请求中指定的模型生成。这些响应行为在此处仍未经验证。
Messages 错误采用 {"type":"error","error":{"type":"...","message":"..."}} 格式。失败的请求不收费。
兼容性验证：2026-10-01
| 结果 | 已检查的行为 |
|---|---|
| 观察到正常工作 | 基本文本、普通多轮上下文回忆、不冲突的字符串/内容块形式系统指令、流式响应、自适应和工具调用之间的思考请求、JSON 输出、auto/none 工具、一项严格模式工具调用、工具结果回传、base64 图像/PDF 输入，以及 5m/1h 缓存写入/读取用量。 |
| 按模型规范拒绝 | 无效输出 token 预算、已移除的采样设置、手动/禁用思考、无效的 between-tools 参数组合、强制工具调用、assistant 预填充、旧版计算机工具，以及超长的 metadata ID。 |
| 请求被接受，效果尚未证实 | 全部五档思考强度、思考摘要、绑定设置、metadata、服务等级、地区选择、诊断、空的上下文编辑列表、null 容器、空 MCP 列表，以及计算机工具集声明。工具集声明被接受不代表计算机使用功能执行成功。 |
| 已知不一致 | max_tokens: 0 返回 400。停止序列请求返回了停止字符串及其后续文本。按需压缩返回了普通文本，而非带签名的压缩块。 |
| 仍需调查的其他行为 | 一项逐消息思考强度请求未能回忆先前的值；一项系统/用户指令冲突探测遵循了用户指令。这些结果不能证明每条系统提示或多轮请求都会失败。 |
Beta 工具执行、真实 MCP 连接、Files API 引用、数据地域驻留、思考签名回传、完整上下文/输出上限、媒体边界情况，以及拒绝/回退行为均尚未经端到端验证。HTTP 200 和返回的模型名称不能证实实际运行的是哪个模型，也不能证明所有传入选项都已生效。