# Ověřování

Každé volání, které spouští model nebo načítá vaše požadavky, potřebuje API klíč. Katalog (`GET /models`,
`GET /categories`), `POST /quote` a dokument OpenAPI jsou veřejné.

## API klíče

Vytvářejte a rušte klíče na stránce [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Klíč vypadá
jako `doitong_` následovaný 64 hexadecimálními znaky a zobrazí se pouze jednou při vytvoření. Odešlete ho v hlavičce
`Authorization`:

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

`X-API-Key: <key>` funguje také.

> [!WARNING]
> Klíče uchovávejte na serveru: každý, kdo klíč má, může utratit API kredity, k jejichž utrácení je oprávněn. Pokud klíč unikne,
> zrušte ho a vytvořte nový.

Požadavek bez klíče obdrží `401` s kódem `missing_api_key`; neznámý, zrušený nebo prošlý klíč obdrží také `401`.

## Rozsahy oprávnění

Každý klíč obsahuje rozsahy oprávnění. API modelů kontroluje tyto rozsahy:

| Akce | Potřebný rozsah |
|---|---|
| Spuštění modelu, zrušení požadavku, odstranění souborů požadavku, změna nastavení úložiště | `models:run` (fungují také klíče se staršími `images:create` nebo `videos:create`) |
| Vytvoření URL pro nahrání | `models:run` nebo `media:upload` |
| Čtení požadavků a účtu | `models:read` (klíč, který může spouštět modely, může také číst) |

Nové klíče ve výchozím nastavení získají `models:read` a `models:run`. Volání bez správného rozsahu obdrží `403` s kódem
`insufficient_scope`.

## Rozpočty API kreditů

Klíč může mít vlastní rozpočet v API kreditech (1 000 kreditů API = 1 $), který nastaví vlastník účtu: celkový rozpočet, denní
rozpočet (za posledních 24 hodin) nebo obojí. Před zaúčtováním spuštění se cena porovná s částkou, kterou klíč již
prostřednictvím tohoto API utratil (po odečtení refundací). Spuštění, které by rozpočet překročilo, je odmítnuto s `402 budget_exceeded`
a nic se nezaúčtuje.

> [!IMPORTANT]
> Odmítnutí kvůli rozpočtu je konečné: opakování nepomůže, dokud vlastník rozpočet nezvýší.

 Klíč bez rozpočtu může
utratit až do výše zůstatku API. Samostatně platí, že spuštění, které zůstatek API nepokryje, obdrží `402 insufficient_credits`
s `top_up_url`.

`GET https://api.doitong.com/v1/account` zobrazuje zůstatek API a zbývající rozpočet klíče (obojí v API kreditech):

```json 200 OK · účet
{
  "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` je `null`, pokud klíč nemá vlastní rozpočet.

## Limity rychlosti

Každý klíč může provést 3600 požadavků za hodinu, pokud jeho limit nebyl nastaven jinak. Každá ověřená odpověď obsahuje
aktuální stav:

| Hlavička | Význam |
|---|---|
| `X-RateLimit-Limit` | Počet požadavků povolených v aktuálním okně |
| `X-RateLimit-Remaining` | Počet požadavků zbývajících v aktuálním okně |
| `X-RateLimit-Reset` | Unixový čas resetování okna |

Po překročení limitu obdržíte `429` s hlavičkou `Retry-After` (sekundy). Dlouhé dotazování s `?wait=` se počítá jako jeden požadavek
na volání, takže čekání je levnější než rychlé dotazování.

Na účet se vztahuje také limit 10 probíhajících požadavků (ve stavu `queued` nebo `running`). Spuštění dalšího vrátí
`429 too_many_inflight`; spusťte ho znovu po dokončení jednoho z nich.