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.

On this page
  1. Base URLs
  2. Authentication
  3. Endpoints
  4. Errors
  5. Request IDs
  6. Streaming
  7. Limits
  8. OpenAPI file
  9. Troubleshooting
  10. Related

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 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). If you set account spend caps, reaching one returns 402 spend_cap_reached. GET /v1/usage and the read-only video endpoints skip that check. See Authentication and Billing & top-ups.

#Endpoints

Method and path Purpose Key groups
POST /v1/chat/completions OpenAI Chat Completions All groups that serve text models
POST /v1/messages Anthropic Messages Anthropic groups; OpenAI groups that allow Messages dispatch. Not chat-only groups
POST /v1/messages/count_tokens Count input tokens Anthropic groups only
POST /v1/responses OpenAI Responses (Codex CLI) OpenAI and Anthropic groups. Not chat-only groups
GET /v1/models Models your group serves All groups
POST /v1/videos Create a video, avatar or video-tool task Pay-as-you-go keys
GET /v1/videos/{id} Task status and output link Same account that created the task
POST /v1/audio/speech Text to speech Pay-as-you-go keys
POST /v1/audio/generations Music, sound effects, audio tools Pay-as-you-go keys
POST /v1/workflows/short-drama Script to clips workflow Pay-as-you-go keys
GET /v1/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.

#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.

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.

#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 and Per-key limits & budgets.
  • 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 (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.

Updated · View as Markdown