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

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

## API-ключи

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

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

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

> [!WARNING]
> Храните ключи на своём сервере: любой, у кого есть ключ, может потратить разрешённые для него API-кредиты. Если ключ утёк,
> отзовите его и создайте новый.

Запрос без ключа получает `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`, и средства
не списываются.

> [!IMPORTANT]
> Отказ из-за бюджета окончателен: повторная попытка не поможет, пока владелец не увеличит бюджет.

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

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

```json 200 OK · аккаунт
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/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`; повторите запуск после завершения одного из них.