# Create a message (Anthropic Messages)

> POST /v1/messages on BigModel.io. The Anthropic Messages API for Claude Code and Anthropic SDKs, with streaming, tools, extended thinking and prompt caching.

Web version: https://bigmodel.io/docs/api-messages · Updated 2026-10-18

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

The Anthropic Messages endpoint. Anthropic SDKs and Claude Code use the base URL `https://bigmodel.io` and append `/v1/messages` themselves. Anthropic groups serve it natively; OpenAI groups convert it when the group allows Messages dispatch; chat-only groups (DeepSeek, GLM platforms) return `404`.

## Request

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

### Authentication

| Header | Value |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

Send one of these.

### Headers

| Name | Type | Required | Description |
|---|---|---|---|
| `anthropic-version` | string |  | Anthropic API version header sent by Anthropic SDKs. |

### Body

Standard Anthropic Messages body.

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | Yes | Model ID, e.g. `glm-5.3`. |
| `max_tokens` | integer | Yes | Maximum tokens to generate. |
| `messages` | array<object> | Yes | Alternating user and assistant turns. |
| `messages[].role` | string | Yes | One of: `user`, `assistant` |
| `messages[].content` | string \| array<object> | Yes |  |
| `system` | string \| array<object> |  | System prompt. Blocks may carry `cache_control`. |
| `stream` | boolean |  | Stream Anthropic SSE events. Default `false` |
| `tools` | array<object> |  | Tools with `name`, `description` and `input_schema`. |
| `tool_choice` | object |  |  |
| `thinking` | object |  | Extended thinking settings, for models that support them. |
| `temperature` | number |  |  |
| `metadata` | object |  |  |
| `metadata.user_id` | string |  |  |

## Response

| Status | Meaning |
|---|---|
| `200` | A message, or Anthropic SSE events when `stream` is true. |
| `400` | `api_key_in_query_deprecated` (key sent in the query string), or `invalid_request_error`: empty or invalid JSON, missing `model`, a non-boolean `stream`, or another malformed field. |
| `401` | `API_KEY_REQUIRED`, `INVALID_API_KEY`, `API_KEY_DISABLED`, `USER_NOT_FOUND`, `USER_INACTIVE`. |
| `403` | `INSUFFICIENT_BALANCE`, `API_KEY_EXPIRED`, `ACCESS_DENIED` (IP rule), `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_INVALID`, or a `permission_error` (key without a group, endpoint not allowed for the group). |
| `404` | `not_found_error`: the key group only serves `/v1/chat/completions`. |
| `409` | `malformed_session_state`: the conversation history has thinking blocks or tool ids the model cannot accept. Start a new session. |
| `413` | Request body too large. |
| `429` | `API_KEY_QUOTA_EXHAUSTED`, `USAGE_LIMIT_EXCEEDED` (plan limit), or `rate_limit_exceeded` / `rate_limit_error` (key 5h/1d/7d limit, requests per minute, concurrency, upstream). RPM limits send `Retry-After`. |
| `502` | `upstream_error`: the model provider failed. |
| `503` | `api_error` and similar: no capacity for this model in your group right now, or the model is not served by your group (`No available accounts`). |

### Response fields

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `type` | any |  |
| `role` | any |  |
| `model` | string |  |
| `content` | array<object> | `text`, `thinking` and `tool_use` blocks. |
| `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 |  |

With `stream: true` the response is the Anthropic event stream: `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop`.


## Examples

```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": "You are a concise assistant.",
    "messages": [{"role": "user", "content": "Explain HTTP 429 in one sentence."}]
  }'
```

```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="You are a concise assistant.",
    messages=[{"role": "user", "content": "Explain HTTP 429 in one sentence."}],
)
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: 'You are a concise assistant.',
  messages: [{role: 'user', content: 'Explain HTTP 429 in one sentence.'}],
})
console.log(msg.content[0].text)
```

Example response (the `id`, text and token counts are illustrative):

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "glm-5.3",
  "content": [
    {"type": "text", "text": "HTTP 429 means you sent too many requests in a given time and should retry later."}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 21, "output_tokens": 19, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}
}
```

### Streaming

```python [Python]
with client.messages.stream(
    model="glm-5.3",
    max_tokens=256,
    messages=[{"role": "user", "content": "Count to 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: 'Count to 3.'}],
})
stream.on('text', text => process.stdout.write(text))
await stream.finalMessage()
```

### Prompt caching

```json
{
  "model": "glm-5.3",
  "max_tokens": 256,
  "system": [
    {"type": "text", "text": "<long, stable instructions>", "cache_control": {"type": "ephemeral"}}
  ],
  "messages": [{"role": "user", "content": "First question"}]
}
```

## Notes

- **Chat-only groups return `404`.** Keys in DeepSeek or GLM platform groups get `not_found_error` "… platform only supports /v1/chat/completions; /v1/messages is not available". Use [Chat Completions](https://bigmodel.io/docs/api-chat-completions) or a key from a group that serves Messages.
- **OpenAI groups** convert Messages only if the group allows it; otherwise `403` "This group does not allow /v1/messages dispatch".
- **`model` is required**; a missing one returns `400` `invalid_request_error`. An unserved or mistyped model returns `503` `api_error` "No available accounts", not `404`.
- **Prompt caching.** `cache_control` passes through. At most 4 breakpoints are kept; extras are removed from `tools` first, then `messages`, then `system`. `cache_control` on thinking blocks is stripped. Cache writes and reads are billed at the model's cache-write and cache-read prices. See [Prompt caching](https://bigmodel.io/docs/prompt-caching).
- **Thinking.** `thinking` and `output_config.effort` are read and forwarded. If the conversation history contains thinking blocks or tool IDs the model cannot accept, you get `409` `malformed_session_state`; start a new session. See [Reasoning & thinking](https://bigmodel.io/docs/reasoning).
- **`metadata.user_id`.** Send a stable value per conversation so its requests are handled consistently, which helps prompt caching.
- Errors use the Anthropic envelope `{"type":"error","error":{...}}`, except key checks, which use `{"code","message"}`. Mid-stream errors arrive as an SSE `error` event. Full list: [Errors](https://bigmodel.io/docs/errors).

## Related

- [Claude Code](https://bigmodel.io/docs/claude-code)
- [Anthropic SDK](https://bigmodel.io/docs/anthropic-sdk)
- [Count tokens](https://bigmodel.io/docs/api-count-tokens)
- [Prompt caching](https://bigmodel.io/docs/prompt-caching)