# BigModel.io API reference

> Base URLs, authentication headers, error envelopes, request IDs, streaming and the full endpoint list for the BigModel.io OpenAI- and Anthropic-compatible API.

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

BigModel.io speaks the OpenAI and Anthropic HTTP protocols with one API key. Which endpoints and models a key can call depends on the key's **group**; the reference pages below say which groups each endpoint serves.

## Base URLs

| Client type | Base URL | Requests go to |
|---|---|---|
| OpenAI SDKs and OpenAI-compatible tools | `https://bigmodel.io/v1` | `https://bigmodel.io/v1/chat/completions`, `/v1/responses`, `/v1/models`, … |
| Anthropic SDKs, Claude Code | `https://bigmodel.io` (no `/v1`) | the client appends `/v1/messages` |

Every path in this reference is relative to `https://bigmodel.io/v1`.

## Authentication

Create a key in [API Keys](https://bigmodel.io/keys) and send it in a header. The gateway checks these headers in order and uses the first one present:

| Header | Value |
|---|---|
| `Authorization` | `Bearer sk-...` (the `Bearer` scheme is case-insensitive) |
| `x-api-key` | `sk-...` (what Anthropic SDKs send) |

```bash
curl https://bigmodel.io/v1/models \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

Keys in the query string are rejected: a request with `?key=` or `?api_key=` returns `400` `api_key_in_query_deprecated`, even if the key is valid. A missing key returns `401` `API_KEY_REQUIRED`; an unknown key `401` `INVALID_API_KEY`.

Text and model endpoints need a positive balance or an active plan; otherwise they return `403`. On `POST /v1/chat/completions`, `/v1/messages` and `/v1/responses`, models priced at $0 are the exception: they work at a zero balance (see [Trial credit & free models](https://bigmodel.io/docs/free-credits)). If you set account spend caps, reaching one returns `402` `spend_cap_reached`. [`GET /v1/usage`](https://bigmodel.io/docs/api-usage) and the read-only video endpoints skip that check. See [Authentication](https://bigmodel.io/docs/authentication) and [Billing & top-ups](https://bigmodel.io/docs/billing).

## Endpoints

| Method and path | Purpose | Key groups |
|---|---|---|
| [`POST /v1/chat/completions`](https://bigmodel.io/docs/api-chat-completions) | OpenAI Chat Completions | All groups that serve text models |
| [`POST /v1/messages`](https://bigmodel.io/docs/api-messages) | Anthropic Messages | Anthropic groups; OpenAI groups that allow Messages dispatch. Not chat-only groups |
| [`POST /v1/messages/count_tokens`](https://bigmodel.io/docs/api-count-tokens) | Count input tokens | Anthropic groups only |
| [`POST /v1/responses`](https://bigmodel.io/docs/api-responses) | OpenAI Responses (Codex CLI) | OpenAI and Anthropic groups. Not chat-only groups |
| [`GET /v1/models`](https://bigmodel.io/docs/api-models) | Models your group serves | All groups |
| [`POST /v1/videos`](https://bigmodel.io/docs/api-media-tasks) | Create a video, avatar or video-tool task | Pay-as-you-go keys |
| [`GET /v1/videos/{id}`](https://bigmodel.io/docs/api-media-tasks) | Task status and output link | Same account that created the task |
| [`POST /v1/audio/speech`](https://bigmodel.io/docs/text-to-speech) | Text to speech | Pay-as-you-go keys |
| [`POST /v1/audio/generations`](https://bigmodel.io/docs/audio-generation) | Music, sound effects, audio tools | Pay-as-you-go keys |
| [`POST /v1/workflows/short-drama`](https://bigmodel.io/docs/short-drama-workflow) | Script to clips workflow | Pay-as-you-go keys |
| [`GET /v1/usage`](https://bigmodel.io/docs/api-usage) | Key quota, balance and usage | All keys |

"Chat-only groups" are groups on the DeepSeek and GLM platforms. They serve only `/v1/chat/completions`; `/v1/messages`, `/v1/responses` and token counting return `404` `not_found_error` there.

## Errors

The JSON shape of an error depends on which layer rejected the request:

| Layer | Shape | Example |
|---|---|---|
| Key and balance checks (before routing) | `{"code": "...", "message": "..."}` | `INVALID_API_KEY`, `INSUFFICIENT_BALANCE` |
| `/v1/messages`, `count_tokens`, chat-only 404s | `{"type": "error", "error": {"type": "...", "message": "..."}}` | `not_found_error` |
| `/v1/chat/completions`, `/v1/responses` | `{"error": {"type": "...", "message": "..."}}` | `rate_limit_error` |
| Video endpoints | `{"error": {"type": "<code>", "message": "..."}}` | `insufficient_balance` |

Errors that happen after a stream has started arrive as an SSE `error` event, not as an HTTP status. A model your group does not serve, or a mistyped model ID, returns `503` `api_error` with "No available accounts", not `404`. The full code list with fixes is on [Errors](https://bigmodel.io/docs/errors).

## Request IDs

Every response carries an `X-Request-ID` header. If you send `X-Request-ID`, the gateway echoes it; otherwise it generates one. On some upstream paths it is replaced by the model provider's request ID. Log it and include it when you contact [support](https://bigmodel.io/support).

The header is not exposed to browsers through CORS. Call the API from your server, not from front-end code, so your key stays private.

## Streaming

Set `"stream": true` on Chat Completions, Messages or Responses to get server-sent events:

- Chat Completions: `chat.completion.chunk` events ending with `data: [DONE]`. The gateway always asks the upstream for a final usage chunk.
- Messages: Anthropic events (`message_start` … `message_stop`).
- Responses: Responses events (`response.created` … `response.completed`). `GET /v1/responses` is the WebSocket transport and returns `426` without an `Upgrade` header.

See [Streaming](https://bigmodel.io/docs/streaming).

## Limits

- Request bodies are limited to 256 MiB (`413` above that). Video create bodies are limited to 1 MiB.
- Concurrency and requests-per-minute limits apply per user and per group; per-key spend limits and quotas are optional. See [Limits & rate limits](https://bigmodel.io/docs/rate-limits) and [Per-key limits & budgets](https://bigmodel.io/docs/key-limits).
- The gateway sends no rate-limit headers of its own; upstream `x-ratelimit-*` and `retry-after` headers are passed through when present.

## OpenAPI file

The machine-readable description of these endpoints is at [`https://bigmodel.io/openapi.json`](https://bigmodel.io/openapi.json) (OpenAPI 3.1). The request and response tables on each reference page are generated from it. Import it into Postman, Insomnia or a client generator.

## Troubleshooting

**`400` `api_key_in_query_deprecated`**: the key is in the URL. Remove `?key=` / `?api_key=` and send `Authorization: Bearer`.

**`404` `not_found_error` on `/v1/messages` or `/v1/responses`**: the key belongs to a chat-only group. Use `/v1/chat/completions`, or a key from a group that serves the endpoint.

**`403` `INSUFFICIENT_BALANCE`**: the balance is zero or below. Top up in [Billing](https://bigmodel.io/purchase).

## Related

- [Quickstart](https://bigmodel.io/docs/quickstart)
- [Authentication](https://bigmodel.io/docs/authentication)
- [Errors](https://bigmodel.io/docs/errors)
- [Model catalog](https://bigmodel.io/models)