Быстрый старт с BeatAPI

Один API-ключ BeatAPI подходит для текстовых запросов, генерации изображений, видео и эффектов, рабочих процессов и видео в реальном времени. Храните ключ на сервере. Вы можете подключить ИИ-агента или обращаться к API напрямую. Платные запросы списывают средства с баланса в USD, поэтому перед запуском проверьте цену выбранной модели.

Подключить ИИ-ассистента

Вставьте строку целиком в чат ИИ-ассистента или агента в IDE, не в Google:

set up https://beatapi.io/SKILL.md

Агент прочитает общедоступную инструкцию и поможет настроить подключение, если его среда это поддерживает. Одного чтения инструкции недостаточно для авторизации: создайте ключ в панели управления и сохраните его в защищённом хранилище учётных данных клиента. Не отправляйте ключ в чат. Попросите агента проверить подключение и показать доступные модели и инструменты, не запуская платную задачу.

Если агент не может открыть ссылку, настроить MCP или отправить HTTPS-запрос, воспользуйтесь руководством по настройке и документацией клиента. Если в чате нет доступа к внешним инструментам, эта строка сама по себе не подключит его к BeatAPI.

Первая задача за три шага

1. Создайте API-ключ

Откройте Dashboard → API Keys. В терминале введите ключ так, чтобы он не попал в историю команд:

read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY

Базовый адрес API — https://api.beatapi.io. Для авторизации передавайте заголовок:

Authorization: Bearer <BEATAPI_API_KEY>

Если настраиваете OpenAI SDK, укажите https://api.beatapi.io/v1; для Anthropic SDK — https://api.beatapi.io. Как правильно указать /v1, объясняется в FAQ по подключению.

2. Создайте задачу

Пример генерации изображения через POST /v1/images/tasks. Его выполнение оплачивается по тарифу модели:

curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "Editorial product photograph on a warm stone pedestal."
  }'

Корректный запрос возвращает 201 Created. Сохраните data.id.

3. Получите результат

curl https://api.beatapi.io/v1/tasks/task_8K2qA \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

Замените task_8K2qA на data.id из шага 2. Между проверками ждите data.poll_after_seconds: 5 секунд для изображений, 8 для видео и эффектов, 10 для данных и рабочих процессов. Поле присутствует, пока задача выполняется.

Когда статус станет succeeded, получите файлы из data.output.media и прекратите опрос. При failed проверьте data.error_code, data.error_message и data.retryable, затем также прекратите опрос. Если уже принятая задача завершилась ошибкой, запрос её статуса всё равно возвращает HTTP 200; ошибка указана в теле ответа.

Выберите API

Ответ на текстовый запрос возвращается синхронно или потоком SSE. Realtime создаёт краткоживущую сессию. При запуске рабочего процесса, генерации видео, изображения или эффекта создаётся асинхронная задача: сохраните data.id и проверяйте её статус через общий метод GET /v1/tasks/{task_id}. Для этого метода нет ограничения частоты запросов, но между проверками следует выдерживать интервал poll_after_seconds.

Форматы GPT, выбор модели и потоковые примеры: справочник GPT.

Проверка статуса задачи

GET /v1/tasks/{task_id} принимает обязательный строковый task_id в пути. Используйте data.id из ответа создания.

Задачи генерации изображений и видео используют только queued, processing, succeeded и failed. Остальные состояния относятся к Music Video.

Общие поля задачи

Расходы и выходные файлы

Поля credits_* сохранены для совместимости. Все значения баланса и расходов — десятичные суммы USD: **1 Credit = $1 USD**. Панель управления показывает те же суммы со знаком `$`.

Если задача завершилась ошибкой, credits_reserved показывает зарезервированную сумму, credits_charged и credits_settled равны 0, а credits_refunded содержит сумму возврата. При content_policy_violation и bad_request повторять ту же задачу без изменений не следует. При processing_unavailable, processing_timeout, processing_failed и result_transfer_failed повторная отправка может помочь. См. ошибки.

Загрузка входного файла

Используйте POST /v1/files, если файл находится на вашем устройстве и ещё не доступен по общедоступной HTTPS-ссылке. Запрос должен содержать точный Content-Length; curl, браузеры и SDK обычно задают его автоматически. Загрузка с передачей по частям (chunked) без указанной длины отклоняется до чтения тела запроса в буфер.

В multipart-запросе поле file обязательно. Необязательное поле purpose игнорируется: в ответе оно всегда равно input.

curl https://api.beatapi.io/v1/files \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -F "file=@./song.mp3" \
  -F "purpose=input"

Можно также передать содержимое файла непосредственно в теле запроса, указав его MIME-тип в заголовке Content-Type.

Допустимые альтернативные MIME-типы приводятся к стандартным: image/jpg — к image/jpeg, audio/mp3 — к audio/mpeg, а text/plain для файла .srt — к application/x-subrip. PDF, произвольные текстовые файлы, octet-stream, неподдерживаемые видеоконтейнеры и ZIP отклоняются с 400 bad_request. Если у файла есть расширение, оно должно соответствовать объявленному Content-Type. При загрузке проверяется объявленный тип, но не содержимое файла, его длительность или размеры изображения. Поэтому модель или рабочий процесс могут отклонить уже загруженный файл при создании задачи, например из-за длительности или размера. Ссылки на входные файлы рабочих процессов не могут указывать на localhost или адреса частной сети; data URL также не поддерживаются.

При отказе в загрузке возвращается 400 bad_request. Текст сообщения остаётся на английском, чтобы его можно было сопоставить с ответом API:

Если файл не удалось сохранить, возвращается 503 processing_unavailable или 503 result_transfer_failed. Ничего не сохранено; повторите запрос позже, увеличивая задержку между попытками.

Пример ответа при загрузке

{
  "data": {
    "id": "file_6f1c2b9e-4d0a-4c58-9a57-2f0a8f3d7b11",
    "object": "file",
    "url": "https://files.beatapi.io/u/6f1c2b9e4d0a4c589a572f0a8f3d7b11.mp3",
    "key": "u/6f1c2b9e4d0a4c589a572f0a8f3d7b11.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 1048576,
    "purpose": "input",
    "created_at": 1782210000
  }
}

Ответ содержит data.id вида file_<uuid>, object: "file", HTTPS-ссылку url, ключ хранения key, стандартный mime_type, размер в байтах size_bytes, purpose: "input" и временную метку Unix created_at. Передайте data.url в запрос к модели или рабочему процессу. Ограничения конкретного процесса проверяются при создании задачи: например, Standard Music Video принимает аудио длительностью 10–180 секунд, а Premium — 10–300 секунд.

Проверка баланса и использования

Для GET /v1/usage требуется API-ключ. У метода нет параметров:

curl https://api.beatapi.io/v1/usage \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

Для задачи Music Video в состоянии storyboard_ready или requires_action уже могут быть списаны средства, хотя она не учитывается в числе одновременно выполняемых задач.

Ошибки и повторные попытки

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: at most 60 successful requests per 1 minute(s). Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}

Ответ с ошибкой содержит code, описание причины на английском в поле message и идентификатор request_id. При обработке ошибки ориентируйтесь на code, а не на текст сообщения: клиент может показать его перевод.

Коды ошибок

BeatAPI возвращает стабильные публичные коды, не раскрывая поставщика модели и не передавая его исходный ответ об ошибке. Код указан в error.code; если асинхронная задача уже была принята, код её итоговой ошибки также может находиться в error_code. Различия между ошибками при создании задачи, её выполнении и текстовом вызове описаны в справочнике ошибок.

retryable: false означает, что тот же запрос не сработает без изменений. Только 429 rate_limit_exceeded содержит известную задержку retry_after_seconds и заголовок Retry-After. У 503 нет известного времени ожидания. 502 и 504 без JSON приходят от сетевого шлюза, а не BeatAPI; повторяйте их как 503.

Поле retryable присутствует для всех кодов в таблице HTTP-ответов выше: оно равно false для 400, 401, 402, 403, 404, 409 и 501, и true для 429, 500 и 503.

Если клиент пишет «insufficient funds», начните с FAQ по балансу. Если «не работает» или «не удалось подключиться» — с FAQ по подключению.

Идемпотентность

• Создание задач Workflow, Image, Video, Effect и POST /v1/capabilities/run принимают необязательный ключ идемпотентности. Для создания Realtime Session он обязателен.
• Ключ хранится 24 часа. Максимум 255 символов; превышение даёт 400 bad_request.
• Тот же ключ с другим телом или путём возвращает 409 idempotency_conflict. Такой же ответ возможен, пока первый запрос ещё выполняется.
• Повтор идентичного запроса возвращает сохранённый ответ с Idempotent-Replayed: true.
• Сохраняются только ответы 2xx, поэтому после 400 или 402 можно повторить запрос с тем же ключом.

Перед запуском в рабочей среде

• Отправляйте запросы на https://api.beatapi.io и храните постоянные ключи на сервере.
• Проверяйте обязательные поля, форматы, перечисления, ограничения и условия выбранного API.
• Сохраняйте ID задачи или сессии и request_id до запуска фоновой обработки.
• Выдерживайте интервал poll_after_seconds. Прекращайте опрос, если задача завершилась или ожидает вашего действия.
• Скачивайте результаты, которые нужно хранить постоянно.
• Соблюдайте HTTP-коды, Retry-After и retry_after_seconds.
• Проверяйте подпись вебхука по исходным байтам до разбора JSON. События — только task.succeeded и task.failed, всего 3 попытки: повторы через 1 и 5 минут. Задача, завершённая по тайм-ауту фоновым обработчиком, не отправляет событие: статус задачи остаётся источником истины.
• Учитывайте резервы, итоговые списания и возвраты, а также ошибки и URL результата.
• Перед обработкой камер, лиц, голосов и референсов прочитайте политику конфиденциальности (EN) и условия использования (EN).