curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-opus-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",
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",
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",
"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",
"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",
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",
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",
"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- Claude Fable 5(最新,最强能力)claude-opus-5- Claude Opus 5(最新,复杂 Agent 与编码场景)claude-sonnet-5- Claude Sonnet 5(速度与智能兼顾)claude-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.5(速度最快)claude-sonnet-4-5-20250929- Claude Sonnet 4.5claude-sonnet-4-20250514- Claude Sonnet 4- 其他 Claude 系列模型
array
必填
对话消息列表,每个元素包含
role(user/assistant)和 content。content 可以是字符串或媒体内容数组。模型支持:全部 Claude 模型均支持。助手预填充(assistant prefill):以
role: "assistant" 结尾来预填模型回复,在 claude-sonnet-4-6、claude-sonnet-5、claude-opus-4-6 及之后的所有模型上返回 400;开启思考时在任何模型上都不可用。请改用 output_config.format(结构化输出)或系统提示词约束输出格式。number
必填
最大生成 token 数,控制回复长度。必须大于 0。思考 token 也计入本上限,开启思考时需预留足够额度,否则会出现
stop_reason: "max_tokens" 截断。模型支持(各模型单次请求的输出上限不同)| 模型 | 最大输出 token |
|---|---|
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、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 4 及以上模型:
temperature 与 top_p 不能同时传入,二选一。number
默认值:"1.0"
核采样参数,0-1,控制生成的多样性。模型支持
| 模型 | 支持情况 |
|---|---|
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-* | ✅ 支持;开启思考时取值须在 0.95 ~ 1 之间 |
number
Top-K 采样参数。模型支持
| 模型 | 支持情况 |
|---|---|
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-* | ✅ 支持;但开启思考时不可用(与思考不兼容) |
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、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 会报错 |
object
扩展思考配置,启用 Claude 的深度推理能力。模型支持(不同代际差异最大的参数,请对照下表)
| 模型 | 支持的思考模式 | 不传 thinking 时 | 返回 400 的取值 |
|---|---|---|---|
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 4.7 代际起,
{"type": "enabled", "budget_tokens": N} 一律返回 400,请改用 {"type": "adaptive"} + output_config.effort 控制思考深度。| 子字段 | 类型 | 说明 |
|---|---|---|
type | enum | "adaptive":自适应思考,由模型决定何时思考及思考深度;"disabled":关闭思考。Claude 4.5 及更早的模型使用 "enabled" 并配合 budget_tokens |
display | enum | "summarized":返回思考过程的摘要;"omitted":不返回思考内容。思考本身仍会进行、费用相同,omitted 只是不展示,好处是流式输出时正文回复出现得更快。不能与 type: "disabled" 同时使用 |
budget_tokens | number | 仅配合 type: "enabled"(Claude 4.5 及更早模型)使用。最小 1024,且必须小于 max_tokens;Claude 4.7 及更新的模型不支持这种写法 |
{"type": "adaptive"} // 自适应思考
{"type": "adaptive", "display": "summarized"} // 自适应思考,并返回思考摘要
{"type": "disabled"} // 关闭思考
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(正文、工具调用、思考),因此不需要开启思考也能生效。模型支持
| 子字段 | 类型 | 说明 |
|---|---|---|
effort | enum | 思考深度,可选 "low" / "medium" / "high" / "xhigh" / "max",默认 "high"。档位越高,回答通常越准确、越深入,但耗时和 token 消耗也更多;编码或 Agent 场景可以尝试 "xhigh" 或 "max" |
{"effort": "high"} // 默认档位,等同于不传该参数
{"effort": "xhigh"} // 编码 / Agent 等长程任务
| 模型 | 可用档位 |
|---|---|
claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-sonnet-5 | low / medium / high / xhigh / max(全部五档) |
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 上,
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。
{"type": "ephemeral"} // 5 分钟缓存(默认)
{"type": "ephemeral", "ttl": "1h"} // 1 小时缓存
旧版 Amazon Bedrock 集成(
InvokeModel / Converse,覆盖 Opus 4.6 及更早的模型)不支持顶层 cache_control,传入会返回 400。这类模型请改用内容块级的显式断点,详见 各上游平台支持情况。参数支持速查表
各参数在本接口支持的 Claude 模型上的可用情况汇总(✅ 支持 / ⚠️ 有条件 / ❌ 传入即 400):| 参数 | 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 | ✅ | ✅ | ✅ | ✅ | ✅ |
output_config.effort | ✅ 五档 | ✅ 五档 | ✅ 五档 | ✅ 五档 | ⚠️ 无 xhigh | ⚠️ 仅 low/medium/high | ❌ |
| 助手预填充(assistant prefill) | ❌ | ❌ | ❌ | ❌ | ❌ | ⚠️ 思考时不可用 | ⚠️ 思考时不可用 |
上表依据 Anthropic 官方 API 文档整理(核对日期:2026-08-10)。模型能力随版本迭代变化,具体以 模型广场 与实际调用返回为准。
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",
"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 | 说明 |
|---|---|---|
| Fable 5、Opus 5、Opus 4.8、Opus 4.7、Sonnet 5 | ✅ | 走 Messages API 端点,模型 ID 形如 anthropic.claude-opus-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",
"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、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",
"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",
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",
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",
"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 支持扩展思考功能,允许模型进行深度推理。启用后,模型会在生成最终答案前进行内部思考。- 基础用法
- Python 示例
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": 4096,
"temperature": 1.0,
"top_p": 0,
"stream": true,
"messages": [
{"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
with client.messages.stream(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
thinking={
"type": "enabled",
"budget_tokens": 4096
},
temperature=1.0,
top_p=0,
messages=[
{"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
]
) as stream:
for event in stream:
if event.type == "content_block_delta":
if hasattr(event.delta, "thinking"):
# 思考过程
print(f"[思考] {event.delta.thinking}", end="")
elif hasattr(event.delta, "text"):
# 最终答案
print(event.delta.text, end="")
budget_tokens必须大于 1024- 使用扩展思考时,建议设置
temperature: 1.0和top_p: 0 - 必须启用流式输出(
stream: true)才能看到思考过程
工具调用(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 等
第一阶段:模型返回工具调用请求第二阶段:返回工具执行结果
{
"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"} | 必须使用指定的工具 |
{
"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-opus-5 与 claude-sonnet-5。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必须大于 1024 - 扩展思考需要启用流式输出才能看到思考过程
- 工具调用需要多轮交互,第一轮返回工具调用请求,第二轮返回工具执行结果
- 图像输入需要使用 base64 编码
- 使用流式输出可以提升首字响应时间和交互体验
- 工具调用需要做好超时与重试机制,避免阻塞模型响应
- 扩展思考功能可以显著提升复杂问题的推理质量
相关资源
对话接口(OpenAI 兼容)
查看 OpenAI 兼容的对话接口文档
模型列表
查看所有支持的模型信息
