# 创建消息（Anthropic Messages）

> BigModel.io 的 POST /v1/messages 接口：供 Claude Code 和 Anthropic SDK 使用的 Anthropic Messages 协议，支持流式、工具、扩展思考和提示词缓存。

网页版: https://bigmodel.io/zh-cn/docs/api-messages · 更新于 2026-10-18

`POST https://bigmodel.io/v1/messages`

Anthropic Messages 接口。Anthropic SDK 和 Claude Code 的 Base URL 填 `https://bigmodel.io`，客户端会自己拼上 `/v1/messages`。Anthropic 分组原生提供；OpenAI 分组在允许 Messages 调度时会转换处理；仅对话补全分组（DeepSeek、GLM 平台）返回 `404`。

## 请求

```http
POST https://bigmodel.io/v1/messages
```

### 认证

| 请求头 | 值 |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

任选其一。

### 请求头

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `anthropic-version` | string |  | Anthropic SDK 发送的 API 版本请求头。 |

### 请求体

标准 Anthropic Messages 请求体。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID，例如 `glm-5.3`。 |
| `max_tokens` | integer | 是 | 最多生成的 token 数。 |
| `messages` | array<object> | 是 | 交替的 user 和 assistant 消息。 |
| `messages[].role` | string | 是 | 可选值：`user`, `assistant` |
| `messages[].content` | string \| array<object> | 是 |  |
| `system` | string \| array<object> |  | 系统提示词，内容块可带 `cache_control`。 |
| `stream` | boolean |  | 以 Anthropic SSE 流式返回。 默认 `false` |
| `tools` | array<object> |  | 工具定义（`name`、`description`、`input_schema`）。 |
| `tool_choice` | object |  |  |
| `thinking` | object |  | 扩展思考设置（仅支持的模型）。 |
| `temperature` | number |  |  |
| `metadata` | object |  |  |
| `metadata.user_id` | string |  |  |

## 响应

| 状态码 | 含义 |
|---|---|
| `200` | 消息结果；`stream` 为 true 时为 Anthropic SSE 事件流。 |
| `400` | `api_key_in_query_deprecated`（Key 放在了查询参数里），或 `invalid_request_error`：请求体为空或不是合法 JSON、缺少 `model`、`stream` 不是布尔值等。 |
| `401` | `API_KEY_REQUIRED`、`INVALID_API_KEY`、`API_KEY_DISABLED`、`USER_NOT_FOUND`、`USER_INACTIVE`。 |
| `403` | `INSUFFICIENT_BALANCE`、`API_KEY_EXPIRED`、`ACCESS_DENIED`（IP 规则）、`SUBSCRIPTION_NOT_FOUND`、`SUBSCRIPTION_INVALID`，或 `permission_error`（Key 未分配分组、分组不允许该接口）。 |
| `404` | `not_found_error`：该 Key 所在分组只提供 `/v1/chat/completions`。 |
| `409` | `malformed_session_state`：对话历史中的思考块或工具 ID 无法被模型接受，请开新会话。 |
| `413` | 请求体过大。 |
| `429` | `API_KEY_QUOTA_EXHAUSTED`、`USAGE_LIMIT_EXCEEDED`（套餐额度），或 `rate_limit_exceeded` / `rate_limit_error`（Key 的 5 小时/1 天/7 天限额、每分钟请求数、并发、上游限流）。每分钟限流会带 `Retry-After`。 |
| `502` | `upstream_error`：模型服务商出错。 |
| `503` | `api_error` 等：分组暂时没有该模型的可用容量，或分组不提供该模型（`No available accounts`）。 |

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string |  |
| `type` | any |  |
| `role` | any |  |
| `model` | string |  |
| `content` | array<object> | `text`、`thinking`、`tool_use` 内容块。 |
| `stop_reason` | string | `end_turn`, `max_tokens`, `tool_use`, … |
| `usage` | object |  |
| `usage.input_tokens` | integer |  |
| `usage.output_tokens` | integer |  |
| `usage.cache_creation_input_tokens` | integer |  |
| `usage.cache_read_input_tokens` | integer |  |

`stream: true` 时返回 Anthropic 事件流：`message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta`、`message_stop`。


## 示例

```bash [cURL]
curl https://bigmodel.io/v1/messages \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "max_tokens": 256,
    "system": "你是一个简洁的助手。",
    "messages": [{"role": "user", "content": "用一句话解释 HTTP 429。"}]
  }'
```

```python [Python]
import os
from anthropic import Anthropic

client = Anthropic(base_url="https://bigmodel.io", api_key=os.environ["BIGMODEL_API_KEY"])

msg = client.messages.create(
    model="glm-5.3",
    max_tokens=256,
    system="你是一个简洁的助手。",
    messages=[{"role": "user", "content": "用一句话解释 HTTP 429。"}],
)
print(msg.content[0].text)
```

```js [Node.js]
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({baseURL: 'https://bigmodel.io', apiKey: process.env.BIGMODEL_API_KEY})

const msg = await client.messages.create({
  model: 'glm-5.3',
  max_tokens: 256,
  system: '你是一个简洁的助手。',
  messages: [{role: 'user', content: '用一句话解释 HTTP 429。'}],
})
console.log(msg.content[0].text)
```

响应示例（`id`、文本和 token 数仅作示意）：

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "glm-5.3",
  "content": [
    {"type": "text", "text": "HTTP 429 表示你在一段时间内请求过多，需要稍后重试。"}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 21, "output_tokens": 19, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}
}
```

### 流式输出

```python [Python]
with client.messages.stream(
    model="glm-5.3",
    max_tokens=256,
    messages=[{"role": "user", "content": "从 1 数到 3。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

```js [Node.js]
const stream = client.messages.stream({
  model: 'glm-5.3',
  max_tokens: 256,
  messages: [{role: 'user', content: '从 1 数到 3。'}],
})
stream.on('text', text => process.stdout.write(text))
await stream.finalMessage()
```

### 提示词缓存

```json
{
  "model": "glm-5.3",
  "max_tokens": 256,
  "system": [
    {"type": "text", "text": "<较长且稳定的指令>", "cache_control": {"type": "ephemeral"}}
  ],
  "messages": [{"role": "user", "content": "第一个问题"}]
}
```

## 说明

- **仅对话补全分组返回 `404`。** DeepSeek、GLM 平台分组的 Key 会收到 `not_found_error`："… platform only supports /v1/chat/completions; /v1/messages is not available"。请改用[对话补全](https://bigmodel.io/zh-cn/docs/api-chat-completions)，或换一个提供 Messages 的分组的 Key。
- **OpenAI 分组**只有在分组允许时才转换 Messages 请求，否则返回 `403`："This group does not allow /v1/messages dispatch"。
- **`model` 必填**，缺少时返回 `400` `invalid_request_error`。分组不提供或拼错的模型返回 `503` `api_error`（"No available accounts"），不是 `404`。
- **提示词缓存。** `cache_control` 会透传。最多保留 4 个缓存断点，多余的依次从 `tools`、`messages`、`system` 中移除。thinking 块上的 `cache_control` 会被去掉。缓存写入和读取分别按模型的缓存写入价、缓存读取价计费。详见[提示词缓存](https://bigmodel.io/zh-cn/docs/prompt-caching)。
- **思考。** `thinking` 和 `output_config.effort` 会被读取并转发。如果对话历史中的思考块或工具 ID 无法被模型接受，会返回 `409` `malformed_session_state`，请开新会话。详见[推理与思考](https://bigmodel.io/zh-cn/docs/reasoning)。
- **`metadata.user_id`。** 同一会话发送固定的值，会话中的请求会被一致地处理，有助于提示缓存命中。
- 错误使用 Anthropic 结构 `{"type":"error","error":{...}}`，Key 检查阶段的错误除外（`{"code","message"}`）。流式过程中的错误以 SSE `error` 事件返回。完整列表见[错误码](https://bigmodel.io/zh-cn/docs/errors)。

## 相关文档

- [Claude Code](https://bigmodel.io/zh-cn/docs/claude-code)
- [Anthropic SDK](https://bigmodel.io/zh-cn/docs/anthropic-sdk)
- [计算 token](https://bigmodel.io/zh-cn/docs/api-count-tokens)
- [提示词缓存](https://bigmodel.io/zh-cn/docs/prompt-caching)