# Autentifikavimas

Kiekvienam kvietimui, kuris vykdo modelį arba skaito jūsų užklausas, reikia API rakto. Katalogas (`GET /models`,
`GET /categories`), `POST /quote` ir OpenAPI dokumentas yra vieši.

## API raktai

Kurkite ir atšaukite raktus adresu [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Raktas atrodo kaip `doitong_`, po kurio eina 64 šešioliktainiai simboliai, ir rodomas tik vieną kartą – jį sukūrus. Siųskite jį `Authorization` antraštėje:

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

`X-API-Key: <key>` taip pat veikia.

> [!WARNING]
> Laikykite raktus savo serveryje: kiekvienas, turintis raktą, gali išleisti leidžiamus API kreditus. Jei raktas nuteka,
> atšaukite jį ir sukurkite naują.

Užklausa be rakto grąžina `401` su kodu `missing_api_key`; nežinomas, atšauktas arba pasibaigusio galiojimo raktas taip pat grąžina `401`.

## Apimtys

Kiekvienas raktas turi apimtis. Modelio API tikrina šias apimtis:

| Veiksmas | Reikalinga apimtis |
|---|---|
| Vykdyti modelį, atšaukti užklausą, ištrinti užklausos failus, pakeisti saugyklos nustatymą | `models:run` (taip pat veikia raktai su senesnėmis `images:create` arba `videos:create`) |
| Sukurti įkėlimo URL | `models:run` arba `media:upload` |
| Skaityti užklausas, paskyrą | `models:read` (raktas, galintis vykdyti modelius, taip pat gali juos skaityti) |

Naujiems raktams pagal numatytuosius nustatymus suteikiamos `models:read` ir `models:run` apimtys. Kvietimas be tinkamos apimties grąžina `403` su kodu `insufficient_scope`.

## Kreditų biudžetai

Raktas gali turėti savo API kreditų biudžetą (1 000 API kreditų = 1 $), kurį nustato paskyros savininkas: bendrą biudžetą, dienos biudžetą (per pastarąsias 24 valandas) arba abu. Prieš pritaikant mokestį už vykdymą, kaina palyginama su tuo, kiek raktas jau išleido per šią API (įskaičiavus grąžinimus). Vykdymas, dėl kurio riba būtų viršyta, atmetamas su `402 budget_exceeded`, o mokestis netaikomas.

> [!IMPORTANT]
> Biudžeto atsisakymas yra galutinis: pakartotinis bandymas nepadės, kol savininkas nepadidins biudžeto.

 Raktas be biudžeto gali
leisti iki API likučio. Atskirai vykdymas, kurio API likutis negali padengti, grąžina `402 insufficient_credits`
su `top_up_url`.

`GET https://api.doitong.com/v1/account` rodo API likutį ir likusį rakto biudžetą (abu API kreditais):

```json 200 OK · paskyra
{
  "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` yra `null`, kai raktas neturi savo biudžeto.

## Užklausų dažnio ribojimas

Kiekvienas raktas gali pateikti 3600 užklausų per valandą, nebent jo riba nustatyta kitaip. Kiekviename autentifikuotame atsakyme pateikiama dabartinė būsena:

| Antraštė | Reikšmė |
|---|---|
| `X-RateLimit-Limit` | Užklausų skaičius dabartiniame lange |
| `X-RateLimit-Remaining` | Likutis dabartiniame lange |
| `X-RateLimit-Reset` | Unix laikas, kada langas nustatomas iš naujo |

Viršijus ribą gausite `429` su `Retry-After` antrašte (sekundėmis). Ilga apklausa su `?wait=` skaičiuojama kaip viena užklausa per kvietimą, todėl laukti pigiau nei dažnai vykdyti apklausą.

Taip pat vienai paskyrai taikoma 10 vykdomų užklausų (`queued` arba `running`) riba. Pradėjus dar vieną grąžinama
`429 too_many_inflight`; pradėkite ją iš naujo, kai viena užklausa bus baigta.