> 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. # Как подключить BeatAPI — ошибки подключения и API > Правильный base URL BeatAPI, настройка API-ключа и устранение ошибок 401, 402 insufficient_credits, 403, 404, 429 и тайм-аутов. # Подключение и запросы ## Куда вставить инструкцию настройки? Строку `set up https://beatapi.io/SKILL.md` нужно отправить в чат ИИ-ассистента или агента в IDE, а не в Google. Поисковая система найдёт страницы, но не настроит агента. [Руководство по настройке](https://beatapi.io/ru/skill) объясняет следующие шаги. Само чтение 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 Проверьте по порядку: 1. Двойной или отсутствующий `/v1`: `/v1/v1/chat/completions` не существует. 2. Лишний `/` в конце базового адреса: некоторые клиенты добавляют путь, не удаляя этот слеш. 3. Неподдерживаемый метод API. Публичный API включает текстовые запросы, задачи, файлы, статистику использования, вебхуки и видео в реальном времени. `/v1/embeddings`, `/v1/rerank` и `/v1/audio/*` не поддерживаются. 4. Неверный 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 `. Без префикса `Bearer ` формат неверен. * Лишние пробелы вокруг ключа считаются его частью. * Проверьте активность ключа в [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys). Отозванный ключ сразу перестаёт работать. * Некоторые клиенты используют `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` у уже принятой задачи. См. [справочник ошибок](/errors). ## 402 insufficient_credits / insufficient funds Баланс равен нулю или меньше стоимости запроса. Все платные операции аккаунта возвращают `402` до пополнения. Это не ограничение одного ключа. Проверьте [баланс и оплату](/ru/faq/account-billing); повторять запрос без пополнения бессмысленно. ## 429 rate_limit_exceeded Превышен лимит запросов. Перед повторной попыткой подождите время, указанное в `Retry-After` или `retry_after_seconds`. Лимит платных запросов зависит от общей суммы пополнений за всё время. У бесплатных моделей отдельный лимит на аккаунт: 1 успешный запрос в минуту до первого пополнения, до 10 после пополнения на любую сумму. Чтобы проверить статус уже принятой задачи, используйте `GET /v1/tasks/{task_id}`. Между проверками выдерживайте интервал `poll_after_seconds`. Не создавайте задачу заново вместо проверки её статуса. См. [быстрый старт](/ru/quick-guide). ## Запрос завершается по тайм-ауту При `stream: false` текстовый ответ возвращается только после того, как модель закончит его формировать. Подготовка длинного ответа с рассуждениями может занять больше времени, чем стандартный тайм-аут клиента в 30–60 секунд. * Включите `stream: true`, чтобы получать ответ частями и поддерживать соединение. * Увеличьте время ожидания в настройках клиента, если получаете длинный ответ без потоковой передачи. ## Задача не завершается Проверьте `status` через `GET /v1/tasks/{task_id}`. У Music Video состояния `storyboard_ready` и `requires_action` могут требовать вашего просмотра или действия. Бесконечный опрос не заменяет это действие. `succeeded` и `failed` — конечные состояния; полный список есть в [быстром старте](/ru/quick-guide#get-task-status). ## На ноутбуке работает, на сервере — нет Проверяйте доступ с машины, которая отправляет запрос. У Dify, AnythingLLM в Docker и CI могут быть свои правила исходящего трафика. Убедитесь, что контейнер или сервер может обращаться к `api.beatapi.io`, в том числе через корпоративный прокси. Перевод сайта не гарантирует сетевую доступность из любой сети. ## Что приложить к обращению? Укажите `request_id` из ответа с ошибкой, ID модели, HTTP-метод и путь запроса, а также приблизительное время его отправки. Создайте обращение в [панели управления](https://beatapi.io/dashboard). Не прикладывайте секретный ключ или заголовок Authorization.