# Godkendelse

Ethvert kald, der kører en model eller læser dine anmodninger, kræver en API-nøgle. Kataloget (`GET /models`,
`GET /categories`), `POST /quote` og OpenAPI-dokumentet er offentlige.

## API-nøgler

Opret og tilbagekald nøgler på [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). En nøgle ser
ud som `doitong_` efterfulgt af 64 hexadecimale tegn og vises kun én gang, når du opretter den. Send den i
`Authorization`-headeren:

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

`X-API-Key: <key>` fungerer også.

> [!WARNING]
> Opbevar nøgler på din server: Alle, der har en nøgle, kan bruge de API-kreditter, den har tilladelse til at bruge. Hvis en nøgle lækkes,
> skal du tilbagekalde den og oprette en ny.

En anmodning uden nøgle får `401` med koden `missing_api_key`; en ukendt, tilbagekaldt eller udløbet nøgle får også `401`.

## Områder

Hver nøgle har scopes. Model-API'et kontrollerer disse:

| Handling | Påkrævet scope |
|---|---|
| Kør en model, annuller en anmodning, slet en anmodnings filer, rediger lagringsindstillingen | `models:run` (nøgler med det ældre `images:create` eller `videos:create` fungerer også) |
| Opret en upload-URL | `models:run` eller `media:upload` |
| Læs anmodninger og konto | `models:read` (en nøgle, der må køre modeller, kan også læse) |

Nye nøgler får som standard `models:read` og `models:run`. Et kald uden det rette scope får `403` med koden
`insufficient_scope`.

## Kreditbudgetter

En nøgle kan have sit eget budget i API-kreditter (1.000 API-kreditter = 1 $), angivet af kontoejeren: et samlet budget, et
dagligt budget (seneste 24 timer) eller begge. Før en kørsel opkræves, kontrolleres prisen mod det, nøglen allerede har
brugt via denne API (netto efter tilbagebetalinger). En kørsel, der ville overskride det, afvises med `402 budget_exceeded`, og der
opkræves ingenting.

> [!IMPORTANT]
> En budgetafvisning er endelig: Det hjælper ikke at prøve igen, før ejeren hæver budgettet.

 En nøgle uden budget kan
bruge op til API-saldoen. Separat får en kørsel, som API-saldoen ikke kan dække, `402 insufficient_credits`
med en `top_up_url`.

`GET https://api.doitong.com/v1/account` viser API-saldoen og nøglens resterende budget (begge i API-kreditter):

```json 200 OK · konto
{
  "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`, når nøglen ikke har sit eget budget.

## Hastighedsgrænser

Hver nøgle må foretage 3600 anmodninger i timen, medmindre grænsen er angivet anderledes. Alle godkendte svar indeholder
den aktuelle status:

| Header | Betydning |
|---|---|
| `X-RateLimit-Limit` | Antal anmodninger tilladt i det aktuelle vindue |
| `X-RateLimit-Remaining` | Antal anmodninger tilbage i det aktuelle vindue |
| `X-RateLimit-Reset` | Unix-tidspunkt, hvor vinduet nulstilles |

Når grænsen overskrides, får du `429` med en `Retry-After`-header (sekunder). Lang polling med `?wait=` tæller som én anmodning
pr. kald, så det er billigere at vente end at polle hurtigt.

Der er også en grænse på 10 anmodninger under behandling (`queued` eller `running`) pr. konto. Start af endnu en returnerer
`429 too_many_inflight`; start den igen, efter en anden er afsluttet.