> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 原生 Claude 格式
## 简介
Claude 原生的消息接口，适用于 Claude Code 等原生 Anthropic 客户端。该接口遵循 Anthropic 的 API 规范，提供完整的 Claude 模型功能支持，包括扩展思考（Extended Thinking）、工具调用等高级特性。
如果您使用 OpenAI 兼容的客户端（如 OpenAI SDK），建议使用 [`/v1/chat/completions`](/cn/api-reference/endpoint/chat-openai) 接口。
## 认证
Bearer Token，如 `Bearer sk-xxxxxxxxxx`
## 请求参数
Claude 模型标识，支持的模型包括：
* `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-opus-4-1-20250805` - Claude Opus 4.1
* `claude-sonnet-4-20250514` - Claude Sonnet 4
* 其他 Claude 系列模型
对话消息列表，每个元素包含 `role`（user/assistant）和 `content`。`content` 可以是字符串或媒体内容数组。
最大生成 token 数，控制回复长度。必须大于 0。
系统提示词，可以是字符串或媒体内容数组。用于设定模型的行为和角色。
随机性控制，0-1，值越高回复越随机。使用扩展思考时建议设置为 1.0。
核采样参数，0-1，控制生成的多样性。使用扩展思考时建议设置为 0。
Top-K 采样参数，仅部分模型支持。
是否启用流式输出，返回 SSE 格式的分片数据。使用扩展思考时建议启用。
停止序列列表，当模型生成这些序列时停止生成。
工具定义列表，支持函数工具和网页搜索工具。
工具选择策略，控制模型如何使用工具。
扩展思考配置，启用 Claude 的深度推理能力。
请求元数据，用于追踪和调试。
MCP（Model Context Protocol）服务器配置。
上下文管理配置，控制对话上下文的处理方式。
## Prompt Caching（提示词缓存）
Prompt Caching 允许缓存经常使用的上下文内容，显著降低成本并提升响应速度。支持在 `system` 和 `messages` 中使用 `cache_control` 参数。
### 缓存控制参数
缓存控制配置，可用于 `system` 数组元素和 `messages` 的 `content` 数组元素。
* `type`: 缓存类型
* `"ephemeral"`: 5分钟缓存（默认，成本最优）
* `"persistent"`: 1小时缓存（适用于长期稳定的上下文）
### 缓存机制
* **缓存位置**：最后一个带 `cache_control` 标记的内容块会被缓存
* **缓存阈值**：内容至少需要 **1024 tokens**（Claude Sonnet 4.5）或 **2048 tokens**（Claude 3 Haiku）
* **缓存时效**：
* `ephemeral`: 5分钟内有效
* `persistent`: 1小时内有效
* **成本节省**：缓存读取比普通输入便宜 **90%**
### 使用场景
1. **长文档分析**：将大型文档缓存在 `system` 中，多次提问
2. **代码库理解**：缓存代码上下文，进行多轮代码分析
3. **知识库问答**：缓存知识库内容，提供快速查询
4. **多轮对话**：缓存历史对话，保持上下文连贯性
## 基础示例
```bash theme={null}
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": "请用中文简要介绍人工智能"}
]
}'
```
```bash theme={null}
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": "请用中文简要介绍人工智能"}
]
}'
```
```python theme={null}
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="")
```
```json theme={null}
{
"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,
"output_tokens": 100
}
}
```
## 高级功能
### 系统提示词
系统提示词可以设置为字符串或媒体内容数组：
```bash theme={null}
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": "什么是机器学习？"}
]
}'
```
```bash theme={null}
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 支持扩展思考功能，允许模型进行深度推理。启用后，模型会在生成最终答案前进行内部思考。
```bash theme={null}
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": "给出一道中等难度的几何题并分步解析"}
]
}'
```
```python theme={null}
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）
支持函数工具和网页搜索工具：
```bash theme={null}
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 支持官方的网页搜索工具 `web_search_20250305`，可以实时搜索网络信息并在响应中包含引用来源。
注意：aws bedrock 不支持该搜索工具
**基础用法**：
```bash theme={null}
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": "最近关于人工智能的新闻有哪些？"}
]
}'
```
**带搜索次数限制**：
```bash theme={null}
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": "搜索一下今天北京的天气"}
]
}'
```
**带位置信息（提升搜索准确性）**：
```bash theme={null}
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": "上海今天的天气怎么样？"}
]
}'
```
**Python 示例**：
```python theme={null}
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-10
* `user_location`（可选）：用户位置信息，用于提升搜索结果的本地化准确性
* 搜索结果会在响应中自动包含引用来源
* 支持的模型包括 Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5 等
第一阶段：模型返回工具调用请求
```json theme={null}
{
"id": "msg_xxx",
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"city": "上海"}
}
],
"stop_reason": "tool_use"
}
```
第二阶段：返回工具执行结果
```bash theme={null}
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"}` | 必须使用指定的工具 |
示例：
```json theme={null}
{
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
```
### 多模态输入（图像）
支持在消息中包含图像：
```bash theme={null}
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（提示词缓存）
通过缓存常用的上下文内容，可以显著降低成本和提升响应速度。
```bash theme={null}
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 的定价模型是什么？"}
]
}'
```
**首次请求响应**：
```json theme={null}
{
"usage": {
"input_tokens": 50,
"cache_creation_input_tokens": 1200,
"cache_read_input_tokens": 0,
"output_tokens": 150
}
}
```
**5分钟内再次请求（不同问题，相同 system）**：
```json theme={null}
{
"usage": {
"input_tokens": 45,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 1200,
"output_tokens": 100
}
}
```
````bash theme={null}
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": "persistent"}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "这段代码的主要功能是...[详细分析]",
"cache_control": {"type": "persistent"}
}
]
},
{
"role": "user",
"content": "如何优化这段代码的性能？"
}
]
}'
````
**使用 persistent 缓存的优势**：
* 1小时缓存时效，适合长时间会话
* 适用于代码审查、文档分析等场景
* 缓存命中后，后续请求速度更快
```python theme={null}
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）才会触发缓存
* `ephemeral` 缓存在 **5分钟**内有效
* `persistent` 缓存在 **1小时**内有效
* 缓存读取成本比正常输入便宜 **90%**
* 最后一个带 `cache_control` 的块会被缓存
* 缓存基于内容完全匹配，任何改动都会导致缓存失效
**最佳实践**：
* 将不变的长上下文（文档、代码库等）放在 `system` 中并启用缓存
* 对于长期稳定的内容，使用 `persistent` 缓存（1小时）
* 对于频繁变化的内容，使用 `ephemeral` 缓存（5分钟）
* 多轮对话时，可以缓存历史对话内容
* 定期监控 `cache_creation_input_tokens` 和 `cache_read_input_tokens` 以优化成本
## 响应格式
```json theme={null}
{
"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
}
}
```
**使用缓存时的 usage 字段**：
* `input_tokens`: 当前请求的非缓存输入 tokens
* `cache_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`: 消息结束
```json theme={null}
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` 字段：
```json theme={null}
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 | 系统内部错误 |
错误响应示例：
```json theme={null}
{
"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` 是必填参数，必须大于 0
* `messages` 数组不能为空
* 使用扩展思考时，`budget_tokens` 必须大于 1024
* 扩展思考需要启用流式输出才能看到思考过程
* 工具调用需要多轮交互，第一轮返回工具调用请求，第二轮返回工具执行结果
* 图像输入需要使用 base64 编码
* 使用流式输出可以提升首字响应时间和交互体验
* 工具调用需要做好超时与重试机制，避免阻塞模型响应
* 扩展思考功能可以显著提升复杂问题的推理质量
## 相关资源
查看 OpenAI 兼容的对话接口文档
查看所有支持的模型信息