# Autentikacija

Za svaki poziv koji pokreće model ili čita vaše zahtjeve potreban je API ključ. Katalog (`GET /models`,
`GET /categories`), `POST /quote` i OpenAPI dokument javno su dostupni.

## API ključevi

Izradite i opozovite ključeve na [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ključ izgleda
kao `doitong_` iza kojeg slijedi 64 heksadecimalna znaka i prikazuje se samo jednom, pri izradi. Pošaljite ga u
zaglavlju `Authorization`:

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

`X-API-Key: <key>` također radi.

> [!WARNING]
> Ključeve čuvajte na poslužitelju: svatko tko ima ključ može potrošiti API kredite koje smije potrošiti. Ako ključ procuri,
> opozovite ga i izradite novi.

Zahtjev bez ključa dobiva `401` s kodom `missing_api_key`; nepoznat, opozvan ili istekli ključ također dobiva `401`.

## Opsezi

Svaki ključ ima opsege. API modela provjerava sljedeće:

| Radnja | Potreban opseg |
|---|---|
| Pokretanje modela, otkazivanje zahtjeva, brisanje datoteka zahtjeva, promjena postavke pohrane | `models:run` (rade i ključevi sa starijim `images:create` ili `videos:create`) |
| Izrada URL-a za prijenos | `models:run` ili `media:upload` |
| Čitanje zahtjeva i računa | `models:read` (ključ koji može pokretati modele također može čitati) |

Novi ključevi prema zadanim postavkama dobivaju `models:read` i `models:run`. Poziv bez odgovarajućeg opsega dobiva `403` s kodom
`insufficient_scope`.

## Proračuni kredita

Ključ može imati vlastiti proračun u API kreditima (1.000 API kredita = 1 $), koji postavlja vlasnik računa: ukupni proračun,
dnevni proračun (posljednja 24 sata) ili oboje. Prije naplate pokretanja trošak se uspoređuje s iznosom koji je ključ već
potrošio putem ovog API-ja (umanjeno za povrate). Pokretanje koje bi premašilo taj iznos odbija se s `402 budget_exceeded` i ništa
se ne naplaćuje.

> [!IMPORTANT]
> Odbijanje zbog proračuna konačno je: ponovni pokušaj neće pomoći dok vlasnik ne poveća proračun.

 Ključ bez proračuna može
potrošiti do iznosa API stanja. Odvojeno od toga, pokretanje koje API stanje ne može pokriti dobiva `402 insufficient_credits`
s poveznicom `top_up_url`.

`GET https://api.doitong.com/v1/account` prikazuje API stanje i preostali proračun ključa (oboje u API kreditima):

```json 200 OK · account
{
  "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` kada ključ nema vlastiti proračun.

## Ograničenja brzine

Svaki ključ može poslati 3600 zahtjeva na sat, osim ako je njegovo ograničenje drukčije postavljeno. Svaki autentificirani odgovor sadrži
trenutačno stanje:

| Zaglavlje | Značenje |
|---|---|
| `X-RateLimit-Limit` | Broj zahtjeva dopuštenih u trenutačnom prozoru |
| `X-RateLimit-Remaining` | Broj preostalih zahtjeva u trenutačnom prozoru |
| `X-RateLimit-Reset` | Unixovo vrijeme resetiranja prozora |

Kada premašite ograničenje, dobit ćete `429` sa zaglavljem `Retry-After` (sekunde). Dugotrajno anketiranje s `?wait=` računa se kao jedan
zahtjev po pozivu, pa je čekanje jeftinije od učestalog anketiranja.

Postoji i ograničenje od 10 zahtjeva u tijeku (`queued` ili `running`) po računu. Pokretanje još jednog vraća `429 too_many_inflight`; pokušajte
ponovno nakon što jedan završi.