Limites de débit

Deux limites préservent des temps de réponse prévisibles pour tous : limite de débit des requêtes pour les requêtes authentifiées et concurrence pour les générations exécutées en même temps. Au-delà du débit, la requête reçoit 429 rate_limited et rien n’est facturé. Au-delà de la concurrence, rien n’est refusé : la génération attend dans la file de votre compte et démarre dès qu’une des vôtres se termine.

Limites par défaut#

La limite de requêtes repose sur un algorithme de seau à jetons : vous pouvez envoyer jusqu’à 20 requêtes d’un coup, et la capacité se recharge au rythme de 10 par seconde. Un trafic soutenu inférieur à 10 requêtes par seconde n’est jamais limité.

La file d’attente#

• Une génération au-delà de votre limite de concurrence est acceptée comme d’habitude : vous recevez son id immédiatement, son montant est réservé et son statut est queued. Elle démarre d’elle-même dès qu’une de vos générations se termine, la plus ancienne d’abord.
• L’attente ne compte pas dans la durée maximale d’une génération : une génération en file n’échoue jamais et n’expire jamais parce qu’elle attend.
• Une génération qui attend encore dans votre file peut être annulée (POST /generations/{id}/cancel) ou supprimée à tout moment, et son montant réservé est remboursé immédiatement. Une fois démarrée, les règles d’annulation habituelles s’appliquent.
• Votre file accepte jusqu’à 10 × votre limite de concurrence (200 pour un nouveau compte). Au-delà, la requête reçoit 429 rate_limited et rien n’est créé ni facturé.
• Chaque compte a sa propre file, et les générations en attente n’occupent aucune capacité : une longue file ne retarde jamais les générations des autres comptes.

Voir vos limites#

Le tableau indique les valeurs par défaut. Les limites de votre compte, et le nombre de ses générations en cours, figurent dans Tableau de bord → Paramètres et dans le champ limits de GET /api/v1/account (et de l'outil 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 indique combien de générations peuvent s'exécuter à la fois (les autres attendent dans votre file) et in_flight combien sont en cours actuellement, celles en file comprises ; requests_per_second et burst sont le débit de requêtes et le pic autorisé, pour le compte et pour chacune de ses clés d'API.

Lorsque vous atteignez une 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."
  }
}

Chaque 429 comporte un en-tête Retry-After (secondes d'attente). Si une limite a été atteinte, le message l'indique ; si votre file est pleine, il précise aussi combien de générations attendent.

• Débit des requêtes : Attendez brièvement, puis réessayez avec un délai exponentiel et une part d’aléatoire (environ une seconde au départ). Voir Réessayer sans risque.
• File pleine : le 429 lié à la concurrence n’arrive que lorsque votre file est pleine. Attendez que des générations se terminent (un webhook_url vous prévient) ou annulez celles en file, puis envoyez-en d’autres.

Rester sous les limites#

Utilisez les webhooks au lieu d’interroger en boucle#

Interroger des dizaines de tâches toutes les secondes épuise rapidement la limite de requêtes. Indiquez un webhook_url à l’envoi et laissez-nous vous prévenir — voir Webhooks. Si vous utilisez l’interrogation, espacez les requêtes vidéo de 5 à 10 secondes.

Mettez les envois en file d’attente de votre côté#

Les pics courts ne posent pas de problème : votre file les absorbe. Pour les lots plus grands que votre file, gardez le reste de votre côté et envoyez au fur et à mesure que les générations se terminent (les webhooks vous préviennent), afin de ne jamais recevoir le 429 de file pleine.

Une clé par service#

Le débit des requêtes est calculé par clé, mais la concurrence par compte. Répartir le trafic entre plusieurs clés n’augmente pas le nombre de générations exécutables simultanément.