跳转到主要内容
POST

简介

Claude 原生的消息接口,适用于 Claude Code 等原生 Anthropic 客户端。该接口遵循 Anthropic 的 API 规范,提供完整的 Claude 模型功能支持,包括扩展思考(Extended Thinking)、工具调用等高级特性。
如果您使用 OpenAI 兼容的客户端(如 OpenAI SDK),建议使用 /v1/chat/completions 接口。

认证

string
必填
Bearer Token,如 Bearer sk-xxxxxxxxxx

请求参数

string
必填
Claude 模型标识,支持的模型包括:
  • claude-fable-5-1 - Claude Fable 5.1(最新,最强能力,适合最高难度推理与长程 Agent)
  • claude-opus-5-5 - Claude Opus 5.5(最新 Opus,复杂 Agent 与编码场景)
  • claude-sonnet-5-5 - Claude Sonnet 5.5(最新 Sonnet,速度与智能兼顾)
  • claude-haiku-5-5 - Claude Haiku 5.5(最新 Haiku,速度最快、成本最低)
  • claude-fable-5 - Claude Fable 5
  • claude-opus-5 - Claude Opus 5
  • claude-sonnet-5 - Claude Sonnet 5
  • claude-opus-4-8 - Claude Opus 4.8
  • claude-opus-4-7 - Claude Opus 4.7
  • claude-opus-4-6 - Claude Opus 4.6
  • claude-sonnet-4-6 - Claude Sonnet 4.6(平衡性能)
  • claude-opus-4-5-20251101 - Claude Opus 4.5
  • claude-haiku-4-5-20251001 - Claude Haiku 4.5
  • claude-sonnet-4-5-20250929 - Claude Sonnet 4.5
  • claude-sonnet-4-20250514 - Claude Sonnet 4
  • 其他 Claude 系列模型
官方文档:模型总览 | 迁移指南:Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5
array
必填
对话消息列表,每个元素包含 role(user / assistant,部分新模型还支持 system,见下文)和 content。content 可以是字符串或媒体内容数组。模型支持:全部 Claude 模型均支持。对话中途的 system 消息(role: "system")在 messages 数组中间插入 {"role": "system", "content": "..."},可以在对话进行中追加运营方指令(如切换模式、注入状态),不会让前面已缓存的对话前缀失效。相比修改顶层 system,这种方式更省缓存,也更不容易被提示词注入利用。已正式发布,无需 beta 请求头。官方支持的平台为 Claude API、Amazon Bedrock、Google Cloud。官方文档:Mid-conversation system messages位置规则(在支持的模型上,违反也会返回 400):
  • 不能作为 messages[0];
  • 必须紧跟在一条 user 消息之后(或紧跟在以服务端工具调用结尾的 assistant 消息之后);
  • 必须是数组的最后一条,或者后面紧跟一条 assistant 消息;
  • 不能插在 assistant 的 tool_use 和对应的 tool_result 之间(Agent 循环中可放在携带 tool_result 的 user 消息之后)。
顶层 system 字段在所有模型上都可以正常使用。role: "system" 消息只是对它的补充,适合多轮对话中途需要追加指令的场景。通过 /v1/chat/completions(OpenAI 兼容格式)传入的 system 消息,会被合并到 Claude 的顶层 system 字段,不走这套规则。
助手预填充(assistant prefill):以 role: "assistant" 结尾来预填模型回复,在 claude-sonnet-4-6、claude-opus-4-6 及之后的所有模型上返回 400(含 claude-sonnet-5、claude-sonnet-5-5、claude-opus-5-5、claude-fable-5-1、claude-haiku-5-5,Haiku 5.5 关闭思考时也不行);开启思考时在任何模型上都不可用。请改用 output_config.format(结构化输出)或系统提示词约束输出格式。
number
必填
最大生成 token 数,控制回复长度。必须大于 0。思考 token 也计入本上限,开启思考时需预留足够额度,否则会出现 stop_reason: "max_tokens" 截断。模型支持(各模型单次请求的输出上限不同)
string|array
系统提示词,可以是字符串或媒体内容数组。用于设定模型的行为和角色。模型支持:全部 Claude 模型均支持,无差异。
number
默认值:"1.0"
随机性控制,0-1,值越高回复越随机。模型支持
claude-haiku-5-5 的校验更严格:temperature 只接受 1,其他任何值(包括 0)都返回 400;同时传 temperature 和 top_p 也会返回 400。原来在 Haiku 4.5 上用 temperature: 0 做分类的场景,请删掉该参数,改用结构化输出(output_config.format)约束结果。官方文档:Claude Haiku 5.5 迁移指南
所有 Claude 4 及以上模型:temperature 与 top_p 不能同时传入,二选一。
number
默认值:"1.0"
核采样参数,0-1,控制生成的多样性。模型支持
number
Top-K 采样参数。模型支持
boolean
默认值:"false"
是否启用流式输出,返回 SSE 格式的分片数据。模型支持:全部 Claude 模型均支持,无差异。
官方 SDK 在 max_tokens > 21333 时强制要求流式,否则会因 HTTP 超时报错(客户端校验,非服务端限制)。开启思考、或使用较大 max_tokens 时建议一律启用。
array
停止序列列表,当模型生成这些序列时停止生成,此时响应的 stop_reason 为 stop_sequence。模型支持:全部 Claude 模型均支持,无差异。
array
工具定义列表,支持函数工具和网页搜索工具。模型支持:全部 Claude 模型均支持,无差异(具体可用的服务端工具类型按模型代际有别)。
object
工具选择策略,控制模型如何使用工具,可选 auto(默认)、none、any、tool。模型支持
在不支持强制调用的模型上,可以改用 {"type": "auto"},并在提示词里明确要求使用哪个工具;同时在工具定义上加 strict: true,保证参数符合 schema。auto 不保证一定会调用工具,请在代码里检查,没调用就重试。如果强制调用只是为了拿到 JSON,直接改用结构化输出(output_config.format)。官方文档:Forced tool use is not supported | Strict tool use
object
扩展思考配置,启用 Claude 的深度推理能力。模型支持(不同代际差异最大的参数,请对照下表)
从 Claude Opus 4.7 起,以及 Fable、Opus 5 / 5.5、Sonnet 5 / 5.5、Haiku 5.5 全系,{"type": "enabled", "budget_tokens": N} 一律返回 400,请改用 {"type": "adaptive"} + output_config.effort 控制思考深度。budget_tokens 只在 Claude 4.5 及更早的模型上必需;Opus 4.6 / Sonnet 4.6 上已弃用,但暂时还能用。
display 的默认值因模型而异:Claude Fable 5.1、Fable 5、Opus 5.5、Opus 5、Sonnet 5.5、Sonnet 5、Haiku 5.5、Opus 4.8、Opus 4.7 默认为 "omitted";Claude Opus 4.6、Sonnet 4.6 及更早的模型默认为 "summarized"。在前一类模型上需要向用户展示思考过程时,必须显式设置 "display": "summarized",否则拿到的思考内容为空字符串。
Fable 5.1、Opus 5.5、Sonnet 5.5 的响应结构变化:模型在两次工具调用之间写的较长进度说明,会以 thinking 块的形式返回,而不再是 text 块。在默认的 display: "omitted" 下这些块内容为空,所以只渲染 text 块的客户端在长 Agent 回合中会长时间没有输出。请按块的 type 解析响应,不要依赖块的位置;多轮工具调用时,把 thinking 块原样回传。官方文档:Thinking | 控制思考展示(display) | 进度更新(progress updates) | 保留思考块
object
Claude Sonnet 5.5 专属。在 claude-sonnet-5-5 上,{"type": "disabled"} 会返回 400,想关闭思考时请改用 {"type": "between_tools"}。这是该模型思考的最低档:模型不做扩展思考,在两次工具调用之间写的简短进度说明会以 thinking 块返回,并且带有摘要文本(不像 adaptive 默认返回空内容)。不需要 beta 请求头。使用限制(违反任意一条都返回 400 invalid_request_error):
官方建议优先用自适应思考 + effort: "low":在 low 档位下模型思考很短,简单请求通常直接跳过思考。确实需要关闭思考时,再用 between_tools。如果你的代码会把同一个请求体重试到其他模型(如降级、路由),记得先去掉 between_tools。官方文档:Turn off up-front thinking(Sonnet 5.5 迁移指南) | Running without up-front thinking
object
输出配置,用于控制模型的思考深度与 token 消耗。
该参数影响回复中的所有 token(正文、工具调用、思考),因此不需要开启思考也能生效。模型支持
在 Claude Opus 5 和 Haiku 5.5 上,effort 为 "xhigh" 或 "max" 时无法关闭思考,此时同时传 "thinking": {"type": "disabled"} 会返回 400。需要关闭思考时,请把 effort 设为 "high" 或更低档位。Sonnet 5.5 的 between_tools 规则相同。Opus 5.5 在任何档位下都不能关闭思考,只能通过调低 effort 来减少思考。
官方文档:Effort | Sonnet 5.5 推荐档位 | Opus 5.5 迁移指南
object
请求元数据,用于追踪和调试。模型支持:全部 Claude 模型均支持,无差异。
string
默认值:"auto"
服务层级,控制本次请求可使用的容量类型。可选 auto(优先使用 Priority Tier 容量,不足时回落标准容量)、standard_only(仅使用标准容量)。响应的 usage.service_tier 会返回本次请求实际命中的层级。详见 服务层级(Service Tier)。
array
MCP(Model Context Protocol)服务器配置。需与 tools 中的 mcp_toolset 条目配合使用,二者缺一会报参数校验错误。
object
上下文管理配置,控制对话上下文的处理方式。
object
开启自动缓存。放在请求体顶层时,系统会自动把缓存断点打在最后一个可缓存块上,随对话增长自动后移,无需手动维护标记。详见 Prompt Caching。
旧版 Amazon Bedrock 集成(InvokeModel / Converse,覆盖 Opus 4.6 及更早的模型)不支持顶层 cache_control,传入会返回 400。这类模型请改用内容块级的显式断点,详见 各上游平台支持情况。

参数支持速查表

各参数在本接口支持的 Claude 模型上的可用情况汇总(✅ 支持 / ⚠️ 有条件 / ❌ 传入即 400): 最新一代模型 上一代及更早模型
上表依据 Anthropic 官方 API 文档整理(核对日期:2026-10-14),各模型细则见官方迁移指南:Fable 5.1 · Opus 5.5 · Sonnet 5.5 · Haiku 5.5。模型能力随版本迭代变化,具体以 模型广场 与实际调用返回为准。

Prompt Caching(提示词缓存)

Prompt Caching 允许缓存经常使用的上下文内容,显著降低成本并提升响应速度。官方文档:Prompt caching有两种启用方式,可以单独使用也可以组合:

缓存控制参数

两种写法的字段结构相同。字段说明:

自动缓存(顶层 cache_control)

把 cache_control 直接写在请求体根级别即可,不需要在任何内容块上打标记:
断点会随对话增长自动后移,每次请求缓存到最后一个可缓存块为止,之前的内容从缓存读取:

各上游平台支持情况

自动缓存(顶层 cache_control)在绝大多数平台可用,唯一的例外是旧版 Amazon Bedrock 集成: 所以在 AWS 上支不支持,取决于走哪条 Bedrock 集成,而集成又由模型决定。按模型对照:
不确定某个模型实际走哪条链路时,可用同一前缀连发两次请求,看第二次响应的 usage.cache_read_input_tokens 是否大于 0 来验证缓存是否真的命中。

显式断点(内容块级 cache_control)

标记在 system 数组元素或 messages 的 content 数组元素内部:

两种写法组合使用

自动缓存与显式断点可以同时用。典型场景是用显式断点固定住系统提示词,让自动缓存负责不断增长的对话部分:
组合时的规则与边界情况:
  • 自动缓存会占用 4 个断点名额中的 1 个
  • 已有 4 个显式断点时再传顶层 cache_control,返回 400(没有剩余名额)
  • 最后一个块已有相同 ttl 的显式 cache_control 时,自动缓存为空操作,不额外占名额
  • 最后一个块已有不同 ttl 的显式 cache_control 时,返回 400
  • 最后一个块不适合作断点时,系统会自动向前回溯寻找最近的可用块;找不到则跳过缓存(不报错)

缓存机制

  • 缓存断点:单次请求最多可标记 4 块内容。每个断点各自写入一条缓存,缓存的是「从开头到该块为止」的完整前缀
  • 缓存命中:请求时系统在断点处比对前缀,未命中则逐块向前回溯查找,回溯窗口最多 20 个内容块;超出窗口的旧缓存不会被命中,这种情况建议在更靠前的位置增加一个断点
  • 缓存阈值:内容长度低于模型的最小可缓存长度时不会被缓存(不报错,直接按普通输入处理),各模型阈值见下表
  • 缓存时效:5 分钟(默认)或 1 小时
  • 成本:缓存读取为普通输入价格的 10%(便宜 90%);缓存写入有溢价——5 分钟缓存为 1.25 倍,1 小时缓存为 2 倍

各模型最小可缓存长度

使用场景

  1. 长文档分析:将大型文档缓存在 system 中,多次提问
  2. 代码库理解:缓存代码上下文,进行多轮代码分析
  3. 知识库问答:缓存知识库内容,提供快速查询
  4. 多轮对话:缓存历史对话,保持上下文连贯性

基础示例

高级功能

系统提示词

系统提示词可以设置为字符串或媒体内容数组:

扩展思考(Extended Thinking)

Claude 支持扩展思考,模型会在给出最终答案前先进行内部推理。不同代际的写法不同(官方文档:Thinking):
  • budget_tokens 只用于旧模型,最小 1024,且必须小于 max_tokens
  • 开启思考时,旧模型上的 temperature / top_k 不可用,top_p 只能取 0.95 ~ 1;新模型直接不要传这几个采样参数
  • 思考 token 计入 max_tokens,请预留足够额度(长程 Agent 编码可从 64K 起步)
  • 新模型的 display 默认为 "omitted",想看到思考内容需显式设置 "display": "summarized";流式和非流式都会返回 thinking 块
  • 多轮工具调用时,请把 thinking 块(包括 signature)原样回传,不要修改或删除

工具调用(Tools)

支持函数工具和网页搜索工具:

tool_choice 参数详解

tool_choice 控制模型如何使用工具:
any 和 tool 在 claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5 上会返回 400,替代写法见上方 tool_choice 参数说明。disable_parallel_tool_use: true 配合 auto 仍然可用,含义是「最多调用一次」。
示例:

文本编辑器工具(Text Editor Tool)

Claude 官方预定义的文件读写工具,用于让模型查看和修改本地文件,常见于代码调试、重构与文档编辑场景。它由 Anthropic 定义 schema、由你的程序在本地执行:模型返回 tool_use 块,你执行对应的文件操作后,再把结果作为 tool_result 回传。 声明方式无需 input_schema,只需 type 与 name:
模型会在 tool_use.input.command 中返回以下命令之一:
path 由模型生成,属于不可信输入。执行前务必将其解析为规范路径并校验仍在项目根目录内,防止 ..、软链接等路径穿越;出错时返回 is_error: true 的 tool_result,模型可据此重试。
旧版本 text_editor_20250124 + str_replace_editor 在 Claude 4 及以上模型不再支持,undo_edit 命令也已移除。完整命令说明与各语言参考实现见 Anthropic 官方文档:Text editor tool。

服务层级(Service Tier)

Anthropic 提供三种服务层级,用于在可用性、性能与成本之间取舍:Standard(默认,尽力而为)、Priority Tier(优先调度,降低高峰期 overloaded 报错)、Batch(异步批处理)。 通过 service_tier 参数控制本次请求可用的容量:
响应的 usage.service_tier 会返回本次请求实际命中的层级(如 "priority" / "standard"),可据此判断调度结果:
Priority Tier 的容量承诺已停止新购,仅存量合约用户可继续使用至合约到期;其余账号请求实际都走标准容量。另外 Priority Tier 不覆盖 claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-opus-5、claude-sonnet-5,请求这些模型时指定 Priority Tier 会校验失败。
service_tier 为 Anthropic 官方参数,本平台透传至上游,实际调度结果以响应中的 usage.service_tier 为准。完整说明见官方文档:Service tiers。

多模态输入(图像)

支持在消息中包含图像:

Prompt Caching(提示词缓存)

通过缓存常用的上下文内容,可以显著降低成本和提升响应速度。
首次请求响应:
5分钟内再次请求(不同问题,相同 system):
缓存要点:
  • 内容必须 ≥ 1024 tokens(Claude Sonnet 4.5)才会触发缓存
  • 不填 ttl 时缓存在 5分钟内有效
  • ttl: "1h" 时缓存在 1小时内有效
  • 缓存读取成本比正常输入便宜 90%;缓存写入有溢价(5 分钟 1.25 倍、1 小时 2 倍)
  • 单次请求最多可标记 4 块内容,每个断点各自写入一条缓存
  • 缓存基于内容完全匹配,任何改动都会导致缓存失效
最佳实践:
  • 将不变的长上下文(文档、代码库等)放在 system 中并启用缓存
  • 对于长期稳定的内容,使用 1 小时缓存(ttl: "1h")
  • 对于频繁变化的内容,使用默认的 5 分钟缓存(不填 ttl)
  • 多轮对话时,可以缓存历史对话内容
  • 定期监控 cache_creation_input_tokens 和 cache_read_input_tokens 以优化成本

响应格式

使用缓存时的 usage 字段:
  • input_tokens: 当前请求的非缓存输入 tokens
  • cache_creation_input_tokens: 首次缓存创建的 tokens(仅首次请求时有值)
  • cache_read_input_tokens: 从缓存读取的 tokens(缓存命中时有值)
  • output_tokens: 生成的输出 tokens

错误处理

系统会对上游 Claude API 的错误进行统一处理,返回标准化的错误响应格式。 错误响应示例:

与 /v1/chat/completions 的对比

  • 如果您使用 Claude Code 或其他 Anthropic 原生客户端,建议使用 /v1/messages 接口
  • 如果您使用 OpenAI SDK 或需要兼容 OpenAI 格式,建议使用 /v1/chat/completions 接口
  • 两个接口的功能基本相同,主要区别在于请求/响应格式

注意事项

  • max_tokens 是必填参数,必须大于 0
  • messages 数组不能为空
  • budget_tokens 仅用于 Claude 4.5 及更早的模型,最小 1024;新模型请用 thinking.type: "adaptive" + output_config.effort
  • 新模型默认不返回思考内容,需要展示时设置 thinking.display: "summarized"
  • thinking.type: "between_tools" 仅 claude-sonnet-5-5 可用,且不能与其他 thinking 字段同时传入
  • claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5 不支持强制工具调用(tool_choice 为 any / tool)
  • 工具调用需要多轮交互,第一轮返回工具调用请求,第二轮返回工具执行结果
  • 图像输入需要使用 base64 编码
  • 使用流式输出可以提升首字响应时间和交互体验
  • 工具调用需要做好超时与重试机制,避免阻塞模型响应
  • 扩展思考功能可以显著提升复杂问题的推理质量

相关资源

对话接口(OpenAI 兼容)

查看 OpenAI 兼容的对话接口文档

模型列表

查看所有支持的模型信息