Текстовый API

• Текстовые модели 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 моделей, размеры контекста, лимиты вывода и цены можно получить без ключа.

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

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

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

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

• 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 --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." }]
}'

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

GET /v1/text/models

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

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

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

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 не ограничена.
• У бесплатных моделей отдельный лимит; см. Бесплатные модели.
• При превышении возвращается 429 rate_limit_exceeded с retry_after_seconds и заголовком Retry-After. Подождите указанное время и повторите запрос.

Ошибки

Текстовый запрос может завершиться ошибкой на двух этапах, причём формат ответа зависит от этапа. Полная таблица кодов и правила повторных попыток приведены в разделе Ошибки; ниже — краткое описание.

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.

{
  "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 не гарантируется: ориентируйтесь на статус и код. См. Ошибки.

{
  "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 и их замены перечислены в разделе старые модели.