Skip to main content
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 - Claude Fable 5(最新,最强能力)
  • claude-opus-5 - Claude Opus 5(最新,复杂 Agent 与编码场景)
  • 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 系列模型
array
必填
对话消息列表,每个元素包含 role(user/assistant)和 contentcontent 可以是字符串或媒体内容数组。模型支持:全部 Claude 模型均支持。
助手预填充(assistant prefill):以 role: "assistant" 结尾来预填模型回复,在 claude-sonnet-4-6claude-sonnet-5claude-opus-4-6 及之后的所有模型上返回 400;开启思考时在任何模型上都不可用。请改用 output_config.format(结构化输出)或系统提示词约束输出格式。
number
必填
最大生成 token 数,控制回复长度。必须大于 0。思考 token 也计入本上限,开启思考时需预留足够额度,否则会出现 stop_reason: "max_tokens" 截断。模型支持(各模型单次请求的输出上限不同)
string|array
系统提示词,可以是字符串或媒体内容数组。用于设定模型的行为和角色。模型支持:全部 Claude 模型均支持,无差异。
number
默认值:"1.0"
随机性控制,0-1,值越高回复越随机。模型支持
所有 Claude 4 及以上模型:temperaturetop_p 不能同时传入,二选一。
number
默认值:"1.0"
核采样参数,0-1,控制生成的多样性。模型支持
number
Top-K 采样参数。模型支持
boolean
默认值:"false"
是否启用流式输出,返回 SSE 格式的分片数据。模型支持:全部 Claude 模型均支持,无差异。
官方 SDK 在 max_tokens > 21333强制要求流式,否则会因 HTTP 超时报错(客户端校验,非服务端限制)。开启思考、或使用较大 max_tokens 时建议一律启用。
array
停止序列列表,当模型生成这些序列时停止生成,此时响应的 stop_reasonstop_sequence模型支持:全部 Claude 模型均支持,无差异。
array
工具定义列表,支持函数工具和网页搜索工具。模型支持:全部 Claude 模型均支持,无差异(具体可用的服务端工具类型按模型代际有别)。
object
工具选择策略,控制模型如何使用工具,可选 auto(默认)、noneanytool模型支持
object
扩展思考配置,启用 Claude 的深度推理能力。模型支持(不同代际差异最大的参数,请对照下表)
从 Claude 4.7 代际起,{"type": "enabled", "budget_tokens": N} 一律返回 400,请改用 {"type": "adaptive"} + output_config.effort 控制思考深度。
display 的默认值因模型而异:Claude Fable 5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 默认为 "omitted";Claude Opus 4.6、Sonnet 4.6 及更早模型默认为 "summarized"。需要向用户展示思考过程时,在前者上必须显式设置 "display": "summarized",否则拿到的思考内容为空。
object
输出配置,用于控制模型的思考深度与 token 消耗。
该参数影响回复中的所有 token(正文、工具调用、思考),因此不需要开启思考也能生效。模型支持
在 Claude Opus 5 上,effort"xhigh""max"无法关闭思考——此时若同时传 "thinking": {"type": "disabled"} 会返回 400 错误。需要关闭思考时,请将 effort 设为 "high" 或更低档位。
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-08-10)。模型能力随版本迭代变化,具体以 模型广场 与实际调用返回为准。

Prompt Caching(提示词缓存)

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

缓存控制参数

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

自动缓存(顶层 cache_control)

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

各上游平台支持情况

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

显式断点(内容块级 cache_control)

标记在 system 数组元素或 messagescontent 数组元素内部:

两种写法组合使用

自动缓存与显式断点可以同时用。典型场景是用显式断点固定住系统提示词,让自动缓存负责不断增长的对话部分:
组合时的规则与边界情况:
  • 自动缓存会占用 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 支持扩展思考功能,允许模型进行深度推理。启用后,模型会在生成最终答案前进行内部思考。
  • budget_tokens 必须大于 1024
  • 使用扩展思考时,建议设置 temperature: 1.0top_p: 0
  • 必须启用流式输出(stream: true)才能看到思考过程

工具调用(Tools)

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

tool_choice 参数详解

tool_choice 控制模型如何使用工具: 示例:

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

Claude 官方预定义的文件读写工具,用于让模型查看和修改本地文件,常见于代码调试、重构与文档编辑场景。它由 Anthropic 定义 schema、由你的程序在本地执行:模型返回 tool_use 块,你执行对应的文件操作后,再把结果作为 tool_result 回传。 声明方式无需 input_schema,只需 typename
模型会在 tool_use.input.command 中返回以下命令之一:
path 由模型生成,属于不可信输入。执行前务必将其解析为规范路径并校验仍在项目根目录内,防止 ..、软链接等路径穿越;出错时返回 is_error: truetool_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-opus-5claude-sonnet-5
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_tokenscache_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 必须大于 1024
  • 扩展思考需要启用流式输出才能看到思考过程
  • 工具调用需要多轮交互,第一轮返回工具调用请求,第二轮返回工具执行结果
  • 图像输入需要使用 base64 编码
  • 使用流式输出可以提升首字响应时间和交互体验
  • 工具调用需要做好超时与重试机制,避免阻塞模型响应
  • 扩展思考功能可以显著提升复杂问题的推理质量

相关资源

对话接口(OpenAI 兼容)

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

模型列表

查看所有支持的模型信息