# Todennus

Jokainen mallin suorittava tai pyyntöjäsi lukeva kutsu tarvitsee API-avaimen. Luettelo (`GET /models`,
`GET /categories`), `POST /quote` ja OpenAPI-dokumentti ovat julkisia.

## API-avaimet

Luo ja kumoa avaimia osoitteessa [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Avain näyttää
`doitong_`-etuliitteeltä, jota seuraa 64 heksadesimaalimerkkiä, ja se näytetään vain kerran luonnin yhteydessä. Lähetä se
`Authorization`-otsakkeessa:

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

`X-API-Key: <key>` toimii myös.

> [!WARNING]
> Säilytä avaimet palvelimellasi: kuka tahansa avaimen haltija voi käyttää sen sallimat API-krediitit. Jos avain vuotaa,
> kumoa se ja luo uusi.

Ilman avainta lähetetty pyyntö saa vastauksen `401` koodilla `missing_api_key`; tuntematon, kumottu tai vanhentunut avain saa myös
vastauksen `401`.

## Käyttöoikeudet

Jokaisella avaimella on käyttöoikeudet. Malli-API tarkistaa seuraavat:

| Toiminto | Vaadittu käyttöoikeus |
|---|---|
| Mallin suorittaminen, pyynnön peruuttaminen, pyynnön tiedostojen poistaminen, tallennustila-asetuksen muuttaminen | `models:run` (myös avaimet, joilla on vanhempi `images:create`- tai `videos:create`-käyttöoikeus, toimivat) |
| Lataus-URL:n luominen | `models:run` tai `media:upload` |
| Pyyntöjen ja tilin lukeminen | `models:read` (myös avain, jolla voi suorittaa malleja, voi lukea) |

Uudet avaimet saavat oletuksena käyttöoikeudet `models:read` ja `models:run`. Ilman oikeaa käyttöoikeutta kutsu saa vastauksen `403`
koodilla `insufficient_scope`.

## Krediittibudjetit

Avaimella voi olla tilinomistajan asettama oma budjetti API-krediitteinä (1 000 API-krediittiä = 1 $): kokonaisbudjetti, päiväbudjetti (viimeiset
24 tuntia) tai molemmat. Ennen ajon veloittamista hinta tarkistetaan suhteessa siihen, kuinka paljon avaimella on jo käytetty tämän API:n
kautta (hyvitykset vähennettyinä). Ajo, joka ylittäisi rajan, hylätään vastauksella `402 budget_exceeded`, eikä mitään veloiteta.

> [!IMPORTANT]
> Budjetin ylittävä pyyntö hylätään lopullisesti: uudelleenyritys ei auta, ennen kuin omistaja korottaa budjettia.

 Avaimella, jolla ei ole budjettia, voi käyttää enintään API-saldon verran. Lisäksi ajo, jota API-saldo ei kata, saa vastauksen
`402 insufficient_credits` ja sisältää `top_up_url`-osoitteen.

`GET https://api.doitong.com/v1/account` näyttää API-saldon ja avaimen jäljellä olevan budjetin (molemmat API-krediitteinä):

```json 200 OK · tili
{
  "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` on `null`, kun avaimella ei ole omaa budjettia.

## Nopeusrajoitukset

Jokainen avain voi tehdä 3600 pyyntöä tunnissa, ellei sen rajaa ole asetettu toisin. Jokainen todennettu vastaus sisältää nykyisen tilan:

| Otsake | Merkitys |
|---|---|
| `X-RateLimit-Limit` | Nykyisen aikaikkunan sallittujen pyyntöjen määrä |
| `X-RateLimit-Remaining` | Nykyisen aikaikkunan jäljellä olevat pyynnöt |
| `X-RateLimit-Reset` | Unix-aika, jolloin aikaikkuna nollautuu |

Rajan ylittäessä saat vastauksen `429` ja `Retry-After`-otsakkeen (sekunteina). Pitkä kysely parametrilla `?wait=` lasketaan yhdeksi
pyynnöksi kutsua kohti, joten odottaminen on edullisempaa kuin tiheä kysely.

Tilillä voi olla samanaikaisesti enintään 10 käynnissä olevaa pyyntöä (`queued` tai `running`). Ylimääräinen käynnistys palauttaa
`429 too_many_inflight`; yritä uudelleen, kun yksi on valmistunut.