# Claude 消息接口
> 直接使用 Anthropic Messages 原生结构
> 适合需要 `system` 顶层字段、`tool_use`、思考模式等特性的场景
> 与 OpenAI 结构互不影响，可以按需混用
`POST /v1/messages`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 也兼容 `x-api-key`。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
- `anthropic-version` (string / 可选) — 不传时默认使用稳定版本。需要固定行为时可显式指定。
## 请求参数
- `model` (string / 必填) — Claude 模型 ID。
- `max_tokens` (integer / 必填) — 生成的最大 token 数。该字段在原生结构里是必填的，这一点与 OpenAI 不同。
- `messages` (array / 必填) — 消息数组，只允许 `user` 与 `assistant` 两种角色，且必须交替出现。系统提示不进这里。
- `messages[].role` (string / 必填) — 取值 `user` 或 `assistant`。
- `messages[].content` (string / array) — 消息正文。需要多模态或工具结果时传内容块数组，元素含 `type`。
- `messages[].content[].type` (string / 必填) — 内容块类型，取值 `text`、`image`、`tool_use`、`tool_result`。
- `messages[].content[].text` (string / 可选) — `type` 为 `text` 时的正文。
- `messages[].content[].source` (object / 可选) — `type` 为 `image` 时的图片来源，含 `type`（`base64` 或 `url`）、`media_type` 与 `data`。
- `system` (string / 可选) — 系统提示。放在顶层而不是 messages 里，这是与 OpenAI 结构最主要的差异。
- `temperature` (number / 可选) — 采样温度，取值 0 到 1。
- `top_p` (number / 可选) — 核采样阈值。
- `top_k` (integer / 可选) — 每步只从概率最高的 k 个 token 中采样。
- `stop_sequences` (array / 可选) — 停止序列数组。
- `stream` (boolean / 可选) — 是否流式返回。
- `tools` (array / 可选) — 工具清单。与 OpenAI 的 `function` 包装不同，这里直接给 `name`、`description`、`input_schema`。
- `tools[].name` (string / 必填) — 工具名。
- `tools[].description` (string / 可选) — 工具用途说明。
- `tools[].input_schema` (object / 必填) — 入参的 JSON Schema。
- `tool_choice.type` (string / 可选) — 取值 `auto`、`any` 或 `tool`。
- `thinking.type` (string / 可选) — 思考模式。开启后响应里会多出 `thinking` 内容块。
## 响应
- `id` (string) — 消息唯一标识，形如 `msg_`。
- `type` (string) — 固定为 `message`。
- `role` (string) — 固定为 `assistant`。
- `content` (array) — 内容块数组，可能含 `text`、`tool_use`、`thinking` 等多种类型。
- `stop_reason` (string) — 结束原因。`end_turn` 正常结束，`max_tokens` 触达上限，`tool_use` 发起工具调用。
- `usage.input_tokens` (integer) — 输入 token 数。
- `usage.output_tokens` (integer) — 输出 token 数。
## 两种结构的对应关系
| OpenAI | Claude 原生 | 说明 |
|---|---|---|
| `messages[].role = system` | `system` 顶层字段 | 系统提示的位置不同 |
| `max_tokens` 可选 | `max_tokens` 必填 | 原生结构必须显式给出上限 |
| `tools[].function` | `tools[]` 直接扁平 | 少一层包装 |
| `finish_reason` | `stop_reason` | 字段名不同，取值也不同 |
| `usage.prompt_tokens` | `usage.input_tokens` | 命名差异 |
## 支持的模型列表
以下模型均可通过本接口调用，清单由模型目录自动生成，实际可用范围以你的账号分组为准：
:::models anthropic
> **Note:** 想按上下文长度、价格或能力标签挑选模型，可查阅 [模型列表元数据接口](../models.html)，或直接读取 `GET /api/pricing`。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 基础对话
Claude 原生结构里 `max_tokens` 是必填项，不传会直接报错。系统提示放在顶层的 `system` 字段，不在 `messages` 数组里。
### 多轮对话
历史消息同样按顺序放进 `messages`，助手的回复用 `role: assistant` 回填。顶层 `system` 不需要重复，每轮都放一次即可。
### 使用系统提示词
`system` 支持字符串，也支持内容块数组。需要带缓存标记时用数组形式，把稳定部分标成可缓存。
### 流式响应
加 `"stream": true` 后返回 SSE 事件流。事件类型有 `message_start`、`content_block_delta`、`message_stop` 等，取增量文本看 `delta.text`。
### 工具使用
工具定义直接放在 `tools` 数组，比 OpenAI 结构少一层 `function` 包装。模型决定调用时，`stop_reason` 会变成 `tool_use`。
### 视觉理解
图片通过内容块传入，`type` 为 `image`，来源可以是 URL 或 base64。文字与图片可以混在同一个 `content` 数组里。
**基础对话{Basic chat}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "用一段话解释什么是向量数据库" }]
  }'
```
**基础对话{Basic chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1/messages"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "用一段话解释什么是向量数据库" }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**基础对话{Basic chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "用一段话解释什么是向量数据库" }]
  }),
});
console.log(await res.json());
```
**多轮对话{Multi-turn chat}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "你是技术顾问，回答控制在三段以内。",
    "messages": [
      { "role": "user", "content": "我们的 QPS 峰值是 3000，数据库该怎么选" },
      { "role": "assistant", "content": "先看读写比例和一致性要求，再决定单机还是分片。" },
      { "role": "user", "content": "读多写少的情况呢" }
    ]
  }'
```
**多轮对话{Multi-turn chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1/messages"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "你是技术顾问，回答控制在三段以内。",
    "messages": [
      { "role": "user", "content": "我们的 QPS 峰值是 3000，数据库该怎么选" },
      { "role": "assistant", "content": "先看读写比例和一致性要求，再决定单机还是分片。" },
      { "role": "user", "content": "读多写少的情况呢" }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多轮对话{Multi-turn chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "你是技术顾问，回答控制在三段以内。",
    "messages": [
      { "role": "user", "content": "我们的 QPS 峰值是 3000，数据库该怎么选" },
      { "role": "assistant", "content": "先看读写比例和一致性要求，再决定单机还是分片。" },
      { "role": "user", "content": "读多写少的情况呢" }
    ]
  }),
});
console.log(await res.json());
```
**使用系统提示词{Use system prompt}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一家 SaaS 公司的合规顾问。以下是产品条款全文：（此处省略长文本）",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [{ "role": "user", "content": "用户上传的数据会被用于训练吗" }]
  }'
```
**使用系统提示词{Use system prompt}::Python**
```
import requests
url = "https://api.oairoute.com/v1/messages"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一家 SaaS 公司的合规顾问。以下是产品条款全文：（此处省略长文本）",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [{ "role": "user", "content": "用户上传的数据会被用于训练吗" }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**使用系统提示词{Use system prompt}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一家 SaaS 公司的合规顾问。以下是产品条款全文：（此处省略长文本）",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [{ "role": "user", "content": "用户上传的数据会被用于训练吗" }]
  }),
});
console.log(await res.json());
```
**工具使用{Tool use}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_order_status",
      "description": "按订单号查询物流状态",
      "input_schema": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }],
    "messages": [{ "role": "user", "content": "帮我查一下订单 A1024 到哪了" }]
  }'
```
**工具使用{Tool use}::Python**
```
import requests
url = "https://api.oairoute.com/v1/messages"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_order_status",
      "description": "按订单号查询物流状态",
      "input_schema": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }],
    "messages": [{ "role": "user", "content": "帮我查一下订单 A1024 到哪了" }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**工具使用{Tool use}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_order_status",
      "description": "按订单号查询物流状态",
      "input_schema": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }],
    "messages": [{ "role": "user", "content": "帮我查一下订单 A1024 到哪了" }]
  }),
});
console.log(await res.json());
```
**视觉理解{Vision}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "这张架构图里有哪些组件" },
        { "type": "image", "source": { "type": "url", "url": "https://example.com/arch.png" } }
      ]
    }]
  }'
```
**视觉理解{Vision}::Python**
```
import requests
url = "https://api.oairoute.com/v1/messages"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "这张架构图里有哪些组件" },
        { "type": "image", "source": { "type": "url", "url": "https://example.com/arch.png" } }
      ]
    }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视觉理解{Vision}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "这张架构图里有哪些组件" },
        { "type": "image", "source": { "type": "url", "url": "https://example.com/arch.png" } }
      ]
    }]
  }),
});
console.log(await res.json());
```
**200 基础对话{Basic chat}**
```
{
  "id": "msg_01KA",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "向量数据库是专门存储和检索向量的数据库，按向量之间的距离找出语义最相近的内容，常用于语义搜索和检索增强生成。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 21,
    "output_tokens": 58
  }
}
```
**200 多轮对话{Multi-turn chat}**
```
{
  "id": "msg_01KB",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "读多写少时优先考虑主从复制加读写分离，再在前面加一层缓存承接热点读。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 86,
    "output_tokens": 41
  }
}
```
**200 使用系统提示词{Use system prompt}**
```
{
  "id": "msg_01KC",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "不会。条款规定用户上传的数据仅用于提供服务，不用于模型训练。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 33,
    "cache_creation_input_tokens": 2048,
    "cache_read_input_tokens": 0
  }
}
```
**200 工具使用{Tool use}**
```
{
  "id": "msg_01KD",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "我来查一下这个订单。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01KD",
      "name": "get_order_status",
      "input": {
        "order_id": "A1024"
      }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {
    "input_tokens": 412,
    "output_tokens": 56
  }
}
```
**200 视觉理解{Vision}**
```
{
  "id": "msg_01KE",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "图中有四个组件：负载均衡、API 网关、业务服务集群和数据库，请求自上而下依次经过。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1284,
    "output_tokens": 47
  }
}
```