Tutoriel

Limites de débit de l'API de génération d'images expliquées : à quoi s'attendre et comment HiAPI absorbe les pics de trafic

Jun 28, 2026

Ce que signifie réellement « limite de débit » dans une API d'images

Lorsqu'une requête de génération d'images échoue avec HTTP 429, ou que votre traitement par lots se bloque systématiquement au même niveau de concurrence, vous êtes confronté à une limite de débit — pas à un bug. Toutes les API d'images de niveau production limitent le trafic selon au moins l'une de ces trois dimensions, et comprendre ces différences est essentiel pour le débogage :

RPM (requêtes par minute) — le nombre d'appels POST que vous pouvez émettre sur une fenêtre glissante de 60 secondes. Tolérant aux pics, récupération rapide.
RPD (requêtes par jour) — plafond quotidien, généralement lié à votre niveau d'abonnement. Réinitialisé à minuit UTC (ou au jour de facturation de votre compte).
Concurrence / tâches en cours — le nombre de tâches d'image pouvant tourner simultanément. Même si le RPM est respecté, une 5e tâche en cours sera mise en file d'attente ou rejetée.

Dans le cas précis de la génération d'images, le goulot d'étranglement est presque toujours la concurrence, pas le RPM — une seule tâche 1024×1024 peut prendre de 8 à 30 secondes de bout en bout, donc 10 tâches parallèles ≠ 10 RPM. Confondre les deux est la cause la plus fréquente du « mes nouvelles tentatives aggravent la situation ».

Causes courantes classées par probabilité

Votre parallélisme dépasse le plafond de concurrence. La cause la plus probable. Votre boucle émet 50 appels POST /v1/tasks d'un coup, le fournisseur accepte les N premiers et renvoie 429 pour les autres. Les plafonds de concurrence de la plupart des fournisseurs ne sont pas documentés par clé — ils se déduisent de votre niveau.
Tempête de nouvelles tentatives après une erreur transitoire. Une tâche qui renvoie une 5xx déclenche immédiatement une nouvelle tentative, toutes les autres tâches en cours font de même, et votre concurrence effective double en une seconde.
Plafond RPM par modèle que vous ignorez. Une clé universelle de niveau tier élevé peut rester soumise à une limite propre au modèle, surtout pour les modèles récents ou avancés. Appeler gpt-image-2 et flux-1-pro avec la même clé ne signifie pas qu'ils partagent un quota.
Quota quotidien épuisé en milieu de journée. Moins fréquent mais très déroutant — vos requêtes fonctionnent, puis échouent chaque jour à la même heure d'horloge. C'est toujours le RPD.
Voisins bruyants sur un sous-compte partagé. Si vous avez configuré des clés par environnement mais qu'elles partagent un compte de facturation, le trafic de préproduction consomme le quota de production.

Étapes de résolution

Suivez ces étapes dans l'ordre. Chacune isole une dimension différente.

Lisez le corps de la réponse d'erreur, pas seulement le code de statut. Un vrai 429 de HiAPI ressemble à ceci :
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
Notez le request_id. C'est la seule information qui permet au support de tracer précisément la limite que vous avez déclenchée.
Distinguez le 429 du 401. Un 401 accompagné de {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} n'est pas une limite de débit — c'est un échec d'authentification ou de permission. N'ajoutez pas de temporisation sur un 401 ; il ne deviendra jamais un 200, quelle que soit la durée d'attente.

Limitez d'abord la concurrence côté client, puis le nombre de nouvelles tentatives. Un simple sémaphore suffit :

import asyncio, httpx
sem = asyncio.Semaphore(4)  # Faites correspondre cette valeur au plafond de concurrence du fournisseur

async def submit(client, payload):
    async with sem:
        return await client.post("https://api.hiapi.ai/v1/tasks", json=payload)

Commencez par 4. N'augmentez qu'une fois qu'un lot complet s'exécute sans aucun 429.

N'utilisez une temporisation exponentielle avec gigue complète qu'en cas de 429.

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s, plafond à 30s, randomisation pour éviter l'effet de troupeau
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

Limitez les nouvelles tentatives à 5. Au-delà, exposez l'échec — ne réessayez pas indéfiniment.

Respectez l'en-tête Retry-After lorsqu'il est présent. Si la réponse contient un en-tête Retry-After, le fournisseur vous indique explicitement quand la fenêtre se réinitialise. Cette nouvelle tentative doit l'utiliser, et non la valeur de temporisation que vous avez calculée.
Séparez les clés par environnement. Si la préproduction et la production partagent une clé, votre plafond de concurrence est aussi partagé. Une clé par environnement + une clé par pool de travail à fort trafic est la solution la moins coûteuse au problème « la limite semble plus basse que ce que dit la documentation ».

Comment HiAPI gère les pics de trafic

HiAPI expose en amont un point de terminaison POST /v1/tasks qui accepte votre tâche puis renvoie immédiatement l'identifiant de la tâche, après quoi vous interrogez l'état d'achèvement. Cette séparation est importante pour le calcul des limites de débit : l'appel de création est peu coûteux et rapide, donc la limite RPM est souple ; le travail lourd est contrôlé en concurrence du côté du modèle, là où il doit l'être. Lorsque le fournisseur en aval est encombré, l'appel de création réussit quand même — votre tâche attend simplement dans la file, et GET /v1/tasks/{id} renvoie status: "queued" jusqu'à ce qu'un slot se libère. Vous ne voyez jamais de 429 à cause d'une pression transitoire en aval ; uniquement lorsque vous dépassez le quota de votre propre clé.

C'est la raison concrète pour laquelle les équipes migrent vers HiAPI depuis une intégration directe au fournisseur lorsque leur charge de travail d'images dépasse la capacité d'un seul compte : une seule clé Bearer, un budget de limite de débit prévisible, et les pics absorbés par la file d'attente plutôt que par votre boucle de nouvelles tentatives.

Exemple de vérification minimal

Utilisez ceci pour confirmer que votre clé fonctionne et que votre configuration de concurrence est raisonnable. Il soumet une tâche d'image à gpt-image-2 et affiche l'identifiant de la tâche :

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": "a single red apple on a wooden table, soft daylight",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Réponse attendue :

200 avec {"id":"task_...","status":"queued"} → clé valide, quota OK.
429 avec {"error":{"code":"rate_limit_exceeded",...}} → vous avez dépassé la limite RPM, RPD ou de concurrence. Ralentissez en suivant les étapes de résolution ci-dessus.
401 avec {"error":{"code":"permission_denied",...}} → échec d'authentification, pas une limite de débit. Vérifiez votre clé.

Répétez cet appel avec une boucle rapide seq 1 10 | xargs -n1 -P10 curl ... pour trouver votre plafond de concurrence — le premier qui renvoie 429 marque votre plafond effectif.

Pour aller plus loin

Diagnostic des tâches HiAPI bloquées et des délais d'attente — lorsque des tâches restent dans l'état queued ou processing plus longtemps que prévu.
Pourquoi le rappel de votre tâche HiAPI ne se déclenche pas — dépannage des rappels asynchrones du flux /v1/tasks.
Résoudre l'erreur model_not_available — catégorie d'erreur voisine, souvent mal interprétée comme une limite de débit.
Catalogue de modèles — tarification par modèle et types de points de terminaison.
Tarification — détail niveau par niveau.

Questions fréquentes

Existe-t-il une valeur RPM publique pour gpt-image-2 sur HiAPI ? Les limites dépendent du niveau et peuvent évoluer à mesure que les fournisseurs ajustent leurs propres plafonds. Consultez votre tableau de bord pour connaître les limites effectives actuelles, plutôt que de coder en dur les chiffres d'un article de blog.

Pourquoi les nouvelles tentatives aggravent-elles parfois le 429 ? Une nouvelle tentative naïve avec sleep(1) sur N workers parallèles transforme un 429 en N nouvelles tentatives synchronisées, qui échouent toutes à nouveau. Utilisez une gigue complète (sleep * random.random()) plutôt qu'un délai fixe.

HiAPI facture-t-il les réponses 429 ? Non. Les créations de tâches échouées (429, 401, 4xx génériques) ne sont pas facturées. Vous ne payez que pour les tâches qui produisent une sortie avec succès.

Augmenter la concurrence côté client peut-il relever mon plafond ? Non. Le plafond de concurrence est défini côté serveur par clé. Le parallélisme côté client détermine seulement si vous restez sous le plafond ou si vous le déclenchez.

Quelle est la différence entre RPM et TPM ? Les API d'images sont limitées par requête (RPM), pas par token (TPM) — les tâches d'image n'ont pas d'unité « token » significative. Si vous voyez une limite TPM dans votre tableau de bord, elle s'applique aux points de terminaison texte/chat, pas aux tâches d'image /v1/tasks.

Dois-je utiliser une clé à haute concurrence ou plusieurs clés à faible concurrence ? Pour les charges de travail d'images, une clé par pool de travail logique est le modèle mental le plus simple. Plusieurs clés sous un même compte de facturation ne multiplient pas réellement votre quota — elles le partagent.

Puis-je demander un plafond de concurrence plus élevé ? Oui — une fois que vous avez démontré une utilisation régulière sur votre niveau actuel. Fournissez au support le request_id d'un 429 représentatif, et ils pourront tracer la dimension que vous avez atteinte.

Pourquoi ne vois-je pas l'en-tête Retry-After ? Tous les fournisseurs ne l'envoient pas. S'il est absent, revenez à une temporisation exponentielle avec gigue démarrant à 1s. S'il est présent, cette nouvelle tentative doit lui faire confiance.