# Autentifikacia

Sako mangipen savo kerel jekh modelo vaj ginel tuthe mangipena mangel jekh API klidin. O katalogo (`GET /models`,
`GET /categories`), `POST /quote` thaj o OpenAPI dokumento si publika.

## API klidini

Ker thaj irinel klidinen ko [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Jekh klidin dikhel
sar `doitong_` palem 64 hex karaktera thaj sikavel pes numa jekhvar, kana les keres. Bičhal les andre
`Authorization` header:

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

`X-API-Key: <key>` kerel buti vi.

> [!WARNING]
> Garav o klidini tire servereste: sako savo si le klidinesa šaj te pherel o API krediti save les si pravo te pherel. Te jekh klidin
> čhiv pes avri, irinel les thaj ker nevo.

Jekh mangipen bizo klidin lel `401` le codesa `missing_api_key`; jekh na-prindžardo, irime vaj pherdo klidin lel `401` vi.

## Scope

Sako klidin anel scope. O modelo API kontrolinel kala:

| Akcija | Manglo scope |
|---|---|
| Ker jekh modelo, cancelin jekh mangipen, čhin fajlo le mangipnasqe, paruv o arakhipnasqo setting | `models:run` (klidini le purane `images:create` vaj `videos:create` keren buti vi) |
| Ker jekh upload URL | `models:run` vaj `media:upload` |
| Gin mangipena, konto | `models:read` (jekh klidin savo šaj te kerel modelo ginel vi) |

Neve klidini len `models:read` thaj `models:run` standardno. Jekh mangipen bizo lačho scope lel `403` le codesa
`insufficient_scope`.

## Kreditenge budžeto

Jekh klidin šaj te lel lesqo budžeto andre API krediti (1,000 API krediti = $1), thovdo le kontosqe malavtutnesa: totalno budžeto, jekhesqo
divesqo budžeto (palune 24 sekunda), vaj soduj. Angla te pokinel jekh keripe, o mol kontrolinel pes prema kodo so o klidin
užardas palal kado API (netto iripnengo). Jekh keripe savo bi te prevel les, na lel pes thaj del `402 budget_exceeded`; nič na pokinel pes.

> [!IMPORTANT]
> Jekh budžetutni odmuka si finalno: retry na pomožinel dži o malavtutno na vazdel o budžeto.

 Jekh klidin bizo budžeto šaj te pherel dži ko API balanso. Averutno, jekh keripe savo na šaj te avel pokindo le API balancosa lel `402 insufficient_credits`
le `top_up_url`.

`GET https://api.doitong.ru/v1/account` sikavel o API balanso thaj o klidinesqo ačhilo budžeto (soduj andre API krediti):

```json 200 OK · konto
{
  "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` si `null` kana o klidin na si lesqo budžeto.

## Rate limitura

Sako klidin šaj te kerel 3600 mangipena pro jekh ora, te lesqo limit na sas paruvdo. Sako autentifikime odpoveda anel
akto stavo:

| Header | So phenel |
|---|---|
| `X-RateLimit-Limit` | Mangipena save si mukle andre akto vaxtosqo intervalo |
| `X-RateLimit-Remaining` | Mangipena save ačhile andre akto vaxtosqo intervalo |
| `X-RateLimit-Reset` | Unix vakti kana o intervalo pale startinel |

Te predes o limit, les `429` le `Retry-After` headeresa (sekunda). Baro polling le `?wait=` ginel pes sar jekh mangipen pro sako
call, vašoda o ačhimo si po barato sar sigo polling.

Si vi jekh limit 10 mangipnengo andro proceso (`queued` vaj `running`) pro sako konto. O starto jekhes aver del
`429 too_many_inflight`; startin les pale kana jekh agorisardilo.