Персональный токен доступа

Персональный токен доступа — это учётные данные для автоматизации работы с аккаунтом BeatAPI. Он действует с правами вашего аккаунта, поэтому скрипт может получать данные аккаунта, например стоимость каждой задачи или текстового запроса. Запросы к моделям, задачам и рабочим процессам по-прежнему выполняются с API-ключом.

Персональный токен доступа или API-ключ

Создание, замена и отзыв

1. Войдите в панель управления и откройте раздел Безопасность аккаунта.
2. Нажмите Создать персональный токен и пройдите проверку.
3. Скопируйте токен. Полный токен показывается только один раз; после закрытия окна он удаляется со страницы.
4. Сохраните его как секрет там, где работает ваша автоматизация, например в BEATAPI_PERSONAL_TOKEN.

Замена персонального токена выпускает новый токен, а предыдущий сразу перестаёт работать. Отзыв персонального токена удаляет его, и инструменты, которые его используют, сразу теряют доступ. Оба действия требуют проверки. Храните токен только на доверенных серверах: не добавляйте его в код браузера, мобильное приложение или общий репозиторий.

Доступные эндпоинты

Передавайте токен в заголовке Authorization: Bearer <token>. Этим эндпоинтам нужно разрешение usage:read, которое входит в персональный токен. Два эндпоинта записей отклоняют API-ключ с 403 forbidden; GET /v1/usage принимает и API-ключ, и этот токен и возвращает одну и ту же сводку. Со временем этот токен будут принимать и другие эндпоинты аккаунта.

Сверка одной задачи

Сохраните data.id из ответа на создание задачи и запросите запись:

curl https://api.beatapi.io/v1/account/usage/records/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ \
  -H "Authorization: Bearer $BEATAPI_PERSONAL_TOKEN"

{
  "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-<request ID>, это значение тоже подходит. ID запроса, создавшего задачу, возвращает ту же запись, что и ID задачи.

Список записей об использовании

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"

{
  "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"
  }
}

Пока has_more равно true, запрашивайте следующую страницу с cursor. Неизвестный параметр, limit вне диапазона 1–100 или метка времени в миллисекундах не игнорируются, а отклоняются с 400 bad_request.

Запись об использовании

Суммы задачи совпадают с usage.credits_charged и usage.credits_refunded из GET /v1/tasks/{task_id}. Если итоговая сумма задачи больше или меньше зарезервированной, запись показывает итог после расчёта. Читать можно только записи своего аккаунта: ID другого аккаунта возвращает 404 not_found.

Ошибки

Ошибки возвращаются в стандартном объекте ошибки.