# Awtentikazzjoni

Kull sejħa li tmexxi mudell jew taqra t-talbiet tiegħek teħtieġ ċavetta API. Il-katalgu (`GET /models`, `GET /categories`), `POST /quote` u d-dokument OpenAPI huma pubbliċi.

## Ċwievet API

Oħloq u rrevoka ċwievet fuq [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Ċavetta tidher bħal `doitong_` segwita minn 64 karattru eżadeċimali u tintwera darba biss, meta toħloqha. Ibgħatha fil-header `Authorization`:

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

`X-API-Key: <key>` taħdem ukoll.

> [!WARNING]
> Żomm iċ-ċwievet fuq is-server tiegħek: kull min għandu ċavetta jista' jonfoq il-krediti tal-API li għandha permess tonfoq. Jekk ċavetta toħroġ, irrevokaha u oħloq waħda ġdida.

Talba mingħajr ċavetta tirċievi `401` bil-kodiċi `missing_api_key`; ċavetta mhux magħrufa, rrevokata jew skaduta tirċievi `401` ukoll.

## Ambiti

Kull ċavetta għandha ambiti. L-API tal-mudelli tivverifika dawn:

| Azzjoni | Ambitu meħtieġ |
|---|---|
| Mexxi mudell, ikkanċella talba, ħassar il-fajls ta' talba, ibdel is-setting tal-ħażna | `models:run` (ċwievet bl-`images:create` jew `videos:create` l-antik jaħdmu wkoll) |
| Oħloq URL tat-tlugħ | `models:run` jew `media:upload` |
| Aqra t-talbiet, il-kont | `models:read` (ċavetta li tista' tmexxi mudelli taqrahom ukoll) |

Ċwievet ġodda jiksbu `models:read` u `models:run` b'mod prestabbilit. Sejħa mingħajr l-ambitu korrett tirċievi `403` bil-kodiċi `insufficient_scope`.

## Baġits tal-krediti

Ċavetta jista' jkollha l-baġit tagħha fi krediti tal-API (1,000 krediti tal-API = $1), stabbilit mis-sid tal-kont: baġit totali, baġit ta' kuljum (l-aħħar 24 siegħa), jew it-tnejn. Qabel ma tintalab il-ħlas għal ġenerazzjoni, l-ispiża tiġi vverifikata kontra dak li ċ-ċavetta tkun diġà nefqet permezz ta' din l-API (wara r-rifużjonijiet). Ġenerazzjoni li taqbeż dan tiġi rrifjutata b'`402 budget_exceeded` u ma jintalab ebda ħlas.

> [!IMPORTANT]
> Rifjut minħabba baġit huwa finali: tentattiv mill-ġdid ma jgħinx sakemm is-sid ma jgħollix il-baġit.

 Ċavetta mingħajr baġit tista' tonfoq sa l-ammont tal-bilanċ tal-API. Separatament, ġenerazzjoni li l-bilanċ tal-API ma jistax ikopri tirċievi `402 insufficient_credits` b'`top_up_url`.

`GET https://api.doitong.com/v1/account` juri l-bilanċ tal-API u l-baġit li jifdal taċ-ċavetta (it-tnejn fi krediti tal-API):

```json 200 OK · kont
{
  "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` huwa `null` meta ċ-ċavetta ma jkollhiex baġit tagħha.

## Limiti tar-rata

Kull ċavetta tista' tagħmel 3600 talba fis-siegħa sakemm il-limitu tagħha ma jkunx stabbilit b'mod differenti. Kull rispons awtentikat iġorr l-istat attwali:

| Header | Tifsira |
|---|---|
| `X-RateLimit-Limit` | Talbiet permessi fit-tieqa attwali |
| `X-RateLimit-Remaining` | Talbiet li fadal fit-tieqa attwali |
| `X-RateLimit-Reset` | Ħin Unix meta t-tieqa terġa' tibda |

Meta taqbeż il-limitu tirċievi `429` b'header `Retry-After` (sekondi). Polling twil b'`?wait=` jgħodd bħala talba waħda għal kull sejħa, għalhekk l-istennija hija orħos minn polling veloċi.

Hemm ukoll limitu ta' 10 talbiet għaddejjin (`queued` jew `running`) għal kull kont. Il-bidu ta' waħda oħra jirritorna `429 too_many_inflight`; ibdiha mill-ġdid wara li waħda tintemm.