Перейти к содержимому
Русский
Получить API-ключ
Руководство по API

Аутентификация

Просмотреть как Markdown Обновлено

Для каждого вызова, который запускает модель или читает ваши запросы, нужен API-ключ. Каталог (GET /models, GET /categories), POST /quote и документ OpenAPI общедоступны.

API-ключи

Создавайте и отзывайте ключи на странице https://doitong.com/developers/dashboard#keys. Ключ выглядит как doitong_, за которым следуют 64 шестнадцатеричных символа; он показывается только один раз — при создании. Передавайте его в заголовке Authorization:

терминал
curl https://api.doitong.ru/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> также работает.

Запрос без ключа получает 401 с кодом missing_api_key; неизвестный, отозванный или просроченный ключ также получает 401.

Области доступа

Каждый ключ содержит области доступа. API моделей проверяет следующие области:

Действие Требуемая область доступа
Запустить модель, отменить запрос, удалить файлы запроса, изменить настройку хранилища models:run (также работают ключи со старыми областями images:create или videos:create)
Создать URL для загрузки models:run или media:upload
Читать запросы и аккаунт models:read (ключ, с которого можно запускать модели, также позволяет читать данные)

Новые ключи по умолчанию получают models:read и models:run. Вызов без необходимой области доступа получает 403 с кодом insufficient_scope.

Бюджеты в кредитах

Для ключа можно задать собственный бюджет в API-кредитах (1 000 API-кредитов = 1 $), который устанавливает владелец аккаунта: общий бюджет, дневной бюджет (за последние 24 часа) или оба. Перед списанием за запуск стоимость сравнивается с уже потраченной этим ключом через API суммой (за вычетом возвратов). Запуск, который превысит бюджет, отклоняется с ошибкой 402 budget_exceeded, и средства не списываются.

Ключ без бюджета может тратить средства в пределах баланса API. Отдельно: если баланс API не покрывает стоимость запуска, вы получите 402 insufficient_credits с полем top_up_url.

GET https://api.doitong.ru/v1/account показывает баланс API и оставшийся бюджет ключа (оба значения указаны в API-кредитах):

200 OK · аккаунт
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

budget_remaining имеет значение null, если для ключа не задан собственный бюджет.

Ограничения частоты запросов

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

Заголовок Значение
X-RateLimit-Limit Количество запросов, разрешённых в текущем окне
X-RateLimit-Remaining Количество запросов, оставшихся в текущем окне
X-RateLimit-Reset Время Unix, когда окно сбрасывается

При превышении лимита вы получите 429 с заголовком Retry-After (в секундах). Длительный опрос с ?wait= считается одним запросом за вызов, поэтому ожидание выгоднее частого опроса.

Кроме того, для каждого аккаунта действует ограничение в 10 запросов, находящихся в процессе (queued или running). Запуск ещё одного возвращает 429 too_many_inflight; повторите запуск после завершения одного из них.