> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Text API > Call BeatAPI's text models with one API key through OpenAI Chat Completions, OpenAI Responses, Anthropic Messages or Gemini-native requests. * BeatAPI serves its text models as a synchronous, token-metered API. Keep one BeatAPI key and send the request format your application already uses. * One key for every text model, and one base URL: `https://direct.beatapi.io` (recommended) or `https://api.beatapi.io` (fallback). * Four request formats: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Gemini native. Which one you use depends on the family; see the table below. * Text calls return JSON immediately or stream server-sent events. They never create an asynchronous BeatAPI task. * `GET /v1/text/models` is public: read model IDs, context windows, output limits and prices without a key. > **Note** > > Use `https://direct.beatapi.io` as the base URL for text requests: it is not subject to Cloudflare's 100-second limit, so a long non-streaming request is not cut off. `https://api.beatapi.io` also works and is the fallback if `direct.beatapi.io` is unreachable from your network. The key, models and prices are the same on both. Image and video APIs use `https://api.beatapi.io` only. ## Choose a protocol | Protocols | Endpoint | SDK | Families | | ----------------------- | --------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OpenAI Chat Completions | `POST /v1/chat/completions` | OpenAI SDK (`chat.completions`) | [GPT](/text-api/gpt/chat-completions), [Gemini](/text-api/gemini/chat-completions), [Grok](/text-api/grok/chat-completions), [DeepSeek](/text-api/deepseek/chat-completions), [GLM](/text-api/glm/chat-completions), [Qwen](/text-api/qwen/chat-completions), [Kimi](/text-api/kimi/chat-completions), [MiniMax](/text-api/minimax/chat-completions), [MiMo](/text-api/mimo/chat-completions), [Hunyuan](/text-api/hunyuan/chat-completions), [Muse](/text-api/muse/chat-completions) | | OpenAI Responses | `POST /v1/responses` | OpenAI SDK (`responses`) | [GPT](/text-api/gpt/responses), [Gemini](/text-api/gemini/responses), [Grok](/text-api/grok/responses), [DeepSeek](/text-api/deepseek/responses), [GLM](/text-api/glm/responses), [Qwen](/text-api/qwen/responses), [Kimi](/text-api/kimi/responses), [MiniMax](/text-api/minimax/responses), [MiMo](/text-api/mimo/responses), [Hunyuan](/text-api/hunyuan/responses), [Muse](/text-api/muse/responses) | | Anthropic Messages | `POST /v1/messages` | Anthropic SDK (`messages`) | [Claude](/text-api/claude/messages), [Gemini](/text-api/gemini/messages), [Grok](/text-api/grok/messages), [DeepSeek](/text-api/deepseek/messages), [GLM](/text-api/glm/messages), [Qwen](/text-api/qwen/messages), [Kimi](/text-api/kimi/messages), [MiniMax](/text-api/minimax/messages), [MiMo](/text-api/mimo/messages), [Hunyuan](/text-api/hunyuan/messages), [Muse](/text-api/muse/messages) | | Gemini native | `POST /v1beta/models/{model}:generateContent` | Gemini SDK or plain HTTP | [Gemini](/text-api/gemini/native) | ## Base URL and authentication Use `https://direct.beatapi.io` for text requests; it is not subject to Cloudflare's 100-second limit. `https://api.beatapi.io` is the fallback. Send the key in the header your SDK already uses; they all identify the same BeatAPI account and USD balance. The key works with or without the `sk-` prefix. | Format | Key header | | ----------------------------------------- | --------------------------------------------------------------- | | OpenAI Chat Completions, OpenAI Responses | `Authorization: Bearer ` | | Anthropic Messages | `x-api-key: `, or `Authorization: Bearer` | | Gemini native | `x-goog-api-key: `, or `Authorization: Bearer` | > **Note** > > Store permanent BeatAPI API keys on trusted servers. Never ship them in a browser or mobile app. ## Which format to use for which model * **GPT** is called on OpenAI Chat Completions or OpenAI Responses. For new reasoning and tool-calling integrations, Responses is the recommended format. * **Claude** is called on Anthropic Messages (`POST /v1/messages`). * **Gemini** can be called in all four formats: Chat Completions, Responses, Anthropic Messages and Gemini native. * **Every other family** can be called on Chat Completions, Responses and Anthropic Messages. Messages requests carry the `anthropic-version` header. If you are unsure, use Chat Completions. ## Quick start **`cURL`** ```bash title="cURL" curl --request POST \ --url https://direct.beatapi.io/v1/chat/completions \ --header "Authorization: Bearer $BEATAPI_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "glm-5.3", "messages": [{ "role": "user", "content": "Say hello in one sentence." }] }' ``` **`Python`** ```python title="Python" import os from openai import OpenAI client = OpenAI(api_key=os.environ["BEATAPI_API_KEY"], base_url="https://direct.beatapi.io/v1") completion = client.chat.completions.create( model="glm-5.3", messages=[{"role": "user", "content": "Say hello in one sentence."}], ) print(completion.choices[0].message.content) ``` **`JavaScript`** ```javascript title="JavaScript" import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.BEATAPI_API_KEY, baseURL: "https://direct.beatapi.io/v1", }); const completion = await client.chat.completions.create({ model: "glm-5.3", messages: [{ role: "user", content: "Say hello in one sentence." }], }); console.log(completion.choices[0].message.content); ``` ## Find the models ### `GET /v1/text/models` Public and anonymous: no key needed. Call it on `https://api.beatapi.io/v1/text/models`; `direct.beatapi.io` serves model calls, not this list. It returns one entry per model in `data.data`: | Field | Meaning | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The model ID to send as `model`. | | `family` | The group the model is routed and billed under. A key must be able to reach the family to call the model. | | `endpoints` | The formats the model's line speaks natively: `openai` (Chat Completions), `anthropic` (Messages), `openai-response` (Responses). It is **not** the full list of formats you can call. The family pages, not this field, say which formats are documented for a model. | | `context_length` | Context window in tokens. Omitted when not published. | | `max_output_tokens` | Largest output in tokens. Omitted when not published. | | `input_usd_per_million`, `output_usd_per_million` | Our price in USD per 1M tokens, discount already applied. This is the base tier: a long-context tier is not included. | | `discount` | Our price is the listed price multiplied by `discount` (`0.7` means 30% off the list price). Omitted when it is 1. | | `time_rules` | Peak-time price multipliers, with the condition and whether each is active now. Omitted when the model has none. | | `capabilities` | Free-form labels such as reasoning or tools. Advisory, not a contract. | | `description` | A short description. | Free models (IDs ending in `-free`) list only `id`, `family` and `endpoints`: no price, context window or description is published for them. See [Free models](/free-models). The list contains text models only. ### `GET /v1/models` Requires a key. Returns the models that key can call, in the OpenAI list shape (`id`, `object`, `created`, `owned_by`, `supported_endpoint_types`) wrapped in `data`. With `x-api-key` and `anthropic-version` it answers the Anthropic list shape; with `x-goog-api-key` or `?key=` it answers the Gemini list shape. It leaves out models the key's group cannot reach and, on free credit, models the account may not use. It is not rate limited. ## Streaming Set `"stream": true` on Chat Completions, Responses and Messages. For Gemini native, call `:streamGenerateContent?alt=sse`. The response is `text/event-stream`; without streaming it is `application/json`. A failure that happens before the model is called is returned as a normal JSON error with an HTTP status, not as a stream event. ## `max_tokens` and output limits * The largest value the gateway accepts for `max_tokens` (Chat Completions and Messages), `max_output_tokens` (Responses) is 1,073,741,823. A larger value is `400 bad_request`. * The gateway does **not** compare your value with the model's `max_output_tokens` from the catalogue. Keep it at or below that number; what happens above it is decided by the model's line and is not guaranteed. * `max_tokens` is also used to estimate how much balance a request needs. A very large value can be refused with `402 insufficient_credits` even though the real output would be small. Set it to what you need. ## Rate limits * Each account has a per-minute limit on successful requests that **rises with the account's lifetime top-ups**. Redeem codes, referral bonuses and promotional credits do not count towards it. The numbers are not published as a table; read your own limit and the next tier in the dashboard. * A request holds its slot while it is running, and a failed request gives the slot back. * `GET /v1/models` is not rate limited. * Free models have their own separate limit; see [Free models](/free-models). * When you hit a limit, the answer is `429 rate_limit_exceeded` with `retry_after_seconds` and a `Retry-After` header. Wait that long, then retry. ## Errors A text call can fail in two stages, and the two stages have different bodies. [Errors](/errors#text-endpoints) has the full code table and retry policy; this is the short version. **1. Before the model is called.** On `/v1/chat/completions`, `/v1/responses` and `/v1/messages`, the BeatAPI error envelope: `code`, `message`, `retryable` and `request_id`, plus `retry_after_seconds` on a `429`. The Gemini-native endpoints (`/v1beta/...`) and `GET /v1/models` are not envelope surfaces: their errors look like `{"error":{"message":"... (request id: ...)","type":"beatapi_error","code":...}}` with no `retryable` or `retry_after_seconds`, though a `429` still carries the `Retry-After` header. | HTTP | Code | Cause | | ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401` | `missing_api_key`, `invalid_api_key` | No key, or a wrong, expired, disabled or exhausted one. | | `403` | `forbidden` | The account is on free credit and the model is not on the free list, the request is outside the key's IP allowlist, or the model is outside the key's group. | | `404` | `not_found` | Unknown or not routable model for this key. List the models with `GET /v1/models`. | | `429` | `rate_limit_exceeded` | Account or free-model limit reached. Wait `retry_after_seconds`. | ```json { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded: this model allows at most 10 successful requests per minute per account. Retry after 60 seconds.", "retryable": true, "request_id": "req_abc123", "retry_after_seconds": 60 } } ``` An unknown model is `404 not_found`: `The requested model is not available to this key: check the model id against GET /v1/models, or retry in a few minutes if it worked before.` **2. During the call.** The body keeps the SDK's native shape, so the OpenAI and Anthropic SDKs parse it and raise their usual exceptions. A refusal the gateway raises itself uses a BeatAPI code (`insufficient_credits`, `content_policy_violation`, `bad_request`, `not_found` or `internal_error`): `error.type` is `beatapi_error` and the code is in `error.code`; on `/v1/messages` the code is in `error.type`. A failure on the model's side is rewritten with the code `temporary_error`, `upstream_timeout`, `model_unavailable` or `rate_limit_exceeded` and keeps its status, except that `502` and `504` become `503` (a fault on our account with the supplier is `503 model_unavailable`). An English parameter error from the model, such as a context that is too long, is passed on as a sentence so you can fix the input. The request id is appended to every `message` in this stage. There is no `retryable` field and no `Retry-After` is promised on a `429` here; use the status and the code. See [Errors](/errors#text-endpoints). ```json { "error": { "message": "This API key's remaining quota is below the price of this request. Raise the key's quota in the console or use another key. (request id: req_abc123)", "type": "beatapi_error", "param": "", "code": "insufficient_credits" } } ``` Retry only `429`, `500` and `503`, with backoff. ## All text models Every current text model, generated from the gateway catalogue. Click a family for its protocol pages. Prices are what BeatAPI charges, USD per 1M tokens. | Model ID | Family | Context (tokens) | Max output (tokens) | Input, USD per 1M tokens | Output, USD per 1M tokens | Protocols | | ------------------------- | ----------------------------------------------- | ---------------- | ------------------- | ------------------------ | ------------------------- | ---------------------------------------------------- | | `gpt-6.1-sol` | [GPT](/text-api/gpt/responses) | 1,050,000 | 128,000 | \$0.80 | \$4.00 | Chat Completions, Responses | | `gpt-6-astra` | [GPT](/text-api/gpt/responses) | 1,000,000 | 128,000 | \$4.00 | \$20.00 | Chat Completions, Responses | | `gpt-6-sol` | [GPT](/text-api/gpt/responses) | 1,050,000 | 128,000 | \$0.80 | \$4.00 | Chat Completions, Responses | | `gpt-6-luna` | [GPT](/text-api/gpt/responses) | 1,050,000 | 128,000 | \$0.04 | \$0.20 | Chat Completions, Responses | | `claude-opus-5-5` | [Claude](/text-api/claude/messages) | 1,000,000 | 128,000 | \$2.00 | \$10.00 | Messages | | `claude-sonnet-5-5` | [Claude](/text-api/claude/messages) | 1,000,000 | 128,000 | \$1.00 | \$5.00 | Messages | | `claude-haiku-5-5` | [Claude](/text-api/claude/messages) | 1,000,000 | 128,000 | \$0.05 | \$0.25 | Messages | | `claude-fable-5-1` | [Claude](/text-api/claude/messages) | 1,000,000 | 128,000 | \$5.00 | \$25.00 | Messages | | `gemini-4-argon` | [Gemini](/text-api/gemini/chat-completions) | — | 1,000,000 | \$1.00 | \$5.00 | Chat Completions, Responses, Messages, Gemini native | | `gemini-3.8-flash` | [Gemini](/text-api/gemini/chat-completions) | — | — | \$0.375 | \$1.875 | Chat Completions, Responses, Messages, Gemini native | | `gemini-3.1-pro-preview` | [Gemini](/text-api/gemini/chat-completions) | 1,048,576 | 65,536 | \$1.00 | \$6.00 | Chat Completions, Responses, Messages, Gemini native | | `grok-4.7` | [Grok](/text-api/grok/chat-completions) | 500,000 | — | \$0.70 | \$2.10 | Chat Completions, Responses, Messages | | `deepseek-v4.1-flash` | [DeepSeek](/text-api/deepseek/chat-completions) | — | — | \$0.075 | \$0.30 | Chat Completions, Responses, Messages | | `deepseek-v4-pro-0813` | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000 | 128,000 | \$0.33 | \$0.99 | Chat Completions, Responses, Messages | | `deepseek-v4.1-flash-hc` | [DeepSeek](/text-api/deepseek/chat-completions) | — | — | \$0.105\* | \$0.42\* | Chat Completions, Responses, Messages | | `deepseek-v4-pro-0813-hc` | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000 | 128,000 | \$0.462\* | \$1.386\* | Chat Completions, Responses, Messages | | `glm-5.3` | [GLM](/text-api/glm/chat-completions) | 1,000,000 | 128,000 | \$0.98 | \$3.08 | Chat Completions, Responses, Messages | | `glm-5.3-flash` | [GLM](/text-api/glm/chat-completions) | 1,000,000 | 128,000 | \$0.105 | \$0.35 | Chat Completions, Responses, Messages | | `glm-5.3-flashx` | [GLM](/text-api/glm/chat-completions) | 1,000,000 | 128,000 | \$0.259 | \$0.875 | Chat Completions, Responses, Messages | | `qwen3.8-max` | [Qwen](/text-api/qwen/chat-completions) | 1,000,000 | 128,000 | \$1.40 | \$4.20 | Chat Completions, Responses, Messages | | `qwen3.8-flash` | [Qwen](/text-api/qwen/chat-completions) | — | — | \$0.105 | \$0.329 | Chat Completions, Responses, Messages | | `kimi-k3` | [Kimi](/text-api/kimi/chat-completions) | 1,048,576 | 128,000 | \$2.10 | \$10.50 | Chat Completions, Responses, Messages | | `MiniMax-M3` | [MiniMax](/text-api/minimax/chat-completions) | 1,048,576 | 128,000 | \$0.21 | \$0.84 | Chat Completions, Responses, Messages | | `MiniMax-M3.1-Flash` | [MiniMax](/text-api/minimax/chat-completions) | 1,000,000 | — | \$0.135 | \$0.54 | Chat Completions, Responses, Messages | | `mimo-v2.6-flash` | [MiMo](/text-api/mimo/chat-completions) | 1,048,576 | 128,000 | \$0.098 | \$0.196 | Chat Completions, Responses, Messages | | `mimo-v2.5` | [MiMo](/text-api/mimo/chat-completions) | 1,048,576 | 128,000 | \$0.098 | \$0.196 | Chat Completions, Responses, Messages | | `hy4-preview` | [Hunyuan](/text-api/hunyuan/chat-completions) | — | — | \$0.5838 | \$1.7507 | Chat Completions, Responses, Messages | | `hy3` | [Hunyuan](/text-api/hunyuan/chat-completions) | 256,000 | 64,000 | \$0.05775\* | \$0.231\* | Chat Completions, Responses, Messages | | `muse-wonder` | [Muse](/text-api/muse/chat-completions) | 1,048,576 | 131,072 | \$4.00 | \$20.00 | Chat Completions, Responses, Messages | * Prices are the base tier, discount already applied. A long-context tier, cached-input rates and cache writes are not in this table; see the [price table](https://beatapi.io/pricing). * `—` means the catalogue does not publish the number. * \* A peak-time multiplier applies in the model's peak window; the price shown is the off-peak base price. ## Free models Free models have no per-token charge and separate per-minute limits. They are documented on [Free models](/free-models); each one is the free version of the paid model in the last column. | Model ID | Family | Paid version | Price | | ----------------------------- | -------- | ------------------------ | ----- | | `deepseek-v4.1-flash-free` | DeepSeek | `deepseek-v4.1-flash` | Free | | `deepseek-v4-flash-0731-free` | DeepSeek | `deepseek-v4-flash-0731` | Free | | `glm-5.3-free` | GLM | `glm-5.3` | Free | | `glm-5.3-flash-free` | GLM | `glm-5.3-flash` | Free | | `gemini-3.8-flash-free` | Gemini | `gemini-3.8-flash` | Free | ## Legacy models Older model IDs that still work are listed on [Legacy models](/text-api/legacy-models), with the current model to move to.