ToAPIsToAPIs

Подключение

Публичный API читает данные вашего аккаунта и управляет обычными ключами моделей, принадлежащими ему. Основной аккаунт не получает автоматический доступ к данным субаккаунтов. Администраторы также работают только со своими ресурсами.

Публичный API читает данные вашего аккаунта и управляет обычными ключами моделей, принадлежащими ему. Основной аккаунт не получает автоматический доступ к данным субаккаунтов. Администраторы также работают только со своими ресурсами.

Для международного сервиса используйте https://api.toapis.com, для материкового Китая https://api.toapis.cn. Не отправляйте запросы этой группы на корневой домен сайта.

Получить системный токен доступа

Создайте системный токен доступа в настройках аккаунта. Повторная генерация отменяет прежний токен, поэтому обновите интеграции.

Каждый запрос передаёт Bearer YOUR_SYSTEM_ACCESS_TOKEN в заголовке Authorization, заголовок отправляется ровно один. Модельные API-ключи (sk-...), cookie, учётные данные в URL и токены Agent/MCP не принимаются как удостоверение, X-User-Id не требуется.

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

Необязательный заголовок X-Locale принимает en, zh, zh-TW, ja, ko, ru. Без допустимого значения используются языковые настройки аккаунта и результат согласования. Запрос не инициализирует настройки аккаунта.

Результат определяйте по HTTP-статусу и числовому code, а не по локализуемому message.

curl https://api.toapis.com/api/v1/account \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

Ответы и суммы

Все ответы имеют только три поля верхнего уровня: code, message, data. При успехе code=0, message="". HTTP-статус: 200 для обычного успеха, 201 при создании ключа, 202 при постановке теста Webhook в очередь или приёме запроса удаления файлов.

При ошибке сохраняется реальный HTTP-статус, а data ошибки содержит только param, params, request_id или null без раскрытия внутренних деталей.

Идентификаторы ресурсов и суммы передаются десятичными строками, api_key_id в Webhook — целое число. Время — RFC 3339 с часовым поясом. Неизвестные или неприменимые значения возвращают null согласно контракту поля. Баланс и использование возвращаются и в USD, и в кредитах.

Курс — credits_per_usd из ответа. Суммы платежей сохраняют исходную валюту.

Каждый ответ содержит заголовки Cache-Control: private, no-store и X-Request-Id. X-Request-Id идентифицирует данный запрос к API и не является ID исходного запроса генерации из trace использования.

{
  "code": 0,
  "message": "",
  "data": {
    "items": [],
    "has_more": false,
    "next_cursor": null,
    "meta": {}
  }
}

Пагинация и периоды

Кроме списка файлов пользователя, списки возвращают data.items, has_more, next_cursor и meta. В пустом списке items равен [], на последней странице next_cursor равен null, общее число не возвращается. Следующую страницу запрашивайте, передавая next_cursor как есть в cursor и сохраняя фильтры.

При смене фильтров начинайте с первой страницы.

Временные диапазоны — полуоткрытые интервалы UTC [from, to), границы с точностью до секунды округляются вверх. Значения по умолчанию и лимиты различаются: для использования from и to обязательны на каждой странице, максимум 31 день.

Задачи — по умолчанию последние 24 часа, максимум 31 день. Пополнения и счета — по умолчанию последние 31 день, максимум 366 дней. Диапазон по умолчанию фиксируется на первой странице, дальше его можно опускать.

Неизвестные или повторные параметры и ошибки экранирования возвращают 400.

Периоды задаются полуинтервалом UTC [from,to), секундные границы округляются вверх. Для использования from и to обязательны на каждой странице, максимум 31 день. Задачи по умолчанию охватывают 24 часа, максимум 31 день, пополнения и счета 31 день, максимум 366.

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

Лимиты и ошибки

Чтение делит лимит 120 запросов в минуту на пользователя. Сводки использования, счета и тарифы имеют дополнительные лимиты по 6 запросов в минуту; список и детали счетов делят один лимит.

Запись API-ключей, Webhook и файлов делит отдельный лимит 10 запросов в минуту на пользователя, не расходуя лимит чтения. Перевыпуск системного токена не сбрасывает лимиты. Новые и совместимые старые пути используют общий соответствующий лимит.

Слишком частые или многочисленные одновременные запросы могут вернуть 429. Выдерживайте Retry-After со случайной задержкой. Ответ 503 означает временную недоступность сервиса; уменьшите частоту перед повтором. Не пересылайте вслепую запросы создания, ротации или удаления после тайм-аута.

HTTPcodeДействие
40010001 / 10004 / 13002 / 13028 / 16014Исправьте тело, параметры или курсор.
40111032 / 11059Проверьте системный токен доступа.
40311023 / 12001 / 12002 / 12006 / 13003Проверьте статус аккаунта, права и группу ключа.
40413001 / 16008Ресурс отсутствует или принадлежит другому аккаунту.
40913004 / 13005 / 13006 / 15045 / 16015 / 16016Устраните ограничения числа ключей, срока, квоты или связи платежей.
42910002Выдержите Retry-After.
50010000 / 13029Сохраните request_id для проверки.
50311001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029Выдержите паузу и при необходимости сократите период.

Область данных

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

Эндпоинты задач возвращают только сохранённые метаданные задач и подтверждаемую оплату: без результатов генерации, без опроса апстрима, расчётов и возвратов. Пополнения не включают вручную начисленные кредиты и отдельные офлайн-возвраты.

Счета покрывают только текущего проверенного Stripe Customer.

В качестве идентификатора ресурса используйте числовой id из списка или деталей ключа — строка секрета (sk-...) не подходит. Полный секрет возвращается один раз в ответах создания и ротации, последующие чтения его не возвращают.

Успешная запись означает сохранение настройки; применение может занять немного времени.

Отключение, ротация или отзыв ключа могут привести к сбою выполняющихся запросов или задач: платформа не отменяет задачи автоматически и не делает возвратов, периода одновременной валидности старого и нового секретов нет.

Эндпоинты

Ниже указаны основные пути. Оставленные для совместимости старые GET-пути /api/v1/account/... и переход со старых API описаны в истории изменений.

Методы файлов управляют зарегистрированными файлами, сроком хранения и асинхронным удалением. Список файлов является исключением пагинации: только items, next_cursor, последний курсор "", без has_more и meta. Приём удаления возвращает HTTP 202. Настройка срока и удаление делят бюджет записи аккаунта. Пользовательский срок требует включённой автоочистки платформы; ручное удаление от неё не зависит. Область действия и примеры приведены ниже.

HTTP
GET /api/v1/accountПолучить профиль аккаунта
GET /api/v1/account/balanceПолучить баланс аккаунта
GET /api/v1/api-keysСписок API-ключей
GET /api/v1/api-keys/{api_key_id}Получить API-ключ
GET /api/v1/api-keys/{api_key_id}/balanceПолучить баланс ключа
POST /api/v1/api-keysСоздать API-ключ
PATCH /api/v1/api-keys/{api_key_id}Обновить API-ключ
DELETE /api/v1/api-keys/{api_key_id}Отозвать API-ключ
POST /api/v1/api-keys/{api_key_id}/rotateЗаменить секрет API-ключа
GET /api/v1/webhookПолучить настройки Webhook
PATCH /api/v1/webhookОбновить настройки Webhook
POST /api/v1/webhook/rotate-secretСменить секрет подписи Webhook
POST /api/v1/webhook/testПроверить Webhook
GET /api/v1/webhook/eventsСписок событий Webhook
GET /api/v1/webhook/events/{event_id}Получить событие Webhook
GET /api/v1/usage/recordsПолучить записи использования
GET /api/v1/usage/summaryПолучить сводку использования
GET /api/v1/tasksСписок задач аккаунта
GET /api/v1/tasks/{task_id}Получить задачу аккаунта
GET /api/v1/billing/topupsСписок заказов пополнения
GET /api/v1/billing/topups/{trade_no}Получить заказ пополнения
GET /api/v1/billing/payment-methodПолучить способ оплаты
GET /api/v1/billing/auto-topupПолучить настройки автопополнения
GET /api/v1/billing/stripe/invoicesСписок счетов
GET /api/v1/billing/stripe/invoices/{invoice_id}Получить счет
GET /api/v1/pricingПолучить тарифы моделей
GET /api/v1/user/fileСписок файлов пользователя
GET /api/v1/user/file/retentionПолучить срок хранения файлов
PUT /api/v1/user/file/retentionУстановить срок хранения файлов
POST /api/v1/user/file/deletion-requestsСоздать запрос удаления файлов
GET /api/v1/user/file/deletion-requests/{id}Получить прогресс удаления файлов

Webhook

Порядок подключения:

  1. Вызовите POST /api/v1/webhook/rotate-secret, чтобы сгенерировать секрет подписи и сохранить его на приёмнике.
  2. Вызовите PATCH /api/v1/webhook, чтобы задать URL колбэка и включить доставку.
  3. Вызовите POST /api/v1/webhook/test, чтобы отправить тестовое событие, или проверьте список событий для подтверждения доставки.

Правила проверки подписи и полные шаги — в Получении настроек Webhook.

On this page