> 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-ключами, чтения баланса и платежей и сверки расходов по каждому запросу в USD. # Персональный токен доступа Персональный токен доступа — это учётные данные для автоматизации работы с аккаунтом BeatAPI. Вы сами выбираете разрешения каждого токена, поэтому скрипт делает только то, что вы разрешили: читает баланс, управляет API-ключами, получает список платежей или данные аккаунта, например стоимость каждой задачи или текстового запроса. Запросы к моделям, задачам и рабочим процессам по-прежнему выполняются с API-ключом. ## Персональный токен доступа или API-ключ | | Персональный токен доступа | API-ключ | | --------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | | Начинается с | `nap_` | `sk-` | | Назначение | Автоматизация аккаунта, например `GET /v1/account` и `GET /v1/account/usage/records` | Запросы к моделям, задачам и рабочим процессам | | Количество | До 20 на аккаунт, у каждого своё имя | Сколько нужно | | Ограничения | Выбранные вами разрешения; отдельных ограничений по моделям, IP и расходам нет | Для каждого ключа можно задать ограничения по моделям, IP и расходам | | Срок действия | По выбору: 7, 30, 90 или 365 дней либо бессрочно | Для каждого ключа можно задать срок действия | | Где принимается | Эндпоинты `/v1/account` и `GET /v1/usage` | Эндпоинты моделей, задач и рабочих процессов и `GET /v1/usage` | ## Создание токенов и управление ими 1. Войдите в [панель управления](https://beatapi.io/dashboard/security) и откройте раздел **Безопасность аккаунта**. 2. Нажмите **Создать персональный токен**, введите имя, отметьте нужные токену разрешения и выберите срок действия: 7, 30 (по умолчанию), 90 или 365 дней либо бессрочно. 3. Пройдите проверку и скопируйте токен. Полный токен показывается только один раз; после закрытия окна он удаляется со страницы. 4. Сохраните его как секрет там, где работает ваша автоматизация, например в `BEATAPI_PERSONAL_TOKEN`. На одном аккаунте может быть до 20 токенов. Давайте каждому имя, по которому понятно, где он используется, и выдавайте только нужные разрешения. В списке токенов видны имя, разрешения, срок действия и время последнего использования каждого токена. Переименовать токен можно в любое время без проверки. Изменение разрешений и отзыв токена требуют проверки. Изменённые разрешения применяются к тому же токену, поэтому ничего не нужно разворачивать заново. **Отзыв** удаляет токен, и инструменты, которые его используют, сразу теряют доступ. Храните токены только на доверенных серверах: не добавляйте их в код браузера, мобильное приложение или общий репозиторий. Токен, созданный до появления нескольких токенов, продолжает работать с теми разрешениями, которые у него уже были. ## Разрешения У токена есть только те разрешения, которые вы отметили. Вызов, которому нужно отсутствующее у токена разрешение, отклоняется с `403 forbidden`, а в сообщении указано недостающее разрешение. | Разрешение | Что разрешает | Эндпоинты | | ---------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `usage:read` | Чтение записей об использовании и сводки | `GET /v1/account/usage/records`, `GET /v1/account/usage/records/{id}`, `GET /v1/usage` | | `api_key:read` | Список и чтение API-ключей; ключи маскируются | `GET /v1/account/keys`, `GET /v1/account/keys/{id}` | | `api_key:write` | Создание API-ключей (полный ключ возвращается один раз), их изменение, отключение и удаление | `POST /v1/account/keys`, `PATCH /v1/account/keys/{id}`, `DELETE /v1/account/keys/{id}` | | `api_key:reveal` | Чтение полного значения существующего API-ключа | `POST /v1/account/keys/{id}/reveal` | | `wallet:read` | Чтение истории платежей (пополнений) | `GET /v1/account/payments` | | `profile:read` | Чтение профиля, баланса и настроек уведомлений | `GET /v1/account`, `GET /v1/account/notifications` | | `profile:write` | Изменение настроек уведомлений | `PATCH /v1/account/notifications` | Токен не может пополнять баланс, менять настройки входа и безопасности или управлять другими токенами: это делается только в панели управления. Выдавайте `api_key:reveal` лишь тем токенам, которым действительно нужно читать значения ключей. ## Доступные эндпоинты Передавайте токен в заголовке `Authorization: Bearer `. Каждому эндпоинту нужно указанное разрешение. | Эндпоинт | Разрешение | Назначение | | ------------------------------------ | ---------------- | --------------------------------------------------------------- | | `GET /v1/account` | `profile:read` | Профиль аккаунта и баланс в USD | | `GET /v1/account/notifications` | `profile:read` | Чтение настроек уведомлений о балансе | | `PATCH /v1/account/notifications` | `profile:write` | Изменение типа уведомлений, порога или адреса почты | | `GET /v1/account/payments` | `wallet:read` | Список платежей, начиная с новых | | `GET /v1/account/keys` | `api_key:read` | Список API-ключей, начиная с новых | | `GET /v1/account/keys/{id}` | `api_key:read` | Чтение одного API-ключа | | `POST /v1/account/keys` | `api_key:write` | Создание API-ключа | | `PATCH /v1/account/keys/{id}` | `api_key:write` | Изменение, отключение или повторное включение API-ключа | | `DELETE /v1/account/keys/{id}` | `api_key:write` | Удаление API-ключа | | `POST /v1/account/keys/{id}/reveal` | `api_key:reveal` | Чтение полного значения API-ключа | | `GET /v1/account/usage/records` | `usage:read` | Список оплаченных запросов, начиная с новых | | `GET /v1/account/usage/records/{id}` | `usage:read` | Одна запись по ID задачи или ID запроса | | `GET /v1/usage` | `usage:read` | Итоги и разбивки по аккаунту; см. [Быстрый старт](/quick-guide) | Эндпоинты `/v1/account` отклоняют API-ключ с `403 forbidden`; `GET /v1/usage` принимает и API-ключ, и токен с `usage:read` и возвращает одну и ту же сводку. Ответы обёрнуты в `data`. ID — строки, время — Unix-секунды, суммы — в USD. Списки возвращают `object`, `data`, `has_more` и `next_cursor` и принимают `limit` (1–100, по умолчанию 20) и `cursor`. Неизвестный параметр запроса отклоняется с `400 bad_request`. ## Чтение баланса Нужно разрешение `profile:read`. ```bash curl https://api.beatapi.io/v1/account \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "account", "id": "1042", "username": "ada", "display_name": "Ada", "email": "ada@example.com", "credit_balance": 42.5, "currency": "USD" } } ``` ## Список API-ключей Нужно разрешение `api_key:read`. Ключи маскируются: возвращается только `key_prefix` — первые символы. Один ключ читается через `GET /v1/account/keys/{id}`. ```bash curl -G https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "api_key", "id": "1287", "title": "production", "key_prefix": "sk-Ab3d", "status": "active", "created_at": 1793200000, "last_used_at": 1793247312, "expires_at": null, "remaining_credits": null, "credits_used": 18.42, "models": [], "allowed_ips": [] } ], "has_more": false } } ``` ## Создание API-ключа Нужно разрешение `api_key:write`. Обязателен только `title`. Поля `expires_at` (Unix-секунды), `remaining_credits` (USD), `models` и `allowed_ips` необязательны; если их не указывать, у ключа нет срока действия и лимита расходов, доступны все модели и любые IP-адреса. Полный ключ есть в поле `key` только в этом ответе: при последующих чтениях возвращается лишь `key_prefix`, поэтому сохраните ключ сразу. ```bash curl -X POST https://api.beatapi.io/v1/account/keys \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "ci-runner", "remaining_credits": 20, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"]}' ``` ```json { "data": { "object": "api_key", "id": "1304", "title": "ci-runner", "key_prefix": "sk-Qm8R", "key": "sk-Qm8RExampleFullKeyShownOnlyInThisResponse", "status": "active", "created_at": 1793250000, "last_used_at": null, "expires_at": null, "remaining_credits": 20, "credits_used": 0, "models": ["deepseek-v4.1-flash"], "allowed_ips": ["203.0.113.7"] } } ``` Ключ изменяется через `PATCH /v1/account/keys/{id}`: передайте любые из полей `title`, `status` (`active` или `disabled`), `expires_at` (`null` — бессрочно), `remaining_credits` (`null` — без лимита), `models` (`[]` — все модели) и `allowed_ips`. `DELETE /v1/account/keys/{id}` возвращает `object`, `id` и `deleted: true`. ## Чтение полного значения API-ключа Нужно разрешение `api_key:reveal`, отдельное от `api_key:read`: токен, который видит список ключей, не прочитает их значения, пока вы не выдадите и это разрешение. ```bash curl -X POST https://api.beatapi.io/v1/account/keys/1287/reveal \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "api_key_secret", "id": "1287", "key": "sk-Ab3dExampleFullKey" } } ``` ## Список платежей Нужно разрешение `wallet:read`. `status` принимает `paid` (по умолчанию), `pending`, `failed`, `expired`, `reviewing` или `all`. `currency` — валюта оплаты, `USD` или `CNY`; `credits` — сумма, которую платёж добавляет к балансу, в USD. ```bash curl -G https://api.beatapi.io/v1/account/payments \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "status=paid" \ --data-urlencode "limit=20" ``` ```json { "data": { "object": "list", "data": [ { "object": "payment", "id": "5531", "order_no": "ORD20261027153012", "status": "paid", "amount_paid": 20, "currency": "USD", "credits": 20, "payment_method": "stripe", "created_at": 1793100000, "paid_at": 1793100042 } ], "has_more": false } } ``` ## Изменение порога уведомлений Нужно разрешение `profile:write`; чтение настроек через `GET /v1/account/notifications` требует `profile:read`. Передайте любые из полей `type` (`email` или `none`), `threshold_credits` и `notification_email`. BeatAPI уведомляет вас, когда расходы опускают баланс ниже порога; значение `0` выбирает порог по умолчанию. В ответе — обновлённые настройки, где `effective_threshold_credits` — действующий порог. ```bash curl -X PATCH https://api.beatapi.io/v1/account/notifications \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"threshold_credits": 5}' ``` ```json { "data": { "object": "notification_settings", "type": "email", "threshold_credits": 5, "effective_threshold_credits": 5, "default_threshold_credits": 1, "notification_email": "billing@example.com", "account_email": "ada@example.com" } } ``` ## Сверка одной задачи Сохраните `data.id` из ответа на создание задачи и запросите запись: ```bash curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" ``` ```json { "data": { "object": "usage_record", "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ", "type": "image", "model": "seedream-5-pro", "task_id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ", "request_id": "202610290330051234567893f9a1c2eXy7Kp2Qd", "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" }, "status": "succeeded", "created_at": 1793244605, "currency": "USD", "credits_charged": 0.06, "credits_refunded": 0, "usage": { "images": 2 } } } ``` Для текстового запроса используйте ID запроса из заголовка ответа `X-BeatAPI-Request-Id`. Если в теле текстового ответа `id` имеет вид `chatcmpl-`, это значение тоже подходит. ID запроса, создавшего задачу, возвращает ту же запись, что и ID задачи. ## Список записей об использовании ```bash curl -G https://api.beatapi.io/v1/account/usage/records \ -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN" \ --data-urlencode "start=2026-10-01T00:00:00Z" \ --data-urlencode "end=2026-11-01T00:00:00Z" \ --data-urlencode "limit=100" ``` ```json { "data": { "object": "list", "data": [ { "object": "usage_record", "id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw", "type": "text", "model": "deepseek-v4.1-flash", "request_id": "20261029041512987654321b3f9a1c2eQm8Rt4Lw", "api_key": { "id": "1287", "title": "production", "key_prefix": "sk-Ab3d" }, "status": "succeeded", "created_at": 1793247312, "currency": "USD", "credits_charged": 0.002468, "credits_refunded": 0, "usage": { "input_tokens": 1200, "output_tokens": 350, "cached_tokens": 1024 } } ], "has_more": true, "next_cursor": "eyJ0IjoxNzkzMjQ3MzEyLCJpIjo5ODc2NTQzMn0" } } ``` | Параметр | Значение | | ------------ | --------------------------------------------------------------------------------------------------------- | | `start` | Самое раннее включаемое значение `created_at`. Unix-секунды или RFC 3339, например `2026-10-01T00:00:00Z` | | `end` | Верхняя граница, не включается; те же форматы | | `model` | Публичный ID модели, например `seedream-5-pro` | | `type` | Одно из значений: `text`, `image`, `video`, `workflow`, `data`, `realtime` или `other` | | `api_key_id` | Числовой ID API-ключа, как в `api_key.id` | | `limit` | Записей на странице, от 1 до 100; по умолчанию 20 | | `cursor` | Значение `next_cursor` предыдущей страницы | Пока `has_more` равно `true`, запрашивайте следующую страницу с `cursor`. Неизвестный параметр, `limit` вне диапазона 1–100 или метка времени в миллисекундах не игнорируются, а отклоняются с `400 bad_request`. ## Запись об использовании | Поле | Значение | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `usage_record` | | `id` | ID задачи для задачи, иначе ID запроса | | `type` | `text`, `image`, `video`, `workflow`, `data`, `realtime` или `other` | | `model` | Публичный ID модели | | `task_id` | Есть у задач | | `request_id` | ID запроса, создавшего запись, если он известен | | `api_key` | `id`, `title` и `key_prefix` API-ключа, с которого оплачен запрос; `null` для использования в песочнице панели управления | | `status` | `queued`, `processing`, `succeeded`, `failed` или `refunded`, если вся сумма возвращена | | `created_at` | Unix-секунды | | `currency` | `USD` | | `credits_charged` | Сумма, которую вы заплатили, в USD с учётом скидок и итогового расчёта; до шести знаков после запятой | | `credits_refunded` | Сумма в USD, возвращённая на баланс | | `usage` | Оплачиваемые объёмы: `input_tokens`, `output_tokens`, `cached_tokens` и `cache_write_tokens` для текста; `images`, `seconds` и `resolution` для медиа | Суммы задачи совпадают с `usage.credits_charged` и `usage.credits_refunded` из `GET /v1/tasks/{task_id}`. Если итоговая сумма задачи больше или меньше зарезервированной, запись показывает итог после расчёта. Читать можно только записи своего аккаунта: ID другого аккаунта возвращает `404 not_found`. ## Ошибки | Статус | `code` | Когда | | ------ | -------------- | ------------------------------------------------------------------------------------------------------------- | | `400` | `bad_request` | Недопустимый параметр запроса или поле тела, либо в запросе неизвестный параметр | | `401` | `unauthorized` | Токен отсутствует, неизвестен, отозван или истёк | | `403` | `forbidden` | У токена нет разрешения, нужного эндпоинту (в сообщении оно названо), или API-ключ передан эндпоинту аккаунта | | `404` | `not_found` | В вашем аккаунте нет записи, платежа или API-ключа с таким ID | Ошибки возвращаются в стандартном [объекте ошибки](/errors).