Limiti di velocità dell'API di generazione immagini spiegati: cosa aspettarsi e come HiAPI gestisce i picchi di traffico

Cosa significa davvero "limite di velocità" nelle API di immagini

Quando una richiesta di generazione immagini fallisce con HTTP 429, o il tuo job batch si blocca sempre esattamente allo stesso numero di concorrenza, stai incontrando un limite di velocità — non un bug. Tutte le API di immagini di livello produttivo limitano il traffico lungo almeno una di tre dimensioni, e capire queste differenze è fondamentale per il debug:

• RPM (richieste al minuto) — il numero di chiamate POST che puoi effettuare in una finestra scorrevole di 60 secondi. Tollerante verso i picchi, si ripristina rapidamente.
• RPD (richieste al giorno) — il tetto giornaliero, di solito legato al tuo livello di piano. Si azzera a mezzanotte UTC (o al giorno di fatturazione del tuo account).
• Concorrenza / attività in corso — il numero di attività di immagine che possono essere eseguite contemporaneamente. Anche con RPM nella norma, la quinta attività in corso verrà messa in coda o rifiutata.

Nello specifico della generazione immagini, il collo di bottiglia è quasi sempre la concorrenza, non gli RPM — una singola attività 1024×1024 può richiedere da 8 a 30 secondi end-to-end, quindi 10 attività in parallelo ≠ 10 RPM. Confondere queste due cose è la causa più comune di "i miei retry peggiorano la situazione".

Cause comuni ordinate per frequenza

1. Il tuo parallelismo supera il limite di concorrenza.La causa più probabile. Il tuo ciclo invia 50 chiamate POST /v1/tasks in una volta, il provider accetta le prime N, il resto restituisce 429. Il limite di concorrenza della maggior parte dei provider non è documentato per singola chiave — si deduce dal tuo livello.
2. Tempesta di retry dopo errori transitori.Un'attività che restituisce 5xx attiva immediatamente un retry, tutte le altre attività in corso fanno lo stesso, e la tua concorrenza effettiva raddoppia in un secondo.
3. Limite RPM per modello che non conosci.Una chiave generica di livello alto può comunque essere limitata lungo la dimensione modello, soprattutto per modelli nuovi o avanzati. Chiamare gpt-image-2 e flux-1-pro con la stessa chiave non significa che condividano una quota.
4. Quota giornaliera esaurita a metà giornata.Meno comune ma più confuso — le tue richieste funzionano, poi iniziano a fallire ogni giorno alla stessa ora precise. È sempre l'RPD.
5. Vicini rumorosi su sottaccount condivisi.Se configuri chiavi per ambiente ma condividono un account di fatturazione, il traffico di staging consuma la quota di produzione.

Passaggi di correzione

Esegui i seguenti passaggi in ordine. Ogni passaggio isola una dimensione diversa.

1. Leggi il corpo della risposta di errore, non solo il codice di stato.Un vero 429 da HiAPI assomiglia a questo:

   {
     "error": {
       "code": "rate_limit_exceeded",
       "type": "hiapi_error",
       "request_id": "req_01HXXXXXXXXXXXXXXX"
     }
   }
   

   Annota il request_id. È l'unica informazione che permette al team di supporto di tracciare esattamente quale limite hai attivato.

2. Distingui 429 da 401.Un 401 con {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} non è un limite di velocità — è un fallimento di autenticazione o permessi. Non aggiungere backoff per i 401; non diventerà mai 200, indipendentemente da quanto aspetti.

3. Limita prima la concorrenza lato client, poi il numero di retry.Un semplice semaforo è sufficiente:

   import asyncio, httpx
   sem = asyncio.Semaphore(4)  # allinea questo valore al limite di concorrenza del provider
   
   async def submit(client, payload):
       async with sem:
           return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)
   

   Parti da 4. Alza solo dopo che un intero batch è stato eseguito senza un solo 429.

4. Usa un backoff esponenziale con jitter completo solo sui 429.

   import asyncio, random
   async def backoff(attempt):
       # 1s, 2s, 4s, 8s, tetto 30s, randomizzato per evitare il thundering herd
       delay = min(30, 2 ** attempt) * random.random()
       await asyncio.sleep(delay)
   

   Imposta il limite di retry a 5. Dopo, esponi il fallimento — non riprovare all'infinito.

5. Rispetta Retry-After quando presente.Se la risposta include l'header Retry-After, il provider ti sta dicendo esplicitamente quando la finestra si azzera. Quel retry deve usarlo, non il valore di backoff calcolato da te.

6. Separa le chiavi per ambiente.Se staging e produzione condividono una chiave, condividono anche il limite di concorrenza. Una chiave per ambiente + una chiave per pool di lavoro ad alto traffico è il modo più economico per risolvere "il limite sembra più basso di quanto dice la documentazione".

Come HiAPI gestisce i picchi di traffico

HiAPI espone un endpoint POST /v1/tasks che accetta la tua attività e restituisce immediatamente l'id dell'attività, poi interroghi lo stato di completamento. Questa separazione è importante per il calcolo dei limiti di velocità: la chiamata di creazione è economica e breve, quindi il limite RPM è permissivo; il lavoro pesante è controllato dalla concorrenza lato modello, che è dove dovrebbe stare. Quando il provider a valle è congestionato, la chiamata di creazione riesce comunque — la tua attività semplicemente attende in coda, e GET /v1/tasks/{id} restituisce status: "queued" finché non si libera uno slot. Non vedrai mai 429 per la pressione transitoria a valle; lo vedrai solo quando tu superi la quota della tua chiave.

Questo è il motivo pratico per cui i team migrano da un'integrazione diretta con il provider a HiAPI quando il carico di lavoro delle immagini supera la capacità di un singolo account: una chiave Bearer, un budget di limiti di velocità ragionabile, e i picchi assorbiti dalla coda invece che dal tuo ciclo di retry.

Esempio minimo di verifica

Usalo per confermare che la tua chiave funziona e che l'impostazione di concorrenza è ragionevole. Invia un'attività di immagine a gpt-image-2 e stampa l'id dell'attività:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "una singola mela rossa su un tavolo di legno, luce diurna soffusa",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Risposta attesa:

• 200 con {"id":"task_...","status":"queued"} → la chiave è valida, la quota è a posto.
• 429 con {"error":{"code":"rate_limit_exceeded",...}} → hai superato il limite RPM, RPD o di concorrenza. Rallenta seguendo i passaggi di correzione sopra.
• 401 con {"error":{"code":"permission_denied",...}} → fallimento di autenticazione, non limite di velocità. Controlla la tua chiave.

Ripeti questa chiamata con un rapido ciclo seq 1 10 | xargs -n1 -P10 curl ... per trovare il tuo limite di concorrenza — il primo che restituisce 429 segna il tuo limite effettivo.

Letture correlate

• Diagnosi di attività HiAPI in sospeso e timeout— quando un'attività rimane nello stato queued o processing più del previsto.
• Perché il callback della tua attività HiAPI non si attiva— risoluzione dei problemi dei callback asincroni nel flusso /v1/tasks.
• Risolvere l'errore model_not_available— una categoria di errore adiacente, spesso fraintesa come limite di velocità.
• Catalogo modelli— prezzi per modello e tipi di endpoint.
• Prezzi— dettaglio per livello.

Domande frequenti

Esistono valori RPM pubblici per gpt-image-2 su HiAPI? I limiti dipendono dal livello e possono cambiare man mano che i provider adeguano i propri tetti. Controlla la tua dashboard per i limiti effettivi correnti invece di codificare a mano i numeri di un articolo di blog.

Perché i retry a volte peggiorano il 429? Usare ingenuamente sleep(1) su N worker paralleli trasforma un 429 in N retry sincronizzati che colpiscono tutti di nuovo. Usa il jitter completo (sleep * random.random()), non un ritardo fisso.

HiAPI addebita le risposte 429? No. Le creazioni di attività fallite (429, 401, 4xx generici) non vengono fatturate. Paghi solo per le attività che producono output con successo.

Aumentare la concorrenza lato client aumenta il mio limite? No. Il limite di concorrenza è impostato dal lato server per chiave. Il parallelismo lato client determina solo se rimani sotto il limite o lo attivi.

Qual è la differenza tra RPM e TPM? Le API di immagini limitano per richiesta (RPM), non per token (TPM) — le attività di immagine non hanno un'unità "token" significativa. Se vedi un limite TPM nella tua dashboard, si applica agli endpoint di testo/chat, non alle attività di immagine /v1/tasks.

Dovrei usare una chiave ad alta concorrenza o più chiavi a bassa concorrenza? Per i carichi di lavoro delle immagini, una chiave per pool logico di lavoro è il modello mentale più semplice. Più chiavi sotto un account di fatturazione in realtà non moltiplicano la tua quota — la condividono.

Posso richiedere un limite di concorrenza più alto? Sì — una volta che hai dimostrato un uso costante nel tuo livello attuale. Fornisci al team di supporto il request_id di un 429 rappresentativo, e possono tracciare quale dimensione stai colpendo.

Perché non vedo l'header Retry-After? Non tutti i provider lo inviano. Quando manca, usa il backoff esponenziale con jitter a partire da 1s. Quando è presente, quel retry dovrebbe fidarsi di esso.