Подключение
Публичный 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 означает временную недоступность сервиса; уменьшите частоту перед повтором. Не пересылайте вслепую запросы создания, ротации или удаления после тайм-аута.
| HTTP | code | Действие |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | Исправьте тело, параметры или курсор. |
| 401 | 11032 / 11059 | Проверьте системный токен доступа. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | Проверьте статус аккаунта, права и группу ключа. |
| 404 | 13001 / 16008 | Ресурс отсутствует или принадлежит другому аккаунту. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | Устраните ограничения числа ключей, срока, квоты или связи платежей. |
| 429 | 10002 | Выдержите Retry-After. |
| 500 | 10000 / 13029 | Сохраните request_id для проверки. |
| 503 | 11001 / 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
Порядок подключения:
- Вызовите
POST /api/v1/webhook/rotate-secret, чтобы сгенерировать секрет подписи и сохранить его на приёмнике. - Вызовите
PATCH /api/v1/webhook, чтобы задать URL колбэка и включить доставку. - Вызовите
POST /api/v1/webhook/test, чтобы отправить тестовое событие, или проверьте список событий для подтверждения доставки.
Правила проверки подписи и полные шаги — в Получении настроек Webhook.