Limiti di frequenza

Due limiti mantengono prevedibile la latenza per tutti: un limite di frequenza delle richieste alle chiamate autenticate e un limite di concorrenza alle generazioni in esecuzione contemporaneamente. Oltre la frequenza delle richieste, la chiamata riceve 429 rate_limited e non viene addebitato nulla. Oltre il limite di concorrenza, nulla viene rifiutato: la generazione attende nella coda del tuo account e parte appena una delle tue termina.

Limiti predefiniti#

Il limite di richieste usa un token bucket: puoi inviare fino a 20 richieste alla volta e la capacità si ricarica a 10 al secondo. Il traffico costante sotto 10 richieste al secondo non viene mai limitato.

La coda#

• Una generazione oltre il tuo limite di concorrenza viene accettata come sempre: ricevi subito il suo id, l'importo viene bloccato e lo stato è queued. Parte da sola appena una delle tue generazioni termina, a partire dalla più vecchia.
• L'attesa non conta per il limite di tempo di una generazione: una generazione in coda non fallisce né scade mai perché attende.
• Una generazione ancora in attesa nella tua coda può essere annullata (POST /generations/{id}/cancel) o eliminata in qualsiasi momento, e l'importo bloccato viene rimborsato subito. Una volta partita, valgono le normali regole di annullamento.
• La tua coda contiene fino a 10 × il tuo limite di concorrenza (200 per un account nuovo). Oltre, la richiesta riceve 429 rate_limited e non viene creato né addebitato nulla.
• Ogni account ha la propria coda e le generazioni in attesa non occupano capacità: una coda lunga non rallenta mai le generazioni di altri account.

Vedere i tuoi limiti#

La tabella mostra i valori predefiniti. I limiti del tuo account, e quante sue generazioni sono in corso, sono in Dashboard → Impostazioni e nel campo limits di GET /api/v1/account (e dello strumento MCP get_account):

{
  "object": "account",
  "balance_usd": 42.5,
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

concurrent_generations indica quante generazioni possono essere in esecuzione contemporaneamente (le altre attendono nella tua coda) e in_flight quante sono in corso ora, comprese quelle in coda; requests_per_second e burst sono la frequenza delle richieste e il picco, per l'account e per ciascuna delle sue chiavi API.

Quando raggiungi un limite#

{
  "error": {
    "code": "rate_limited",
    "message": "Your queue is full: 200 generations are already waiting for your 20 concurrent slots (up to 200 can wait). Nothing was submitted or charged. Retry when some have finished (webhook_url tells you when), or cancel queued ones; GET /api/v1/account shows your limits. For a higher limit, contact us: contact@cheapergen.com."
  }
}

Ogni 429 include un header Retry-After (secondi di attesa). Se è stato raggiunto un limite, il messaggio lo indica; se la tua coda è piena, indica anche quante generazioni sono in attesa.

• Frequenza delle richieste: attendi un attimo e riprova con backoff esponenziale e jitter (parti da circa un secondo). Consulta Riprovare in sicurezza.
• Coda piena: il 429 per concorrenza arriva solo quando la tua coda è piena. Attendi che alcune generazioni terminino (un webhook_url ti avvisa) o annulla quelle in coda, poi inviane altre.

Resta entro i limiti#

Usa i webhook invece di controllare lo stato di continuo#

Interrogare decine di job ogni secondo esaurisce rapidamente il budget di richieste. Passa webhook_url e lascia che ti contattiamo noi — vedi Webhook. Se usi il polling, per i video aumenta l’intervallo a 5–10 secondi.

Metti in coda le richieste sul tuo sistema#

I picchi brevi non sono un problema: la tua coda li assorbe. Per lotti più grandi della tua coda, tieni l'arretrato dalla tua parte e invia man mano che le generazioni terminano (i webhook ti avvisano), così non riceverai mai il 429 di coda piena.

Una chiave condivisa per servizio#

La frequenza delle richieste si conteggia per chiave, mentre la concorrenza si conteggia per account. Distribuire il traffico su più chiavi non aumenta il numero di generazioni che puoi eseguire contemporaneamente.