# Hitelesítés

Minden olyan híváshoz, amely modellt futtat vagy beolvassa a kéréseidet, API-kulcs szükséges. A katalógus (`GET /models`, `GET /categories`), a `POST /quote` és az OpenAPI-dokumentum nyilvános.

## API-kulcsok

Kulcsokat itt hozhatsz létre és vonhatsz vissza: [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Egy kulcs a `doitong_` előtagból és 64 hexadecimális karakterből áll, és csak egyszer jelenik meg, létrehozásakor. Küldd el az `Authorization` fejlécben:

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

Az `X-API-Key: <key>` is működik.

> [!WARNING]
> A kulcsokat a szervereden tárold: bárki, aki rendelkezik egy kulccsal, elköltheti az általa elkölthető API-krediteket. Ha egy kulcs kiszivárog, vond vissza, és hozz létre újat.

A kulcs nélküli kérés `401` választ kap `missing_api_key` kóddal; az ismeretlen, visszavont vagy lejárt kulcs szintén `401` választ kap.

## Hatókörök

Minden kulcshoz hatókörök tartoznak. A modell API ezeket ellenőrzi:

| Művelet | Szükséges hatókör |
|---|---|
| Modell futtatása, kérés megszakítása, a kérés fájljainak törlése, a tárhelybeállítás módosítása | `models:run` (a régebbi `images:create` vagy `videos:create` hatókörrel rendelkező kulcsok is működnek) |
| Feltöltési URL létrehozása | `models:run` vagy `media:upload` |
| Kérések és fiók olvasása | `models:read` (a modelleket futtatni képes kulcsok olvasni is tudnak) |

Az új kulcsok alapértelmezés szerint `models:read` és `models:run` hatókört kapnak. A megfelelő hatókör nélküli hívás `403` választ kap `insufficient_scope` kóddal.

## Kreditkeretek

Egy kulcshoz saját API-kreditkeret tartozhat (1000 API-jóváírás = 1 $), amelyet a fiók tulajdonosa állít be: teljes keret, napi keret (az elmúlt 24 órára), vagy mindkettő. Mielőtt egy futtatást kiszámláznánk, a költséget összevetjük azzal, amit a kulcs már elköltött ezen az API-n keresztül (a visszatérítésekkel korrigálva). A keretet túllépő futtatást elutasítjuk `402 budget_exceeded` hibával, és nem számítunk fel díjat.

> [!IMPORTANT]
> A keret miatti elutasítás végleges: az újrapróbálkozás nem segít, amíg a tulajdonos meg nem emeli a keretet.

A keret nélküli kulcs legfeljebb az API-egyenleg erejéig költhet. Ettől függetlenül, ha az API-egyenleg nem fedezi a futtatást, `402 insufficient_credits` választ kapsz egy `top_up_url` értékkel.

A `GET https://api.doitong.com/v1/account` megjeleníti az API-egyenleget és a kulcshoz fennmaradó keretet (mindkettőt API-kreditekben):

```json 200 OK · fiók
{
  "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_..."
}
```

A `budget_remaining` értéke `null`, ha a kulcsnak nincs saját kerete.

## Sebességkorlátok

Minden kulcs óránként 3600 kérést indíthat, kivéve, ha a korlátot ettől eltérően állították be. Minden hitelesített válasz tartalmazza az aktuális állapotot:

| Fejléc | Jelentés |
|---|---|
| `X-RateLimit-Limit` | Az aktuális időablakban engedélyezett kérések |
| `X-RateLimit-Remaining` | Az aktuális időablakban fennmaradó kérések |
| `X-RateLimit-Reset` | Az időablak alaphelyzetbe állításának Unix-ideje |

A korlát túllépésekor `429` választ kapsz egy `Retry-After` fejléccel (másodperc). A `?wait=` paraméterrel végzett hosszú lekérdezés hívásonként egy kérésnek számít, ezért a várakozás olcsóbb, mint a gyakori lekérdezés.

Fiókonként emellett legfeljebb 10 folyamatban lévő kérés lehet (`queued` vagy `running`). Egy további indítása `429 too_many_inflight` választ ad; indítsd újra, miután egy befejeződött.