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

# Текстовый API

> Вызывайте текстовые модели BeatAPI с одним API-ключом в форматах OpenAI Chat Completions, OpenAI Responses, Anthropic Messages или нативного API Gemini.

* Текстовые модели BeatAPI работают через синхронный API с оплатой по числу токенов. Используйте один ключ BeatAPI и привычный вашему приложению формат запроса.
* Один ключ для всех текстовых моделей и один базовый URL: `https://direct.beatapi.io` (рекомендуется) либо `https://api.beatapi.io` (запасной адрес).
* Четыре формата запросов: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages и нативный API Gemini. Доступные форматы зависят от семейства; см. таблицу ниже.
* Текстовые вызовы возвращают JSON напрямую или потоком SSE. Асинхронная задача BeatAPI при этом не создаётся.
* `GET /v1/text/models` доступен публично: ID моделей, размеры контекста, лимиты вывода и цены можно получить без ключа.

> **Note**
>
> Для текстовых запросов используйте базовый URL `https://direct.beatapi.io`. Этот адрес не ограничен 100-секундным тайм-аутом Cloudflare, который может прервать долгий запрос без потоковой передачи. Если ваша сеть не может подключиться к нему, используйте `https://api.beatapi.io`. Ключи, модели и цены одинаковы. API изображений и видео используют только `https://api.beatapi.io`.

## Выбор протокола

| Протоколы               | Эндпоинт                                      | SDK                             | Семейства                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | --------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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)                                                                                   |
| Нативный API Gemini     | `POST /v1beta/models/{model}:generateContent` | Gemini SDK или HTTP             | [Gemini](/text-api/gemini/native)                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## Базовый URL и авторизация

Для текстовых запросов используйте `https://direct.beatapi.io`: на этот адрес не распространяется 100-секундный лимит Cloudflare. Запасной адрес — `https://api.beatapi.io`. Передавайте ключ в том заголовке, который использует ваш SDK: все варианты указывают на один аккаунт BeatAPI и баланс в USD. Ключ работает как с префиксом `sk-`, так и без него.

| Формат                                    | Заголовок с ключом                                              |
| ----------------------------------------- | --------------------------------------------------------------- |
| OpenAI Chat Completions, OpenAI Responses | `Authorization: Bearer <BEATAPI_API_KEY>`                       |
| Anthropic Messages                        | `x-api-key: <BEATAPI_API_KEY>` или `Authorization: Bearer`      |
| Нативный API Gemini                       | `x-goog-api-key: <BEATAPI_API_KEY>` или `Authorization: Bearer` |

> **Note**
>
> Храните постоянные API-ключи BeatAPI на доверенных серверах. Не включайте их в браузерные или мобильные приложения.

## Какой формат выбрать для модели

* **GPT** вызывается через OpenAI Chat Completions или OpenAI Responses. Для новых интеграций с рассуждениями и инструментами рекомендуется Responses.
* **Claude** вызывается через Anthropic Messages (`POST /v1/messages`).
* **Gemini** доступна во всех четырёх форматах: Chat Completions, Responses, Anthropic Messages и нативный API Gemini.
* **Все остальные семейства** доступны через Chat Completions, Responses и Anthropic Messages. Запросы Messages должны содержать заголовок `anthropic-version`. Если не уверены, используйте Chat Completions.

## Быстрый старт

**`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);
```

## Как найти модели

### `GET /v1/text/models`

Публичный метод, не требующий ключа. Вызывайте `https://api.beatapi.io/v1/text/models`: `direct.beatapi.io` обслуживает вызовы моделей, но не этот список. Каждая модель представлена отдельной записью в `data.data`:

| Поле                                              | Значение                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                              | ID модели, который нужно передавать в `model`.                                                                                                                                                                                                                                            |
| `family`                                          | Группа маршрутизации и тарификации модели. Чтобы вызвать модель, ключ должен иметь доступ к её семейству.                                                                                                                                                                                 |
| `endpoints`                                       | Форматы, нативно поддерживаемые маршрутом, который обслуживает модель: `openai` (Chat Completions), `anthropic` (Messages), `openai-response` (Responses). Это **не** полный список доступных форматов вызова. Документированные форматы указаны на страницах семейств, а не в этом поле. |
| `context_length`                                  | Контекстное окно в токенах. Отсутствует, если значение не опубликовано.                                                                                                                                                                                                                   |
| `max_output_tokens`                               | Максимальный вывод в токенах. Отсутствует, если значение не опубликовано.                                                                                                                                                                                                                 |
| `input_usd_per_million`, `output_usd_per_million` | Цена BeatAPI в USD за 1M токенов с учётом скидки. Это базовый тариф без надбавки за длинный контекст.                                                                                                                                                                                     |
| `discount`                                        | Цена равна опубликованной цене, умноженной на `discount` (`0.7` означает скидку 30%). Поле отсутствует при значении 1.                                                                                                                                                                    |
| `time_rules`                                      | Множители цены в часы пик: условие и признак того, действует ли оно сейчас. Поле отсутствует у моделей без таких правил.                                                                                                                                                                  |
| `capabilities`                                    | Произвольные метки, например рассуждения или инструменты. Это подсказки, а не гарантии API.                                                                                                                                                                                               |
| `description`                                     | Краткое описание.                                                                                                                                                                                                                                                                         |

У бесплатных моделей (ID с окончанием `-free`) опубликованы только `id`, `family` и `endpoints`, без цены, контекстного окна и описания. См. [Бесплатные модели](/free-models).

Список содержит только текстовые модели.

### `GET /v1/models`

Требует ключ. Возвращает доступные этому ключу модели в формате списка OpenAI (`id`, `object`, `created`, `owned_by`, `supported_endpoint_types`), обёрнутом в `data`. С заголовками `x-api-key` и `anthropic-version` возвращается формат списка Anthropic; с `x-goog-api-key` или `?key=` — формат списка Gemini. Модели, недоступные группе ключа, а при использовании регистрационного бонуса и модели, недоступные аккаунту, исключаются. Частота запросов к этому методу не ограничена.

## Потоковая передача

В Chat Completions, Responses и Messages установите `"stream": true`. Для нативного API Gemini используйте `:streamGenerateContent?alt=sse`. Тип ответа — `text/event-stream`; без потоковой передачи — `application/json`. Ошибка до вызова модели возвращается обычным JSON-ответом с HTTP-кодом, а не событием потока.

## `max_tokens` и ограничения вывода

* Максимальное значение, которое шлюз принимает для `max_tokens` (Chat Completions и Messages) и `max_output_tokens` (Responses), — 1 073 741 823. Превышение возвращает `400 bad_request`.
* Шлюз **не** сравнивает указанное значение с `max_output_tokens` модели в каталоге. Не превышайте этот предел: поведение выше него зависит от обслуживающей модель линии и не гарантируется.
* `max_tokens` также используется для оценки необходимого баланса. Слишком большое значение может привести к `402 insufficient_credits`, даже если фактический ответ был бы коротким. Указывайте столько токенов, сколько требуется задаче.

## Ограничения частоты запросов

* У каждого аккаунта есть минутный лимит успешных запросов, который **повышается с общей суммой пополнений за всё время**. Коды пополнения, реферальные бонусы и промокредиты не учитываются. Таблица уровней не публикуется; свой лимит и следующий уровень можно посмотреть в панели управления.
* Выполняющийся запрос занимает место в лимите; при ошибке это место освобождается.
* Частота запросов `GET /v1/models` не ограничена.
* У бесплатных моделей отдельный лимит; см. [Бесплатные модели](/free-models).
* При превышении возвращается `429 rate_limit_exceeded` с `retry_after_seconds` и заголовком `Retry-After`. Подождите указанное время и повторите запрос.

## Ошибки

Текстовый запрос может завершиться ошибкой на двух этапах, причём формат ответа зависит от этапа. Полная таблица кодов и правила повторных попыток приведены в разделе [Ошибки](/errors#text-endpoints); ниже — краткое описание.

**1. До вызова модели.** Для `/v1/chat/completions`, `/v1/responses` и `/v1/messages` используется формат ошибок BeatAPI: `code`, `message`, `retryable` и `request_id`, а при `429` также `retry_after_seconds`. Нативные методы Gemini (`/v1beta/...`) и `GET /v1/models` не используют этот формат. Их ошибки имеют вид `{"error":{"message":"... (request id: ...)","type":"beatapi_error","code":...}}`, без `retryable` и `retry_after_seconds`, хотя при `429` по-прежнему передаётся заголовок `Retry-After`.

| HTTP  | Код                                  | Причина                                                                                                                                                     |
| ----- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | `missing_api_key`, `invalid_api_key` | Ключ не передан, неверен, просрочен, отключён или исчерпал лимит.                                                                                           |
| `403` | `forbidden`                          | На аккаунте только регистрационный бонус, а модель не входит в разрешённый список; IP-адрес запроса не разрешён ключу; либо модель недоступна группе ключа. |
| `404` | `not_found`                          | Модель неизвестна или недоступна этому ключу. Получите список через `GET /v1/models`.                                                                       |
| `429` | `rate_limit_exceeded`                | Достигнут лимит аккаунта или бесплатной модели. Подождите `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
  }
}
```

Для неизвестной модели возвращается `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. Во время вызова.** Сохраняется собственный формат ошибок SDK, поэтому OpenAI SDK и Anthropic SDK разбирают ответ и выбрасывают обычные для них исключения. Для отказов самого шлюза используется код BeatAPI (`insufficient_credits`, `content_policy_violation`, `bad_request`, `not_found` или `internal_error`): `error.type` равен `beatapi_error`, а код указан в `error.code`; для `/v1/messages` код находится в `error.type`. Ошибка на стороне модели получает код `temporary_error`, `upstream_timeout`, `model_unavailable` или `rate_limit_exceeded`. HTTP-статус сохраняется, кроме `502` и `504`, которые заменяются на `503`; проблема с нашим аккаунтом у поставщика возвращает `503 model_unavailable`. Английское сообщение модели о неверном параметре, например о слишком длинном контексте, передаётся текстом, чтобы вы могли исправить входные данные. На этом этапе ID запроса добавляется в конец каждого `message`. Поля `retryable` нет, а заголовок `Retry-After` при `429` не гарантируется: ориентируйтесь на статус и код. См. [Ошибки](/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"
  }
}
```

Повторяйте запросы только при `429`, `500` и `503`, увеличивая задержку между попытками.

## Все текстовые модели

Текущие текстовые модели из каталога шлюза. Выберите семейство, чтобы открыть страницу протокола. Указаны цены BeatAPI в USD за миллион токенов.

| ID модели                 | Семейство                                       | Контекст (токены) | Максимальный вывод (токены) | Ввод, USD за миллион токенов | Вывод, USD за миллион токенов | Протоколы                                                  |
| ------------------------- | ----------------------------------------------- | ----------------- | --------------------------- | ---------------------------- | ----------------------------- | ---------------------------------------------------------- |
| `gpt-6.1-terra`           | [GPT](/text-api/gpt/responses)                  | 1 050 000         | 128 000                     | \$0.40                       | \$2.00                        | Chat Completions, Responses                                |
| `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, Нативный API Gemini |
| `gemini-3.8-flash`        | [Gemini](/text-api/gemini/chat-completions)     | —                 | —                           | \$0.375                      | \$1.875                       | Chat Completions, Responses, Messages, Нативный API Gemini |
| `gemini-3.1-pro-preview`  | [Gemini](/text-api/gemini/chat-completions)     | 1 048 576         | 65 536                      | \$1.00                       | \$6.00                        | Chat Completions, Responses, Messages, Нативный API Gemini |
| `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.1-pro`           | [Kimi](/text-api/kimi/chat-completions)         | 1 048 576         | —                           | \$1.20                       | \$6.00                        | Chat Completions, Responses, Messages                      |
| `kimi-k3`                 | [Kimi](/text-api/kimi/chat-completions)         | 1 048 576         | 128 000                     | \$1.80                       | \$9.00                        | Chat Completions, Responses, Messages                      |
| `MiniMax-M3`              | [MiniMax](/text-api/minimax/chat-completions)   | 1 048 576         | 128 000                     | \$0.18                       | \$0.72                        | Chat Completions, Responses, Messages                      |
| `MiniMax-M3.1-Flash`      | [MiniMax](/text-api/minimax/chat-completions)   | 1 000 000         | —                           | \$0.09                       | \$0.36                        | 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                      |

* Указаны базовые цены со скидкой. Не включены тарифы для длинного контекста, кэшированного ввода и записи в кэш. См. [страницу цен](https://beatapi.io/pricing).
* `—` означает, что каталог не публикует это значение.
* \* В часы пик модели действует множитель. Показаны базовые тарифы вне часов пик.

## Бесплатные модели

Бесплатные модели не имеют платы за токены и используют отдельные минутные лимиты. См. [бесплатные модели](/free-models). В последнем столбце указана соответствующая платная модель.

| ID модели                  | Семейство | Платная версия        | Цена      |
| -------------------------- | --------- | --------------------- | --------- |
| `deepseek-v4.1-flash-free` | DeepSeek  | `deepseek-v4.1-flash` | Бесплатно |
| `glm-5.3-flash-free`       | GLM       | `glm-5.3-flash`       | Бесплатно |
| `gemini-3.8-flash-free`    | Gemini    | `gemini-3.8-flash`    | Бесплатно |

## Старые модели

Доступные старые ID и их замены перечислены в разделе [старые модели](/text-api/legacy-models).