Vai al contenuto
Italiano
Ottieni la chiave API
Guida all'API

Autenticazione

Visualizza come Markdown Aggiornato

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. Una chiave è composta da doitong_ seguito da 64 caratteri esadecimali e viene mostrata una sola volta, al momento della creazione. Inviala nell'intestazione Authorization:

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

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

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.

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.com/v1/account mostra il saldo API e il budget residuo della chiave (entrambi in crediti API):

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 è 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.