# Authentifikatioun

All Ufro, déi e Modell ausféiert oder Är Ufroe liest, brauch en API-Schlëssel. De Katalog (`GET /models`, `GET /categories`), `POST /quote` an d'OpenAPI-Dokument sinn ëffentlech.

## API-Schlësselen

Erstellt a réckelt Schlësselen op [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). E Schlëssel gesäit aus wéi `doitong_` gefollegt vu 64 hexadezimale Zeechen a gëtt nëmmen eemol ugewisen, wann Dir en erstellt. Schéckt en am `Authorization`-Header:

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

`X-API-Key: <key>` funktionéiert och.

> [!WARNING]
> Haalt d'Schlësselen op Ärem Server: Jiddereen, deen e Schlëssel huet, kann d'API-Kreditter ausginn, déi en ausginn däerf. Wann e Schlëssel ausgelaf ass, réckelt en a erstellt en neien.

Eng Ufro ouni Schlëssel kritt `401` mam Code `missing_api_key`; en onbekannten, réckelten oder ofgelafene Schlëssel kritt och `401`.

## Beräicher

All Schlëssel huet Beräicher. D'Modell-API kontrolléiert dës:

| Aktioun | Néidege Beräich |
|---|---|
| E Modell ausféieren, eng Ufro annuléieren, d'Dateie vun enger Ufro läschen, d'Astellung vun der Späicherung änneren | `models:run` (Schlëssele mat dem eeleren `images:create` oder `videos:create` funktionéieren och) |
| Eng Upload-URL erstellen | `models:run` oder `media:upload` |
| Ufroen a Kont liesen | `models:read` (e Schlëssel, dee Modeller ausféiere kann, ka se och liesen) |

Nei Schlëssele kréien `models:read` an `models:run` als Standard. Eng Ufro ouni de richtege Beräich kritt `403` mam Code `insufficient_scope`.

## Kreditbudgeten

E Schlëssel kann säin eegene Budget an API-Kreditter hunn (1.000 API-Kreditter = 1 $), vum Kontbesëtzer festgeluecht: e Gesamtbudget, en deegleche Budget (déi lescht 24 Stonnen), oder béides. Ier e Laf verrechent gëtt, gëtt de Käschtepunkt mat deem verglach, wat de Schlëssel bis elo iwwer dës API ausginn huet (netto no Remboursementer). E Laf, deen dëse Betrag iwwerschreide géif, gëtt mat `402 budget_exceeded` refuséiert an et gëtt näischt verrechent.

> [!IMPORTANT]
> Eng Budget-Refus ass definitiv: E Retry hëlleft net, bis de Besëtzer de Budget erhéicht.

 E Schlëssel ouni Budget kann bis zum API-Saldo ausginn. Separat kritt e Laf, deen den API-Saldo net ofdecke kann, `402 insufficient_credits` mat enger `top_up_url`.

`GET https://api.doitong.com/v1/account` weist den API-Saldo an de verbleiwende Budget vum Schlëssel (béid an API-Kreditter):

```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` ass `null`, wann de Schlëssel keen eegene Budget huet.

## Rate-Limiten

All Schlëssel däerf 3600 Ufroen pro Stonn maachen, ausser seng Limit gouf anescht festgeluecht. All authentifizéiert Äntwert enthält den aktuelle Status:

| Header | Bedeitung |
|---|---|
| `X-RateLimit-Limit` | Ufroen, déi an der aktueller Fënster erlaabt sinn |
| `X-RateLimit-Remaining` | Ufroen, déi an der aktueller Fënster iwwreg sinn |
| `X-RateLimit-Reset` | Unix-Zäit, zu där d'Fënster zréckgesat gëtt |

Iwwer der Limit kritt Dir `429` mat engem `Retry-After`-Header (Sekonnen). Laangt Polling mat `?wait=` zielt als eng Ufro pro Opruff, dofir ass Waarden méi bëlleg wéi séier ze pollen.

Et gëtt och eng Limit vun 10 Ufroen, déi pro Kont amgaang sinn (`queued` oder `running`). Eng weider ze starten gëtt `429 too_many_inflight` zeréck; start se nach eng Kéier, nodeems eng fäerdeg ass.