# Preverjanje pristnosti

Vsak klic, ki zažene model ali prebere vaše zahteve, potrebuje ključ API. Katalog (`GET /models`,
`GET /categories`), `POST /quote` in dokument OpenAPI so javni.

## Ključi API

Ključe ustvarjate in preklicujete na naslovu [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ključ je videti
kot `doitong_`, ki mu sledi 64 šestnajstiških znakov, in je prikazan samo enkrat, ko ga ustvarite. Pošljite ga v
glavi `Authorization`:

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

`X-API-Key: <key>` deluje prav tako.

> [!WARNING]
> Ključe hranite na strežniku: kdor ima ključ, lahko porabi dovoljene kredite API. Če ključ uide,
> ga prekličite in ustvarite novega.

Zahteva brez ključa prejme `401` s kodo `missing_api_key`; neznan, preklican ali potekel ključ prav tako prejme `401`.

## Obsegi

Vsak ključ ima obsege. API modelov preverja naslednje:

| Dejanje | Potreben obseg |
|---|---|
| Zagon modela, preklic zahteve, brisanje datotek zahteve, sprememba nastavitve shrambe | `models:run` (delujejo tudi ključi s starejšima obsegoma `images:create` ali `videos:create`) |
| Ustvarjanje URL-ja za nalaganje | `models:run` ali `media:upload` |
| Branje zahtev in računa | `models:read` (ključ, ki lahko zaganja modele, lahko tudi bere) |

Novi ključi privzeto dobijo `models:read` in `models:run`. Klic brez ustreznega obsega prejme `403` s kodo
`insufficient_scope`.

## Proračuni kreditov

Ključ ima lahko lasten proračun v kreditih API (1000 API kreditov = 1 $), ki ga nastavi lastnik računa: skupni proračun,
dnevni proračun (zadnjih 24 ur) ali oboje. Pred zaračunavanjem izvedbe se strošek preveri glede na to, koliko je
ključ že porabil prek tega API-ja (brez upoštevanja vračil). Izvedba, ki bi presegla proračun, je zavrnjena z `402 budget_exceeded`,
noben znesek pa ni zaračunan.

> [!IMPORTANT]
> Zavrnitev zaradi proračuna je dokončna: ponovni poskus ne bo pomagal, dokler lastnik ne poveča proračuna.

 Ključ brez proračuna lahko
porabi največ toliko, kolikor znaša stanje API. Ločeno velja, da izvedba, ki je stanje API ne more pokriti, prejme `402 insufficient_credits`
z `top_up_url`.

`GET https://api.doitong.com/v1/account` prikazuje stanje API in preostali proračun ključa (oboje v kreditih API):

```json 200 OK · račun
{
  "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`, če ključ nima lastnega proračuna.

## Omejitve hitrosti

Vsak ključ lahko izvede 3600 zahtev na uro, razen če je bila njegova omejitev nastavljena drugače. Vsak preverjeni odgovor vsebuje
trenutno stanje:

| Glava | Pomen |
|---|---|
| `X-RateLimit-Limit` | Število dovoljenih zahtev v trenutnem obdobju |
| `X-RateLimit-Remaining` | Preostalo število zahtev v trenutnem obdobju |
| `X-RateLimit-Reset` | Unixov čas ponastavitve obdobja |

Ko presežete omejitev, prejmete `429` z glavo `Retry-After` (sekunde). Dolgo preverjanje z `?wait=` šteje kot ena zahteva
na klic, zato je čakanje učinkovitejše od hitrega preverjanja.

Na račun velja tudi omejitev 10 zahtev v izvajanju (`queued` ali `running`). Zagon še ene vrne
`429 too_many_inflight`; znova jo zaženite, ko se ena od njih konča.