# Autentisering

Varje anrop som kör en modell eller läser dina begäranden behöver en API-nyckel. Katalogen (`GET /models`, `GET /categories`), `POST /quote` och OpenAPI-dokumentet är offentliga.

## API-nycklar

Skapa och återkalla nycklar på [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). En nyckel ser ut som `doitong_` följt av 64 hexadecimala tecken och visas bara en gång när du skapar den. Skicka den i `Authorization`-headern:

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

`X-API-Key: <key>` fungerar också.

> [!WARNING]
> Förvara nycklar på din server: alla som har en nyckel kan använda de API-krediter som den får använda. Om en nyckel läcker ut återkallar du den och skapar en ny.

En begäran utan nyckel får `401` med koden `missing_api_key`; en okänd, återkallad eller utgången nyckel får också `401`.

## Omfattningar

Varje nyckel har omfattningar. Modell-API:t kontrollerar dessa:

| Åtgärd | Krävd omfattning |
|---|---|
| Köra en modell, avbryta en begäran, ta bort en begärans filer, ändra lagringsinställningen | `models:run` (nycklar med de äldre `images:create` eller `videos:create` fungerar också) |
| Skapa en uppladdnings-URL | `models:run` eller `media:upload` |
| Läsa begäranden, konto | `models:read` (en nyckel som får köra modeller får också läsa) |

Nya nycklar får `models:read` och `models:run` som standard. Ett anrop utan rätt omfattning får `403` med koden `insufficient_scope`.

## Kreditbudgetar

En nyckel kan ha en egen budget i API-krediter (1 000 API-krediter = 1 $), som kontoägaren anger: en total budget, en daglig budget (senaste 24 timmarna) eller båda. Innan en körning debiteras kontrolleras kostnaden mot vad nyckeln redan har spenderat via detta API (netto efter återbetalningar). En körning som skulle överskrida gränsen nekas med `402 budget_exceeded` och inget debiteras.

> [!IMPORTANT]
> Ett budgetavslag är slutgiltigt: ett nytt försök hjälper inte förrän ägaren höjer budgeten.

En nyckel utan budget kan spendera upp till API-saldot. Separat får en körning som API-saldot inte kan täcka `402 insufficient_credits` med en `top_up_url`.

`GET https://api.doitong.com/v1/account` visar API-saldot och nyckelns återstående budget (båda i API-krediter):

```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` är `null` när nyckeln inte har en egen budget.

## Hastighetsbegränsningar

Varje nyckel får göra 3600 begäranden per timme om inte gränsen har ställts in annorlunda. Varje autentiserat svar innehåller det aktuella tillståndet:

| Header | Betydelse |
|---|---|
| `X-RateLimit-Limit` | Antal begäranden som tillåts i det aktuella fönstret |
| `X-RateLimit-Remaining` | Antal begäranden som återstår i det aktuella fönstret |
| `X-RateLimit-Reset` | Unix-tid då fönstret återställs |

Över gränsen får du `429` med en `Retry-After`-header (sekunder). Lång polling med `?wait=` räknas som en begäran per anrop, så det är billigare att vänta än att polla ofta.

Det finns också en gräns på 10 pågående begäranden (`queued` eller `running`) per konto. Om du startar ytterligare en returneras `429 too_many_inflight`; starta den igen när en annan är klar.