# Autentifikācija

Katram izsaukumam, kas palaiž modeli vai nolasa jūsu pieprasījumus, ir nepieciešama API atslēga. Katalogs (`GET /models`,
`GET /categories`), `POST /quote` un OpenAPI dokuments ir publiski.

## API atslēgas

Izveidojiet un atsauciet atslēgas vietnē [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Atslēga izskatās
kā `doitong_`, kam seko 64 heksadecimālas rakstzīmes, un tā tiek parādīta tikai vienreiz — izveides brīdī. Nosūtiet to
`Authorization` galvenē:

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

`X-API-Key: <key>` darbojas tāpat.

> [!WARNING]
> Glabājiet atslēgas savā serverī: ikviens, kam ir atslēga, var iztērēt atļautos API kredītus. Ja atslēga ir noplūdusi,
> atsauciet to un izveidojiet jaunu.

Pieprasījums bez atslēgas saņem `401` ar kodu `missing_api_key`; nezināma, atsaukta vai beigusies atslēga saņem `401` tāpat.

## Tvērumi

Katrai atslēgai ir tvērumi. Modeļu API tos pārbauda:

| Darbība | Nepieciešamais tvērums |
|---|---|
| Palaist modeli, atcelt pieprasījumu, dzēst pieprasījuma failus, mainīt krātuves iestatījumu | `models:run` (darbojas arī atslēgas ar vecāko `images:create` vai `videos:create`) |
| Izveidot augšupielādes URL | `models:run` vai `media:upload` |
| Lasīt pieprasījumus un kontu | `models:read` (atslēga, ar kuru drīkst palaist modeļus, var arī lasīt) |

Jaunās atslēgas pēc noklusējuma saņem `models:read` un `models:run`. Izsaukums bez pareizā tvēruma saņem `403` ar kodu
`insufficient_scope`.

## Kredītu budžeti

Atslēgai var būt savs budžets API kredītos (1000 API kredītu = 1 $), ko iestata konta īpašnieks: kopējais budžets, dienas budžets
(pēdējās 24 stundas) vai abi. Pirms maksas iekasēšanas par izpildi izmaksas tiek salīdzinātas ar summu, ko atslēga jau ir
iztērējusi, izmantojot šo API (atskaitot atmaksas). Izpilde, kas pārsniegtu šo summu, tiek noraidīta ar `402 budget_exceeded`, un nekas
netiek iekasēts.

> [!IMPORTANT]
> Budžeta noraidījums ir galīgs: atkārtots mēģinājums nepalīdzēs, kamēr īpašnieks nepalielinās budžetu.

 Atslēga bez budžeta var
iztērēt līdz API atlikuma summai. Atsevišķi izpilde, ko API atlikums nevar segt, saņem `402 insufficient_credits`
ar `top_up_url`.

`GET https://api.doitong.com/v1/account` parāda API atlikumu un atslēgas atlikušo budžetu (abi API kredītos):

```json 200 OK · konts
{
  "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` ir `null`, ja atslēgai nav sava budžeta.

## Ātruma ierobežojumi

Katra atslēga var veikt 3600 pieprasījumus stundā, ja vien tās ierobežojums nav iestatīts citādi. Katrā autentificētā atbildē ir
norādīts pašreizējais stāvoklis:

| Galvene | Nozīme |
|---|---|
| `X-RateLimit-Limit` | Pašreizējā logā atļautie pieprasījumi |
| `X-RateLimit-Remaining` | Pašreizējā logā atlikušie pieprasījumi |
| `X-RateLimit-Reset` | Unix laiks, kad logs tiek atiestatīts |

Pārsniedzot ierobežojumu, saņemsiet `429` ar `Retry-After` galveni (sekundēs). Ilgstoša gaidīšana ar `?wait=` tiek uzskaitīta kā viens pieprasījums
katrā izsaukumā, tāpēc gaidīšana ir izdevīgāka nekā bieža statusa pārbaude.

Turklāt vienam kontam vienlaikus var būt ne vairāk kā 10 procesā esoši pieprasījumi (`queued` vai `running`). Sākot vēl vienu, tiek atgriezts
`429 too_many_inflight`; sāciet to vēlreiz pēc tam, kad kāds pieprasījums ir pabeigts.