curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "你是一个严谨的中文技术助手,回答简洁准确。"
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
],
"thinking": {
"type": "adaptive",
"display": "summarized"
},
"output_config": {
"effort": "high"
},
"tools": [
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai"
}
},
"required": ["timezone"]
}
}
],
"tool_choice": {
"type": "auto"
},
"stop_sequences": ["END"],
"stream": false,
"metadata": {
"user_id": "user_20260810_001"
}
}'
const response = await fetch("https://api.gravitex.ai/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer sk-xxxxxxxxxx",
},
body: JSON.stringify({
model: "claude-opus-5-5",
max_tokens: 4096,
system: [
{ type: "text", text: "你是一个严谨的中文技术助手,回答简洁准确。" },
],
messages: [
{
role: "user",
content: [{ type: "text", text: "今天几号" }],
},
],
thinking: { type: "adaptive", display: "summarized" },
output_config: { effort: "high" },
tools: [
{
name: "get_current_date",
description: "获取当前日期与时间,返回 ISO-8601 格式字符串",
input_schema: {
type: "object",
properties: {
timezone: { type: "string", description: "IANA 时区标识,如 Asia/Shanghai" },
},
required: ["timezone"],
},
},
],
tool_choice: { type: "auto" },
stop_sequences: ["END"],
stream: false,
metadata: { user_id: "user_20260810_001" },
}),
});
const data = await response.json();
console.log(data.content);
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai",
)
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
system=[
{"type": "text", "text": "你是一个严谨的中文技术助手,回答简洁准确。"}
],
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "今天几号"}
],
}
],
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
tools=[
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai",
}
},
"required": ["timezone"],
},
}
],
tool_choice={"type": "auto"},
stop_sequences=["END"],
stream=False,
metadata={"user_id": "user_20260810_001"},
)
print(message.content)
# temperature / top_p / top_k 仅 Claude 4.6 及更早模型可用,
# 且开启思考时不可用;temperature 与 top_p 不能同时传入。
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"temperature": 0.7,
"top_k": 40,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
]
}'
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "用户询问当前日期,我需要调用 get_current_date 工具获取准确时间。",
"signature": "EqQBCgIYAhIM1gbc..."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_current_date",
"input": {
"timezone": "Asia/Shanghai"
}
}
],
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 486,
"output_tokens": 142,
"output_tokens_details": {
"thinking_tokens": 87
}
}
}
对话与文本
原生 Claude 格式
POST
/
v1
/
messages
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "你是一个严谨的中文技术助手,回答简洁准确。"
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
],
"thinking": {
"type": "adaptive",
"display": "summarized"
},
"output_config": {
"effort": "high"
},
"tools": [
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai"
}
},
"required": ["timezone"]
}
}
],
"tool_choice": {
"type": "auto"
},
"stop_sequences": ["END"],
"stream": false,
"metadata": {
"user_id": "user_20260810_001"
}
}'
const response = await fetch("https://api.gravitex.ai/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer sk-xxxxxxxxxx",
},
body: JSON.stringify({
model: "claude-opus-5-5",
max_tokens: 4096,
system: [
{ type: "text", text: "你是一个严谨的中文技术助手,回答简洁准确。" },
],
messages: [
{
role: "user",
content: [{ type: "text", text: "今天几号" }],
},
],
thinking: { type: "adaptive", display: "summarized" },
output_config: { effort: "high" },
tools: [
{
name: "get_current_date",
description: "获取当前日期与时间,返回 ISO-8601 格式字符串",
input_schema: {
type: "object",
properties: {
timezone: { type: "string", description: "IANA 时区标识,如 Asia/Shanghai" },
},
required: ["timezone"],
},
},
],
tool_choice: { type: "auto" },
stop_sequences: ["END"],
stream: false,
metadata: { user_id: "user_20260810_001" },
}),
});
const data = await response.json();
console.log(data.content);
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai",
)
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
system=[
{"type": "text", "text": "你是一个严谨的中文技术助手,回答简洁准确。"}
],
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "今天几号"}
],
}
],
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
tools=[
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai",
}
},
"required": ["timezone"],
},
}
],
tool_choice={"type": "auto"},
stop_sequences=["END"],
stream=False,
metadata={"user_id": "user_20260810_001"},
)
print(message.content)
# temperature / top_p / top_k 仅 Claude 4.6 及更早模型可用,
# 且开启思考时不可用;temperature 与 top_p 不能同时传入。
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"temperature": 0.7,
"top_k": 40,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
]
}'
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "用户询问当前日期,我需要调用 get_current_date 工具获取准确时间。",
"signature": "EqQBCgIYAhIM1gbc..."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_current_date",
"input": {
"timezone": "Asia/Shanghai"
}
}
],
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 486,
"output_tokens": 142,
"output_tokens_details": {
"thinking_tokens": 87
}
}
}
简介
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 5claude-opus-5- Claude Opus 5claude-sonnet-5- Claude Sonnet 5claude-opus-4-8- Claude Opus 4.8claude-opus-4-7- Claude Opus 4.7claude-opus-4-6- Claude Opus 4.6claude-sonnet-4-6- Claude Sonnet 4.6(平衡性能)claude-opus-4-5-20251101- Claude Opus 4.5claude-haiku-4-5-20251001- Claude Haiku 4.5claude-sonnet-4-5-20250929- Claude Sonnet 4.5claude-sonnet-4-20250514- Claude Sonnet 4- 其他 Claude 系列模型
array
必填
对话消息列表,每个元素包含
位置规则(在支持的模型上,违反也会返回 400):
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| 模型 | 支持情况 |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8 | ✅ 支持 |
claude-sonnet-5、claude-opus-4-7 及更早的模型 | ❌ 返回 400:role 'system' is not supported on this model |
- 不能作为
messages[0]; - 必须紧跟在一条
user消息之后(或紧跟在以服务端工具调用结尾的assistant消息之后); - 必须是数组的最后一条,或者后面紧跟一条
assistant消息; - 不能插在
assistant的tool_use和对应的tool_result之间(Agent 循环中可放在携带tool_result的user消息之后)。
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": "你是一个有帮助的助手。",
"messages": [
{"role": "user", "content": "帮我写一段产品介绍"},
{"role": "assistant", "content": "好的,这是一段产品介绍……"},
{"role": "user", "content": "再改短一点"},
{"role": "system", "content": "简洁模式已开启:回复控制在 40 字以内。"}
]
}
顶层
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" 截断。模型支持(各模型单次请求的输出上限不同)| 模型 | 最大输出 token |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5、claude-opus-4-6、claude-sonnet-4-6 | 128K |
claude-opus-4-5-20251101、claude-sonnet-4-5-20250929、claude-haiku-4-5-20251001 | 64K |
| 其他旧版模型 | 以 模型广场 标注为准 |
string|array
系统提示词,可以是字符串或媒体内容数组。用于设定模型的行为和角色。模型支持:全部 Claude 模型均支持,无差异。
number
默认值:"1.0"
随机性控制,0-1,值越高回复越随机。模型支持
| 模型 | 支持情况 |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 | ❌ 不支持。传入非默认值返回 400(与是否开启思考无关),请直接删除该参数,改用系统提示词引导风格 |
claude-opus-4-6、claude-sonnet-4-6、claude-opus-4-5-*、claude-sonnet-4-5-*、claude-haiku-4-5-*、claude-sonnet-4-* | ✅ 支持;但开启思考时不可用(与思考不兼容) |
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,控制生成的多样性。模型支持
| 模型 | 支持情况 |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 | ❌ 不支持,传入非默认值返回 400(claude-haiku-5-5 的默认值是 0.99,传 1 也会报错) |
claude-opus-4-6、claude-sonnet-4-6、claude-opus-4-5-*、claude-sonnet-4-5-*、claude-haiku-4-5-*、claude-sonnet-4-* | ✅ 支持;开启思考时取值须在 0.95 ~ 1 之间 |
number
Top-K 采样参数。模型支持
| 模型 | 支持情况 |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 | ❌ 不支持,传入非默认值返回 400(claude-haiku-5-5 传任何值都报错) |
claude-opus-4-6、claude-sonnet-4-6、claude-opus-4-5-*、claude-sonnet-4-5-*、claude-haiku-4-5-*、claude-sonnet-4-* | ✅ 支持;但开启思考时不可用(与思考不兼容) |
boolean
默认值:"false"
是否启用流式输出,返回 SSE 格式的分片数据。模型支持:全部 Claude 模型均支持,无差异。
官方 SDK 在
max_tokens > 21333 时强制要求流式,否则会因 HTTP 超时报错(客户端校验,非服务端限制)。开启思考、或使用较大 max_tokens 时建议一律启用。array
停止序列列表,当模型生成这些序列时停止生成,此时响应的
stop_reason 为 stop_sequence。模型支持:全部 Claude 模型均支持,无差异。array
工具定义列表,支持函数工具和网页搜索工具。模型支持:全部 Claude 模型均支持,无差异(具体可用的服务端工具类型按模型代际有别)。
object
工具选择策略,控制模型如何使用工具,可选
auto(默认)、none、any、tool。模型支持| 模型 | 支持情况 |
|---|---|
claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5 | ⚠️ 仅支持 auto 与 none。传 any 或 tool 一律返回 400(tool_choice: type "tool" and "any" are not supported for this model.),与是否开启思考无关;Batches 和 count_tokens 接口同样会拒绝 |
claude-haiku-5-5 | ✅ 四种取值全部支持;但强制调用(any / tool)时模型会跳过思考,直接输出工具调用 |
其他自适应思考模型(claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5、claude-opus-4-6、claude-sonnet-4-6) | ✅ 四种取值全部支持,强制工具调用与思考兼容 |
仅支持扩展思考的模型(claude-opus-4-5-*、claude-sonnet-4-5-*、claude-haiku-4-5-*、claude-sonnet-4-*) | ⚠️ 开启思考时仅支持 auto 与 none;传 any 或 tool 会报错 |
在不支持强制调用的模型上,可以改用
{"type": "auto"},并在提示词里明确要求使用哪个工具;同时在工具定义上加 strict: true,保证参数符合 schema。auto 不保证一定会调用工具,请在代码里检查,没调用就重试。如果强制调用只是为了拿到 JSON,直接改用结构化输出(output_config.format)。官方文档:Forced tool use is not supported | Strict tool useobject
扩展思考配置,启用 Claude 的深度推理能力。模型支持(不同代际差异最大的参数,请对照下表)
| 模型 | 支持的思考模式 | 不传 thinking 时 | 返回 400 的取值 |
|---|---|---|---|
claude-fable-5-1 | 仅自适应 | 始终开启 | enabled、disabled、between_tools |
claude-opus-5-5 | 仅自适应 | 始终开启 | enabled、between_tools;disabled 在任何 effort 档位下都报 400 |
claude-sonnet-5-5 | 自适应 + between_tools(最低档) | 默认开启 | enabled、disabled;between_tools 配合 xhigh/max 报 400 |
claude-haiku-5-5 | 仅自适应 | 默认开启 | enabled、between_tools;disabled 仅在 effort ≤ high 时可用 |
claude-fable-5 | 仅自适应 | 始终开启 | enabled、disabled |
claude-opus-5 | 仅自适应 | 默认开启 | enabled;disabled 仅在 effort ≤ high 时可用,配合 xhigh/max 报 400 |
claude-sonnet-5 | 仅自适应 | 默认开启 | enabled |
claude-opus-4-8 | 仅自适应 | 关闭 | enabled |
claude-opus-4-7 | 仅自适应 | 关闭 | enabled |
claude-opus-4-6 | 自适应 + 扩展(已弃用) | 关闭 | 无 |
claude-sonnet-4-6 | 自适应 + 扩展(已弃用) | 关闭 | 无 |
claude-opus-4-5-20251101 | 仅扩展 | 关闭 | adaptive |
claude-sonnet-4-5-20250929 | 仅扩展 | 关闭 | adaptive |
claude-haiku-4-5-20251001 | 仅扩展 | 关闭 | adaptive |
claude-sonnet-4-20250514 | 仅扩展 | 关闭 | adaptive |
从 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 上已弃用,但暂时还能用。| 子字段 | 类型 | 说明 |
|---|---|---|
type | enum | "adaptive":自适应思考,由模型决定何时思考、思考多深;"disabled":关闭思考;"between_tools":仅 claude-sonnet-5-5 支持,是该模型思考的最低档,用来替代被禁用的 disabled(见下文);"enabled":手动设置思考预算,仅用于 Claude 4.5 及更早的模型,需配合 budget_tokens |
display | enum | "summarized":返回思考过程的摘要;"omitted":不返回思考内容。思考照常进行、费用相同,omitted 只是不展示,好处是流式输出时正文出现得更快。"updates"(Beta):隐藏推理过程,只返回模型在两次工具调用之间写的简短进度说明,支持 claude-fable-5-1、claude-fable-5、claude-opus-5-5、claude-sonnet-5-5,需带请求头 anthropic-beta: thinking-display-updates-2026-08-18。display 不能与 type: "disabled" 或 "between_tools" 同时使用 |
budget_tokens | number | 仅配合 type: "enabled" 使用(Claude 4.5 及更早的模型)。最小 1024,且必须小于 max_tokens;Claude 4.7 及之后的模型不支持这种写法 |
{"type": "adaptive"} // 自适应思考
{"type": "adaptive", "display": "summarized"} // 自适应思考,并返回思考摘要
{"type": "disabled"} // 关闭思考(Fable、Opus 5.5、Sonnet 5.5 不可用)
{"type": "between_tools"} // 仅 Sonnet 5.5:思考最低档
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):| 限制 | 违反时的报错 |
|---|---|
thinking 里只能有 type 一个字段,不能带 display、budget_tokens、block_binding | 400 |
output_config.effort 只能是 high 及以下 | output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. |
| 对话中途不能逐条消息修改 effort | messages.N: output_config.effort 'low' differs from the 'high' in effect before it; ... |
只能用于 claude-sonnet-5-5,其他模型(包括 Sonnet 5、Opus 5.5、Fable 5.1)都不支持 | "thinking.type.between_tools" is not supported for this model. |
// ✅ 正确
{"model": "claude-sonnet-5-5", "thinking": {"type": "between_tools"}, "output_config": {"effort": "high"}}
// ❌ 400:between_tools 不能带 budget_tokens
{"model": "claude-sonnet-5-5", "thinking": {"type": "between_tools", "budget_tokens": 2048}}
// ❌ 400:between_tools 不支持 xhigh / max
{"model": "claude-sonnet-5-5", "thinking": {"type": "between_tools"}, "output_config": {"effort": "xhigh"}}
// ❌ 400:Sonnet 5.5 不再接受 disabled
{"model": "claude-sonnet-5-5", "thinking": {"type": "disabled"}}
官方建议优先用自适应思考 +
effort: "low":在 low 档位下模型思考很短,简单请求通常直接跳过思考。确实需要关闭思考时,再用 between_tools。如果你的代码会把同一个请求体重试到其他模型(如降级、路由),记得先去掉 between_tools。官方文档:Turn off up-front thinking(Sonnet 5.5 迁移指南) | Running without up-front thinkingobject
输出配置,用于控制模型的思考深度与 token 消耗。
该参数影响回复中的所有 token(正文、工具调用、思考),因此不需要开启思考也能生效。模型支持
官方文档:Effort | Sonnet 5.5 推荐档位 | Opus 5.5 迁移指南
| 子字段 | 类型 | 说明 |
|---|---|---|
effort | enum | 思考深度,可选 "low" / "medium" / "high" / "xhigh" / "max"。默认值大多为 "high",claude-opus-5-5 和 claude-haiku-5-5 默认为 "medium"。档位越高,回答通常越准确、越深入,但耗时和 token 消耗也越多;编码或 Agent 场景可以尝试 "xhigh" 或 "max" |
{"effort": "high"} // 多数模型的默认档位
{"effort": "xhigh"} // 编码 / Agent 等长程任务
{"effort": "low"} // 闲聊、分类、子 Agent 等简单任务
| 模型 | 可用档位 |
|---|---|
claude-opus-5-5、claude-haiku-5-5 | 全部五档,默认 medium(比上一代低一档,需要深度推理时请显式设置) |
claude-sonnet-5-5 | 全部五档,默认 high;各档位已重新校准,同一档位的思考量与 Sonnet 5 不同,迁移后请重新测试(官方建议 Agent 编码从 medium 起步,闲聊从 low 起步) |
claude-fable-5-1、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 | low / medium / high / xhigh / max(全部五档),默认 high |
claude-opus-4-6、claude-sonnet-4-6 | low / medium / high / max(不支持 xhigh) |
claude-opus-4-5-20251101 | low / medium / high(唯一支持 effort 的「仅扩展思考」模型,需与 budget_tokens 配合) |
claude-sonnet-4-5-20250929、claude-haiku-4-5-20251001、claude-sonnet-4-20250514 | ❌ 不支持本参数 |
在 Claude Opus 5 和 Haiku 5.5 上,
effort 为 "xhigh" 或 "max" 时无法关闭思考,此时同时传 "thinking": {"type": "disabled"} 会返回 400。需要关闭思考时,请把 effort 设为 "high" 或更低档位。Sonnet 5.5 的 between_tools 规则相同。Opus 5.5 在任何档位下都不能关闭思考,只能通过调低 effort 来减少思考。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。
{"type": "ephemeral"} // 5 分钟缓存(默认)
{"type": "ephemeral", "ttl": "1h"} // 1 小时缓存
旧版 Amazon Bedrock 集成(
InvokeModel / Converse,覆盖 Opus 4.6 及更早的模型)不支持顶层 cache_control,传入会返回 400。这类模型请改用内容块级的显式断点,详见 各上游平台支持情况。参数支持速查表
各参数在本接口支持的 Claude 模型上的可用情况汇总(✅ 支持 / ⚠️ 有条件 / ❌ 传入即 400): 最新一代模型| 参数 | Fable 5.1 | Opus 5.5 | Sonnet 5.5 | Haiku 5.5 |
|---|---|---|---|---|
model / messages / system / max_tokens | ✅ | ✅ | ✅ | ✅ |
stream / stop_sequences / tools / metadata | ✅ | ✅ | ✅ | ✅ |
temperature / top_p / top_k | ❌ | ❌ | ❌ | ❌ 仅接受默认值 |
tool_choice(any/tool 强制调用) | ❌ | ❌ | ❌ | ⚠️ 可用但跳过思考 |
thinking: adaptive | ✅ 恒开 | ✅ 恒开 | ✅ 默认开 | ✅ 默认开 |
thinking: enabled + budget_tokens | ❌ | ❌ | ❌ | ❌ |
thinking: disabled | ❌ | ❌ | ❌ | ⚠️ 仅 effort ≤ high |
thinking: between_tools | ❌ | ❌ | ⚠️ 仅 effort ≤ high,不能带其他字段 | ❌ |
thinking.display: updates(Beta) | ✅ | ✅ | ✅ | ❌ |
messages[].role: "system"(对话中途 system 消息) | ✅ | ✅ | ✅ | ✅ |
output_config.effort | ✅ 五档 | ✅ 五档,默认 medium | ✅ 五档(已重新校准) | ✅ 五档,默认 medium |
| 助手预填充(assistant prefill) | ❌ | ❌ | ❌ | ❌ |
| 参数 | Fable 5 | Opus 5 | Sonnet 5 | Opus 4.8 / 4.7 | Opus 4.6 / Sonnet 4.6 | Opus 4.5 | Sonnet 4.5 / Haiku 4.5 / Sonnet 4 |
|---|---|---|---|---|---|---|---|
model / messages / system / max_tokens | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
stream / stop_sequences / tools / metadata | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
temperature | ❌ | ❌ | ❌ | ❌ | ⚠️ 思考时不可用 | ⚠️ | ⚠️ |
top_p | ❌ | ❌ | ❌ | ❌ | ⚠️ 思考时限 0.95~1 | ⚠️ | ⚠️ |
top_k | ❌ | ❌ | ❌ | ❌ | ⚠️ 思考时不可用 | ⚠️ | ⚠️ |
tool_choice(any/tool 强制调用) | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ 思考时不可用 | ⚠️ 思考时不可用 |
thinking: adaptive | ✅ 恒开 | ✅ 默认开 | ✅ 默认开 | ✅ | ✅ | ❌ | ❌ |
thinking: enabled + budget_tokens | ❌ | ❌ | ❌ | ❌ | ⚠️ 已弃用仍可用 | ✅ | ✅ |
thinking: disabled | ❌ | ⚠️ 仅 effort ≤ high | ✅ | ✅ | ✅ | ✅ | ✅ |
thinking: between_tools | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
messages[].role: "system"(对话中途 system 消息) | ✅ | ✅ | ❌ | ⚠️ 仅 Opus 4.8 | ❌ | ❌ | ❌ |
output_config.effort | ✅ 五档 | ✅ 五档 | ✅ 五档 | ✅ 五档 | ⚠️ 无 xhigh | ⚠️ 仅 low/medium/high | ❌ |
| 助手预填充(assistant prefill) | ❌ | ❌ | ❌ | ❌ | ❌ | ⚠️ 思考时不可用 | ⚠️ 思考时不可用 |
上表依据 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 标记在 system / messages 的内容块上 | 需要精确控制缓存边界,例如只缓存系统提示词或某段长文档 |
缓存控制参数
两种写法的字段结构相同。字段说明:| 字段 | 说明 |
|---|---|
type | 缓存类型,固定为 "ephemeral" |
ttl | 缓存有效期,可选。不填为 5 分钟(默认,成本最优);填 "1h" 为 1 小时缓存(适用于长期稳定的上下文,但写入成本更高) |
{"type": "ephemeral"} // 5 分钟缓存(默认)
{"type": "ephemeral", "ttl": "1h"} // 1 小时缓存
自动缓存(顶层 cache_control)
把cache_control 直接写在请求体根级别即可,不需要在任何内容块上打标记:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "你是一个有帮助的助手。",
"messages": [
{"role": "user", "content": "我叫 Alex,做机器学习。"},
{"role": "assistant", "content": "很高兴认识你,Alex!"},
{"role": "user", "content": "我刚才说我是做什么的?"}
]
}
| 请求 | 内容(◀ 为断点位置) | 缓存行为 |
|---|---|---|
| 第 1 次 | System + User(1) + Asst(1) + User(2) ◀ | 全部写入缓存 |
| 第 2 次 | System + …… + User(2) + Asst(2) + User(3) ◀ | System~User(2) 命中缓存;Asst(2) + User(3) 写入缓存 |
| 第 3 次 | System + …… + User(3) + Asst(3) + User(4) ◀ | System~User(3) 命中缓存;Asst(3) + User(4) 写入缓存 |
各上游平台支持情况
自动缓存(顶层cache_control)在绝大多数平台可用,唯一的例外是旧版 Amazon Bedrock 集成:
| 上游平台 | 顶层 cache_control |
|---|---|
| Anthropic 官方 API | ✅ |
| Claude Platform on AWS(Anthropic 自营,AWS Marketplace 计费) | ✅ |
| Claude in Amazon Bedrock(Messages API 端点,Opus 4.7 及之后) | ✅ |
旧版 Claude on Amazon Bedrock(InvokeModel / Converse,Opus 4.6 及更早) | ❌ 返回 400 |
| Google Vertex AI | ✅ |
| Microsoft Foundry | ✅ |
| 模型 | 顶层 cache_control | 说明 |
|---|---|---|
| Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5、Opus 5、Opus 4.8、Opus 4.7、Sonnet 5 | ✅ | 走 Messages API 端点,模型 ID 形如 anthropic.claude-opus-5-5(无 ARN 版本号) |
| Opus 4.6、Sonnet 4.6、Opus 4.5、Sonnet 4.5、Sonnet 4 | ❌ | 走旧版 InvokeModel / Converse,模型 ID 带 ARN 版本号,请用显式断点 |
不确定某个模型实际走哪条链路时,可用同一前缀连发两次请求,看第二次响应的
usage.cache_read_input_tokens 是否大于 0 来验证缓存是否真的命中。显式断点(内容块级 cache_control)
标记在system 数组元素或 messages 的 content 数组元素内部:
{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "大段稳定的上下文内容……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "需要缓存的长文档……",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
}
]
}
两种写法组合使用
自动缓存与显式断点可以同时用。典型场景是用显式断点固定住系统提示词,让自动缓存负责不断增长的对话部分:{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": [
{
"type": "text",
"text": "大段稳定的系统提示词……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "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 倍
各模型最小可缓存长度
| 模型 | 最小可缓存长度 |
|---|---|
| Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5、Claude Haiku 5.5、Claude Fable 5、Claude Opus 5 | 512 tokens |
| Claude Opus 4.8、Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5 | 1,024 tokens |
| Claude Opus 4.7 | 2,048 tokens |
| Claude Opus 4.6、Claude Opus 4.5、Claude Haiku 4.5 | 4,096 tokens |
使用场景
- 长文档分析:将大型文档缓存在
system中,多次提问 - 代码库理解:缓存代码上下文,进行多轮代码分析
- 知识库问答:缓存知识库内容,提供快速查询
- 多轮对话:缓存历史对话,保持上下文连贯性
基础示例
- 非流式请求
- 流式请求(SSE)
- Python 示例(Anthropic SDK)
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "请用中文简要介绍人工智能"}
]
}'
curl -N -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"stream": true,
"messages": [
{"role": "user", "content": "请用中文简要介绍人工智能"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
# 非流式
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "请用中文简要介绍人工智能"}
]
)
print(message.content[0].text)
# 流式
with client.messages.stream(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "请用中文简要介绍人工智能"}
]
) as stream:
for text_block in stream.text_stream:
print(text_block, end="")
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "你是一个严谨的中文技术助手,回答简洁准确。"
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
],
"thinking": {
"type": "adaptive",
"display": "summarized"
},
"output_config": {
"effort": "high"
},
"tools": [
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai"
}
},
"required": ["timezone"]
}
}
],
"tool_choice": {
"type": "auto"
},
"stop_sequences": ["END"],
"stream": false,
"metadata": {
"user_id": "user_20260810_001"
}
}'
const response = await fetch("https://api.gravitex.ai/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer sk-xxxxxxxxxx",
},
body: JSON.stringify({
model: "claude-opus-5-5",
max_tokens: 4096,
system: [
{ type: "text", text: "你是一个严谨的中文技术助手,回答简洁准确。" },
],
messages: [
{
role: "user",
content: [{ type: "text", text: "今天几号" }],
},
],
thinking: { type: "adaptive", display: "summarized" },
output_config: { effort: "high" },
tools: [
{
name: "get_current_date",
description: "获取当前日期与时间,返回 ISO-8601 格式字符串",
input_schema: {
type: "object",
properties: {
timezone: { type: "string", description: "IANA 时区标识,如 Asia/Shanghai" },
},
required: ["timezone"],
},
},
],
tool_choice: { type: "auto" },
stop_sequences: ["END"],
stream: false,
metadata: { user_id: "user_20260810_001" },
}),
});
const data = await response.json();
console.log(data.content);
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai",
)
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
system=[
{"type": "text", "text": "你是一个严谨的中文技术助手,回答简洁准确。"}
],
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "今天几号"}
],
}
],
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
tools=[
{
"name": "get_current_date",
"description": "获取当前日期与时间,返回 ISO-8601 格式字符串",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA 时区标识,如 Asia/Shanghai",
}
},
"required": ["timezone"],
},
}
],
tool_choice={"type": "auto"},
stop_sequences=["END"],
stream=False,
metadata={"user_id": "user_20260810_001"},
)
print(message.content)
# temperature / top_p / top_k 仅 Claude 4.6 及更早模型可用,
# 且开启思考时不可用;temperature 与 top_p 不能同时传入。
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"temperature": 0.7,
"top_k": 40,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "今天几号"
}
]
}
]
}'
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "用户询问当前日期,我需要调用 get_current_date 工具获取准确时间。",
"signature": "EqQBCgIYAhIM1gbc..."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_current_date",
"input": {
"timezone": "Asia/Shanghai"
}
}
],
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 486,
"output_tokens": 142,
"output_tokens_details": {
"thinking_tokens": 87
}
}
}
高级功能
系统提示词
系统提示词可以设置为字符串或媒体内容数组:- 字符串格式
- 数组格式
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": "你是一个有用的助手,擅长用中文回答问题。",
"messages": [
{"role": "user", "content": "什么是机器学习?"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{"type": "text", "text": "你是一个有用的助手,擅长用中文回答问题。"}
],
"messages": [
{"role": "user", "content": "什么是机器学习?"}
]
}'
扩展思考(Extended Thinking)
Claude 支持扩展思考,模型会在给出最终答案前先进行内部推理。不同代际的写法不同(官方文档:Thinking):| 模型 | 推荐写法 |
|---|---|
| Fable 5.1 / 5、Opus 5.5 / 5 / 4.8 / 4.7、Sonnet 5.5 / 5、Haiku 5.5 | {"type": "adaptive"}(或不传)+ output_config.effort 控制深度 |
| Opus 4.6、Sonnet 4.6 | {"type": "adaptive"}(推荐);enabled + budget_tokens 已弃用 |
| Opus 4.5、Sonnet 4.5、Haiku 4.5、Sonnet 4 及更早 | {"type": "enabled", "budget_tokens": N} |
- 自适应思考(新模型)
- Sonnet 5.5 关闭思考(between_tools)
- Python 示例(自适应思考)
- 旧模型(budget_tokens)
curl -N -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"stream": true,
"thinking": {"type": "adaptive", "display": "summarized"},
"output_config": {"effort": "high"},
"messages": [
{"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 16000,
"thinking": {"type": "between_tools"},
"output_config": {"effort": "high"},
"messages": [
{"role": "user", "content": "用一句话介绍你自己"}
]
}'
between_tools 只能单独出现在 thinking 里,effort 不能高于 high,详见上方请求参数中的 thinking.type = between_tools。from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"},
messages=[
{"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
]
) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
# 思考摘要
print(f"[思考] {event.delta.thinking}", end="")
elif event.delta.type == "text_delta":
# 最终答案
print(event.delta.text, end="")
# 仅适用于 Claude 4.5 及更早的模型;
# 在 Opus 4.7+、Fable、Opus 5/5.5、Sonnet 5/5.5、Haiku 5.5 上会返回 400
with client.messages.stream(
model="claude-sonnet-4-5-20250929",
max_tokens=8192,
thinking={"type": "enabled", "budget_tokens": 4096},
messages=[
{"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
]
) as stream:
for text in stream.text_stream:
print(text, end="")
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)
支持函数工具和网页搜索工具:- 函数工具
- Claude 官方网页搜索工具
- 工具调用完整流程
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "根据城市获取天气信息",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
}
],
"tool_choice": {
"type": "auto"
},
"messages": [
{"role": "user", "content": "上海的天气怎么样?"}
]
}'
Claude 支持官方的网页搜索工具 基础用法:带搜索次数限制:带位置信息(提升搜索准确性):Python 示例:
web_search_20250305,可以实时搜索网络信息并在响应中包含引用来源。注意:aws bedrock 不支持该搜索工具
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search"
}
],
"messages": [
{"role": "user", "content": "最近关于人工智能的新闻有哪些?"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
"messages": [
{"role": "user", "content": "搜索一下今天北京的天气"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
"user_location": {
"type": "approximate",
"timezone": "Asia/Shanghai",
"country": "CN",
"region": "Beijing",
"city": "Beijing"
}
}
],
"messages": [
{"role": "user", "content": "上海今天的天气怎么样?"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
tools=[
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
messages=[
{"role": "user", "content": "最近关于人工智能的新闻有哪些?"}
]
)
print(message.content[0].text)
type必须为"web_search_20250305"name必须为"web_search"max_uses(可选):单次对话中最多使用搜索的次数,建议值:2-10user_location(可选):用户位置信息,用于提升搜索结果的本地化准确性- 搜索结果会在响应中自动包含引用来源
- 支持的模型包括 Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5 等
- 共三个版本:
web_search_20250305(基础版)、web_search_20260209(增加动态过滤,模型先写代码过滤搜索结果再放入上下文,更省 token)、web_search_20260318(再增加response_inclusion控制)。动态过滤适用于 Claude 4.6 及之后的模型,name均为web_search - Google Cloud(Vertex AI)渠道只支持基础版
web_search_20250305;Amazon Bedrock 不支持网页搜索 - 官方文档:Web search tool
第一阶段:模型返回工具调用请求第二阶段:返回工具执行结果
{
"id": "msg_xxx",
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"city": "上海"}
}
],
"stop_reason": "tool_use"
}
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [...],
"messages": [
{"role": "user", "content": "上海的天气怎么样?"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"city": "上海"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_xxx",
"content": "{\"temp\":\"22°C\",\"condition\":\"多云\",\"aqi\":53}"
}
]
}
]
}'
tool_choice 参数详解
tool_choice 控制模型如何使用工具:
| 值 | 说明 |
|---|---|
{"type": "auto"} | 自动决定是否使用工具(默认) |
{"type": "any"} | 必须使用至少一个工具 |
{"type": "none"} | 不使用任何工具 |
{"type": "tool", "name": "tool_name"} | 必须使用指定的工具 |
any 和 tool 在 claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5 上会返回 400,替代写法见上方 tool_choice 参数说明。disable_parallel_tool_use: true 配合 auto 仍然可用,含义是「最多调用一次」。{
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
文本编辑器工具(Text Editor Tool)
Claude 官方预定义的文件读写工具,用于让模型查看和修改本地文件,常见于代码调试、重构与文档编辑场景。它由 Anthropic 定义 schema、由你的程序在本地执行:模型返回tool_use 块,你执行对应的文件操作后,再把结果作为 tool_result 回传。
声明方式无需 input_schema,只需 type 与 name:
{
"tools": [
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool"
}
]
}
tool_use.input.command 中返回以下命令之一:
| 命令 | 主要入参 | 作用 |
|---|---|---|
view | path、view_range(可选) | 查看文件内容或目录列表 |
create | path、file_text | 创建 / 覆盖文件 |
str_replace | path、old_str、new_str | 替换文件中唯一匹配的片段 |
insert | path、insert_line、insert_text | 在指定行后插入内容 |
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 参数控制本次请求可用的容量:
| 取值 | 说明 |
|---|---|
auto(默认) | 有 Priority Tier 容量时优先使用,容量不足自动回落到标准容量 |
standard_only | 只使用标准容量,不消耗 Priority Tier 额度 |
{
"model": "claude-opus-4-8",
"max_tokens": 1024,
"service_tier": "auto",
"messages": [
{"role": "user", "content": "你好"}
]
}
usage.service_tier 会返回本次请求实际命中的层级(如 "priority" / "standard"),可据此判断调度结果:
{
"usage": {
"input_tokens": 410,
"output_tokens": 585,
"service_tier": "priority"
}
}
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。多模态输入(图像)
支持在消息中包含图像:curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
},
{
"type": "text",
"text": "这张图片里有什么?"
}
]
}
]
}'
Prompt Caching(提示词缓存)
通过缓存常用的上下文内容,可以显著降低成本和提升响应速度。- System 缓存(5分钟)
- Messages 缓存(1小时)
- Python SDK 示例
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "你是一个专业的技术文档分析助手。以下是 AWS Lambda 的完整技术文档:\n\nAWS Lambda 是一项无服务器计算服务...[大量文档内容,至少1024个tokens]",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Lambda 的定价模型是什么?"}
]
}'
{
"usage": {
"input_tokens": 50,
"cache_creation_input_tokens": 1200,
"cache_read_input_tokens": 0,
"output_tokens": 150
}
}
{
"usage": {
"input_tokens": 45,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 1200,
"output_tokens": 100
}
}
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": "你是一个 Python 编程助手",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "分析这段代码:\n```python\n[大量代码,至少1024个tokens]\n```",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "这段代码的主要功能是...[详细分析]",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
},
{
"role": "user",
"content": "如何优化这段代码的性能?"
}
]
}'
ttl: "1h")的优势:- 1小时缓存时效,适合长时间会话
- 适用于代码审查、文档分析等场景
- 缓存命中后,后续请求速度更快
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
# 首次请求:创建缓存
message1 = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system=[
{
"type": "text",
"text": "你是专业的文档分析助手...[长文本内容]",
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "第一个问题"}
]
)
print(f"缓存创建: {message1.usage.cache_creation_input_tokens} tokens")
print(f"缓存读取: {message1.usage.cache_read_input_tokens} tokens")
# 5分钟内再次请求:使用缓存
message2 = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system=[
{
"type": "text",
"text": "你是专业的文档分析助手...[相同的长文本]",
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "第二个问题"}
]
)
print(f"缓存创建: {message2.usage.cache_creation_input_tokens} tokens")
print(f"缓存读取: {message2.usage.cache_read_input_tokens} tokens")
缓存要点:
- 内容必须 ≥ 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以优化成本
响应格式
- 非流式响应
- 流式响应
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "回复内容..."
}
],
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 25,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 100
}
}
input_tokens: 当前请求的非缓存输入 tokenscache_creation_input_tokens: 首次缓存创建的 tokens(仅首次请求时有值)cache_read_input_tokens: 从缓存读取的 tokens(缓存命中时有值)output_tokens: 生成的输出 tokens
流式响应以 SSE(Server-Sent Events)格式返回,包含以下事件类型:使用扩展思考时,
message_start: 消息开始content_block_start: 内容块开始content_block_delta: 内容增量(包含text或thinking)content_block_stop: 内容块结束message_delta: 消息增量(包含 usage 信息)message_stop: 消息结束
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-5-20250929","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"回"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"复"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":100}}
event: message_stop
data: {"type":"message_stop"}
content_block_delta 可能包含 thinking 字段:event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"让我思考一下这个问题..."}}
错误处理
系统会对上游 Claude API 的错误进行统一处理,返回标准化的错误响应格式。| 错误类型 | HTTP 状态码 | 说明 |
|---|---|---|
invalid_request | 400 | 请求参数错误(如缺少必填字段) |
authentication_error | 401 | API 密钥无效或未授权 |
rate_limit_error | 429 | 请求频率超限 |
upstream_error | 500 | 上游服务错误 |
gravitex_api_error | 500 | 系统内部错误 |
{
"error": {
"type": "invalid_request",
"message": "field messages is required"
}
}
与 /v1/chat/completions 的对比
| 特性 | /v1/messages | /v1/chat/completions |
|---|---|---|
| 认证方式 | Authorization: Bearer | Authorization: Bearer |
| 响应格式 | Anthropic 原生格式 | OpenAI 兼容格式 |
| 扩展思考 | 原生支持 thinking 参数 | 通过 reasoning_effort 或 reasoning 参数 |
| 工具调用 | 原生 tools 和 tool_choice | OpenAI 兼容格式 |
| 适用客户端 | Anthropic SDK、Claude Code | OpenAI SDK、兼容客户端 |
- 如果您使用 Claude Code 或其他 Anthropic 原生客户端,建议使用
/v1/messages接口 - 如果您使用 OpenAI SDK 或需要兼容 OpenAI 格式,建议使用
/v1/chat/completions接口 - 两个接口的功能基本相同,主要区别在于请求/响应格式
注意事项
max_tokens是必填参数,必须大于 0messages数组不能为空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 兼容的对话接口文档
模型列表
查看所有支持的模型信息
