Подключение и запросы

Куда вставить инструкцию настройки?

Строку set up https://beatapi.io/SKILL.md нужно отправить в чат ИИ-ассистента или агента в IDE, а не в Google. Поисковая система найдёт страницы, но не настроит агента. Руководство по настройке объясняет следующие шаги. Само чтение Skill не подключает агента и не авторизует его.

Какой base URL использовать?

Базовый адрес API — https://api.beatapi.io. Нужно ли добавлять к нему /v1, зависит от того, какой путь клиент подставляет автоматически.

Клиент	Base URL	Что клиент добавляет
OpenAI SDK и совместимые инструменты	`https://api.beatapi.io/v1`	`/chat/completions`
Anthropic SDK и клиенты с поддержкой API Claude	`https://api.beatapi.io`	`/v1/messages`
Gemini SDK и клиенты с поддержкой API Gemini	`https://api.beatapi.io`	`/v1beta/models/...`
Прямой HTTP	Полный путь, например `https://api.beatapi.io/v1/chat/completions`	Ничего

Неверный адрес вызывает 404 при каждом запросе. Многие клиенты показывают это как «не удалось подключиться».

Все запросы возвращают 404

Проверьте по порядку:

Двойной или отсутствующий /v1: /v1/v1/chat/completions не существует.
Лишний / в конце базового адреса: некоторые клиенты добавляют путь, не удаляя этот слеш.
Неподдерживаемый метод API. Публичный API включает текстовые запросы, задачи, файлы, статистику использования, вебхуки и видео в реальном времени. /v1/embeddings, /v1/rerank и /v1/audio/* не поддерживаются.
Неверный ID модели. Регистр важен; префикс поставщика не нужен: claude-fable-5-1, а не anthropic/claude-fable-5-1.

401 missing_api_key или invalid_api_key

missing_api_key означает, что BeatAPI не получил ключ. При invalid_api_key ключ получен, но он неверен, срок его действия истёк, он отключён или его лимит расходов исчерпан. Точная причина указана в сообщении об ошибке. Старые клиенты могут показывать прежний код unauthorized.

Заголовок: Authorization: Bearer <key>. Без префикса Bearer формат неверен.
Лишние пробелы вокруг ключа считаются его частью.
Проверьте активность ключа в Dashboard → API Keys. Отозванный ключ сразу перестаёт работать.
Некоторые клиенты используют x-api-key или x-goog-api-key. Это допустимо: они указывают на тот же аккаунт и баланс.

403 forbidden

Ключ распознан, но операция запрещена. Проверьте список разрешённых IP-адресов, группу моделей, доступную ключу, и состояние аккаунта. Если на аккаунте только регистрационный бонус, запрос к модели вне разрешённого списка возвращает 403 forbidden. Пополнение баланса открывает доступ к таким моделям.

Ответ 403 от BeatAPI означает отказ в доступе на стороне BeatAPI, а не отказ модели выполнить запрос. Если тело ответа содержит error code: 1010, запрос отклонён на сетевом уровне: явно задайте заголовок User-Agent. При отклонении модерацией возвращается 400 content_policy_violation на этапе создания задачи либо error_code: content_policy_violation у уже принятой задачи. См. справочник ошибок.

402 insufficient_credits / insufficient funds

Баланс равен нулю или меньше стоимости запроса. Все платные операции аккаунта возвращают 402 до пополнения. Это не ограничение одного ключа. Проверьте баланс и оплату; повторять запрос без пополнения бессмысленно.

429 rate_limit_exceeded

Превышен лимит запросов. Перед повторной попыткой подождите время, указанное в Retry-After или retry_after_seconds. Лимит платных запросов зависит от общей суммы пополнений за всё время. У бесплатных моделей отдельный лимит на аккаунт: 1 успешный запрос в минуту до первого пополнения, до 10 после пополнения на любую сумму.

Чтобы проверить статус уже принятой задачи, используйте GET /v1/tasks/{task_id}. Между проверками выдерживайте интервал poll_after_seconds. Не создавайте задачу заново вместо проверки её статуса. См. быстрый старт.

Запрос завершается по тайм-ауту

При stream: false текстовый ответ возвращается только после того, как модель закончит его формировать. Подготовка длинного ответа с рассуждениями может занять больше времени, чем стандартный тайм-аут клиента в 30–60 секунд.

Включите stream: true, чтобы получать ответ частями и поддерживать соединение.
Увеличьте время ожидания в настройках клиента, если получаете длинный ответ без потоковой передачи.

Задача не завершается

Проверьте status через GET /v1/tasks/{task_id}. У Music Video состояния storyboard_ready и requires_action могут требовать вашего просмотра или действия. Бесконечный опрос не заменяет это действие. succeeded и failed — конечные состояния; полный список есть в быстром старте.

На ноутбуке работает, на сервере — нет

Проверяйте доступ с машины, которая отправляет запрос. У Dify, AnythingLLM в Docker и CI могут быть свои правила исходящего трафика. Убедитесь, что контейнер или сервер может обращаться к api.beatapi.io, в том числе через корпоративный прокси. Перевод сайта не гарантирует сетевую доступность из любой сети.

Что приложить к обращению?

Укажите request_id из ответа с ошибкой, ID модели, HTTP-метод и путь запроса, а также приблизительное время его отправки. Создайте обращение в панели управления. Не прикладывайте секретный ключ или заголовок Authorization.