# Autenticazione

Ogni chiamata che esegue un modello o legge le tue richieste necessita di una chiave API. Il catalogo (`GET /models`, `GET /categories`), `POST /quote` e il documento OpenAPI sono pubblici.

## Chiavi API

Crea e revoca le chiavi in [https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys). Una chiave è composta da `doitong_` seguito da 64 caratteri esadecimali e viene mostrata una sola volta, al momento della creazione. Inviala nell'intestazione `Authorization`:

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

Anche `X-API-Key: <key>` funziona.

> [!WARNING]
> Conserva le chiavi sul tuo server: chiunque possieda una chiave può spendere i crediti API che le sono consentiti. Se una chiave viene esposta, revocala e creane una nuova.

Una richiesta senza chiave restituisce `401` con il codice `missing_api_key`; anche una chiave sconosciuta, revocata o scaduta restituisce `401`.

## Ambiti

Ogni chiave contiene degli ambiti. L'API dei modelli verifica questi:

| Azione | Ambito richiesto |
|---|---|
| Eseguire un modello, annullare una richiesta, eliminare i file di una richiesta, modificare l'impostazione di archiviazione | `models:run` (funzionano anche le chiavi con il precedente `images:create` o `videos:create`) |
| Creare un URL di caricamento | `models:run` o `media:upload` |
| Leggere richieste e account | `models:read` (anche una chiave che può eseguire modelli può leggere) |

Le nuove chiavi ricevono `models:read` e `models:run` per impostazione predefinita. Una chiamata senza l'ambito corretto restituisce `403` con il codice `insufficient_scope`.

## Budget dei crediti

Una chiave può avere il proprio budget in crediti API (1000 crediti API = 1 $), impostato dal proprietario dell'account: un budget totale, un budget giornaliero (ultime 24 ore) o entrambi. Prima di addebitare un'esecuzione, il costo viene confrontato con quanto la chiave ha già speso tramite questa API (al netto dei rimborsi). Un'esecuzione che lo supererebbe viene rifiutata con `402 budget_exceeded` e non viene addebitato nulla.

> [!IMPORTANT]
> Il rifiuto per superamento del budget è definitivo: riprovare non servirà finché il proprietario non aumenterà il budget.

Una chiave senza budget può spendere fino al saldo API. Separatamente, un'esecuzione che il saldo API non può coprire restituisce `402 insufficient_credits` con un `top_up_url`.

`GET https://api.doitong.ru/v1/account` mostra il saldo API e il budget residuo della chiave (entrambi in crediti API):

```json 200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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` è `null` quando la chiave non ha un proprio budget.

## Limiti di frequenza

Ogni chiave può effettuare 3600 richieste all'ora, salvo diversa configurazione del limite. Ogni risposta autenticata contiene lo stato corrente:

| Intestazione | Significato |
|---|---|
| `X-RateLimit-Limit` | Richieste consentite nella finestra corrente |
| `X-RateLimit-Remaining` | Richieste rimanenti nella finestra corrente |
| `X-RateLimit-Reset` | Ora Unix in cui la finestra viene reimpostata |

Superato il limite, ricevi `429` con un'intestazione `Retry-After` (secondi). Il long polling con `?wait=` conta come una richiesta per chiamata, quindi aspettare costa meno che eseguire polling rapidamente.

Esiste inoltre un limite di 10 richieste in corso (`queued` o `running`) per account. Avviarne un'altra restituisce `429 too_many_inflight`; riavviala dopo che una è terminata.