# Auðkenning

Í hverju kalli sem keyrir líkan eða les beiðnirnar þínar þarf API-lykil. Vörulistinn (`GET /models`,
`GET /categories`), `POST /quote` og OpenAPI-skjalið eru opinber.

## API-lyklar

Búðu til og afturkallaðu lykla á [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Lykill lítur út
fyrir `doitong_` á eftir 64 sextándastöfum og birtist aðeins einu sinni þegar þú býrð hann til. Sendu hann í
`Authorization`-hausnum:

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

`X-API-Key: <key>` virkar einnig.

> [!WARNING]
> Geymdu lykla á netþjóninum þínum: hver sem hefur lykil getur eytt þeim API-inneignum sem honum er heimilt að eyða. Ef lykill lekur,
> afturkallaðu hann og búðu til nýjan.

Beiðni án lykils fær `401` með kóðanum `missing_api_key`; óþekktur, afturkallaður eða útrunninn lykill fær einnig `401`.

## Umfang

Hver lykill hefur umfang. API líkansins athugar þetta:

| Aðgerð | Nauðsynlegt umfang |
|---|---|
| Keyra líkan, hætta við beiðni, eyða skrám beiðni, breyta geymslustillingu | `models:run` (lyklar með eldra `images:create` eða `videos:create` virka líka) |
| Búa til upphleðsluvefslóð | `models:run` eða `media:upload` |
| Lesa beiðnir, reikning | `models:read` (lykill sem má keyra líkön getur einnig lesið) |

Nýir lyklar fá `models:read` og `models:run` sjálfgefið. Kall án réttrar heimildar fær `403` með kóðanum
`insufficient_scope`.

## Fjárhagsrammar inneignar

Lykill getur haft sinn eigin fjárhagsramma í API-inneign (1.000 API-inneignir = 1 $), sem reikningseigandinn stillir: heildarfjárhagsramma, daglegan fjárhagsramma
(síðustu 24 klukkustundir) eða hvort tveggja. Áður en keyrsla er gjaldfærð er kostnaðurinn borinn saman við það sem lykillinn hefur þegar
varið í gegnum þetta API (að frádregnum endurgreiðslum). Keyrsla sem færi yfir mörkin er hafnað með `402 budget_exceeded` og ekkert
er gjaldfært.

> [!IMPORTANT]
> Höfnun vegna fjárhagsramma er endanleg: endurtekning hjálpar ekki fyrr en eigandinn hækkar fjárhagsrammann.

 Lykill án fjárhagsramma getur
varið allt að API-stöðunni. Sérstaklega fær keyrsla sem API-staðan getur ekki greitt `402 insufficient_credits`
með `top_up_url`.

`GET https://api.doitong.com/v1/account` sýnir API-stöðuna og eftirstöðvar fjárhagsramma lykilsins (bæði í API-inneign):

```json 200 OK · account
{
  "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` er `null` þegar lykillinn hefur engan eigin fjárhagsramma.

## Hraðatakmarkanir

Hver lykill má gera 3600 beiðnir á klukkustund nema takmörk hans hafi verið stillt öðruvísi. Í hverju auðkenndu svari kemur
fram núverandi staða:

| Haus | Merking |
|---|---|
| `X-RateLimit-Limit` | Leyfðar beiðnir í núverandi tímabili |
| `X-RateLimit-Remaining` | Eftirstandandi beiðnir í núverandi tímabili |
| `X-RateLimit-Reset` | Unix-tími þegar tímabilið endurstillist |

Þegar farið er yfir mörkin færðu `429` með `Retry-After`-haus (sekúndur). Löng könnun með `?wait=` telst sem ein beiðni
fyrir hvert kall, svo bið er ódýrari en hröð könnun.

Einnig eru takmörk á 10 beiðnum í vinnslu (`queued` eða `running`) á hvern reikning. Þegar einni í viðbót er hleypt af stokkunum fæst
`429 too_many_inflight`; ræstu hana aftur eftir að einni lýkur.