История изменений

2026-11-12

В этом обновлении документация публичного API реорганизована: страницы сгруппированы по разделам «аккаунт», «API-ключи», «использование», «задачи», «оплата» и «тарифы», а также добавлены страницы о жизненном цикле ключей (создание, обновление, отзыв, ротация), балансе ключей и тарифах моделей.

Пять страниц прежней группы «Аккаунт» удалены, их URL перенаправляют на соответствующие новые страницы. Изменилась только структура документации, работа API не менялась.

Старые пути, оставленные для совместимости

Следующие 10 устаревших GET-путей по-прежнему работают и полностью повторяют поведение новых путей справа. Они сохранены только для совместимости, будут удалены в следующих версиях, поэтому мигрируйте как можно скорее. Для новых интеграций используйте новые пути.

Обратите внимание: /api/v1/account и /api/v1/account/balance сами являются новыми путями и в список не входят.

Старый путь	Новый путь
`/api/v1/account/api-keys`	`/api/v1/api-keys`
`/api/v1/account/api-keys/{api_key_id}`	`/api/v1/api-keys/{api_key_id}`
`/api/v1/account/usage/records`	`/api/v1/usage/records`
`/api/v1/account/usage/summary`	`/api/v1/usage/summary`
`/api/v1/account/tasks`	`/api/v1/tasks`
`/api/v1/account/tasks/{task_id}`	`/api/v1/tasks/{task_id}`
`/api/v1/account/billing/topups`	`/api/v1/billing/topups`
`/api/v1/account/billing/topups/{trade_no}`	`/api/v1/billing/topups/{trade_no}`
`/api/v1/account/billing/payment-method`	`/api/v1/billing/payment-method`
`/api/v1/account/billing/auto-topup`	`/api/v1/billing/auto-topup`

Для создания, обновления, отзыва и ротации ключей, баланса ключей, Webhook, тарифов и счетов Stripe устаревших путей с префиксом /account не существует — есть только новые плоские пути.

Переход со старых API аккаунта

В таблице ниже показано соответствие старых и новых эндпоинтов по функциям — это не взаимозаменяемые совместимые пути. Учётные данные, параметры и структура ответов различаются, поэтому код вызовов нужно обновить.

Старые эндпоинты баланса и создания использовали модельный ключ, новые используют системный токен доступа. Старый эндпоинт использования также требовал заголовок X-User-Id, новый он не нужен.

Старый API	Новый API	Условия перехода
`GET /v1/balance, /balance`	`GET /api/v1/api-keys/{api_key_id}/balance`	Используйте системный токен и ID, а не секрет запрашиваемого ключа. Безлимитный остаток равен `null` вместо `-1`.
`GET /api/usage/tokens/requests`	`GET /api/v1/usage/records`	Измените параметры и поля по таблице ниже. Количество token чтения и записи кеша возвращается внутри `usage`.
`GET /api/usage/tokens/summary`	`GET /api/v1/usage/summary?group_by=api_key`	Явно укажите `group_by=api_key`. `record_count` считает строки логов, а не полные запросы или окончательные чистые расходы.
`GET /v1/user/balance, /user/balance`	`GET /api/v1/account/balance`	Читает свой баланс или бюджет субаккаунта. Десятичные строки явно разделяют USD и credits.
`GET /v1/pricing`	`GET /api/v1/pricing?api_key_id={api_key_id}`	Для контекста ключа передайте `api_key_id`. `after`/`next_after` заменены `cursor`/`next_cursor`, ответ использует `code`/`message`/`data`. Протокол отличается.
`POST /v1/tokens`	`POST /api/v1/api-keys`	Следуйте новым полям и типам создания. `group`, `cross_group_retry` и Webhook не принимаются, поэтому все прежние возможности не заменены.

Старый allow_ips в виде строки с переносами строк заменён массивом строк, например ["192.0.2.10","2001:db8::1"]. Поддерживается при создании и обновлении: [] снимает ограничение, null или недопустимый адрес возвращает 400.

Поддерживаются только одиночные IP-адреса, диапазоны CIDR не поддерживаются.

Поля использования и пагинация

Параметры времени заменены с Unix-секунд start_timestamp/end_timestamp на from/to с часовым поясом, при постраничном чтении диапазон сохраняется. token_id заменён строкой api_key_id, page_size — параметром limit. Старые курсоры непригодны.

По кэш-полям: старый cache_tokens соответствует usage.cache_read_tokens, cache_creation_tokens — usage.cache_write_tokens. Новый API дополнительно возвращает разбивку записи за 5 минут и 1 час, уже включённую в cache_write_tokens — повторно суммировать нельзя.

Отсутствующее или недопустимое значение возвращается как null, явно записанный ноль — как 0.

Ошибки параметров теперь возвращают HTTP 400 (вместо 422) с числовым code. Старое поле quota было во внутренних единицах, а новое recorded_credits уже в кредитах — при миграции нужно учесть смысл суммы, а не только переименовать поле.

Старое поле	Новое поле	Описание
`log_id`	`id`	Только переименовано.
`token_id`	`api_key_id`	Числовой ID передаётся строкой.
`token_name`	`key_name`	Только переименовано.
`model_name`	`model`	Только переименовано.
`start_timestamp`/`end_timestamp`	`from`/`to`	Unix-секунды → RFC 3339 с часовым поясом; диапазон сохраняется между страницами.
`page_size`	`limit`	Записей на страницу.
`cost_usd`	`recorded_cost_usd`	Учтённая стоимость записи в USD, десятичная строка.
`quota`	`recorded_credits`	Внутренние единицы квоты → пересчитанные credits; старые значения не переносятся.
`prompt_tokens`	`usage.input_tokens`	Перенесено в объект `usage`.
`completion_tokens`	`usage.output_tokens`	Перенесено в объект `usage`.
`reported_total_tokens`	`usage.reported_total_tokens`	Суммарные токены от апстрима; перенесено в `usage`.
`cache_tokens`	`usage.cache_read_tokens`	Прочитанные из кэша токены; перенесено в `usage`.
`cache_creation_tokens`	`usage.cache_write_tokens`	Суммарная запись в кэш; уже включает разбивку на 5 минут и 1 час — не суммируйте повторно.
`request_count`	`record_count`	Число записей журнала, а не полных запросов.
`data[]`	`data.items[]`	Массив записей перенесён в `data.items`.
`meta.has_more`	`data.has_more`	Информация о пагинации перенесена в `data`.
`meta.next_cursor`	`data.next_cursor`	Курсор пагинации; старые курсоры в новом API не работают.

Изменения полей создания ключа

Старое поле	Новое поле	Описание
`expired_time`	`expires_at`	Unix-секунды (-1 = бессрочно) заменены на RFC 3339 с часовым поясом; `null` или отсутствие = бессрочно.
`remain_quota`/`remain_credits`	`remaining_credits`	Десятичная строка без потери точности.
`daily_credits`/`monthly_credits`	`daily_limit_credits`/`monthly_limit_credits`	`null` или `"0"` — без лимита.
`unlimited_quota`	`unlimited`	Булево, `null` не принимается; при `true` `remaining_credits` можно только опустить или передать `null`.
`model_limits_enabled`	—	Удалено; непустой массив `model_limits` включает ограничение.
`model_limits`	`model_limits`	Строка с запятыми → массив строк; до 1024 байт UTF-8 в объединённом виде.
`allow_ips`	`allow_ips`	Строка с переносами → массив строк; только одиночные IP, без CIDR; `[]` снимает, `null`/недопустимые — 400.

Изменения поведения: успешное создание возвращает HTTP 201 вместо 200, а полный секрет приходит в data.key с префиксом sk-.

Возможности, которые нужно различать

Эндпоинт задач аккаунта возвращает только статус задачи и платёжные метаданные — результаты генерации получайте через эндпоинты результатов.

Значение полей billing и usage описано в Фактической стоимости и использовании задач. Каталог тарифов отражает текущие ставки и не пересчитывает исторические счета.

Управление ключами через публичный API также не поддерживает изменение квоты и восстановление отозванных ключей.

Webhook настраивается через отдельный эндпоинт конфигурации: для каждого обычного модельного ключа одна конфигурация, отдельно от создания и обновления ключа. Подробнее — Получение настроек Webhook.