Ratenbegrenzungen

Zwei Limits sorgen für vorhersehbare Latenz für alle: ein Anfragerate-Limit für authentifizierte Aufrufe und ein Parallelitätsgrenze-Limit für gleichzeitig laufende Generierungen. Über der Anfragerate erhält ein Aufruf 429 rate_limited, und es wird nichts berechnet. Über dem Parallelitätslimit wird nichts abgelehnt: Die Generierung wartet in der Warteschlange Ihres Kontos und startet, sobald eine Ihrer Generierungen fertig ist.

Standardlimits#

Die Anforderungsrate wird über einen Token-Bucket begrenzt: Sie können bis zu 20 Anfragen auf einmal senden; pro Sekunde werden 10 Tokens wieder aufgefüllt. Ein gleichmäßiger Datenverkehr unter 10 Anfragen pro Sekunde wird nie begrenzt.

Die Warteschlange#

• Eine Generierung über Ihrem Parallelitätslimit wird wie gewohnt angenommen: Sie erhalten sofort ihre id, der Preis wird reserviert und ihr Status ist queued. Sie startet von selbst, sobald eine Ihrer Generierungen fertig ist – die älteste zuerst.
• Die Wartezeit zählt nicht zum Zeitlimit einer Generierung: Eine wartende Generierung schlägt wegen des Wartens nie fehl und läuft nie ab.
• Eine Generierung, die noch in Ihrer Warteschlange wartet, können Sie jederzeit abbrechen (POST /generations/{id}/cancel) oder löschen; der reservierte Betrag wird sofort erstattet. Sobald sie gestartet ist, gelten die üblichen Regeln für das Abbrechen.
• Ihre Warteschlange fasst bis zu 10 × Ihr Parallelitätslimit (200 bei einem neuen Konto). Darüber erhält eine Anfrage 429 rate_limited, und es wird nichts angelegt oder berechnet.
• Jedes Konto hat seine eigene Warteschlange, und wartende Generierungen belegen keine Kapazität: Eine lange Warteschlange hält nie die Generierungen anderer Konten auf.

Ihre Limits ansehen#

Die Tabelle zeigt die Standardwerte. Die Limits Ihres Kontos und wie viele seiner Generierungen gerade laufen, finden Sie unter Dashboard → Einstellungen und im Feld limits von GET /api/v1/account (sowie des MCP-Tools 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 ist, wie viele Generierungen gleichzeitig laufen dürfen (weitere warten in Ihrer Warteschlange), und in_flight, wie viele gerade in Bearbeitung sind, wartende eingeschlossen; requests_per_second und burst sind Anfragerate und Spitze, für das Konto und für jeden seiner API-Schlüssel.

Wenn Sie ein Limit erreichen#

{
  "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."
  }
}

Jede 429-Antwort enthält einen Retry-After-Header (Wartezeit in Sekunden). Wurde ein Limit erreicht, nennt die Meldung es; ist Ihre Warteschlange voll, außerdem, wie viele Generierungen warten.

• Anfragerate: Warten Sie kurz und versuchen Sie es dann mit exponentiellem Backoff und Zufallsstreuung erneut (zunächst etwa eine Sekunde). Siehe Sicher erneut versuchen.
• Warteschlange voll: Das 429 wegen Parallelität kommt nur, wenn Ihre Warteschlange voll ist. Warten Sie, bis einige Generierungen fertig sind (eine webhook_url meldet es Ihnen), oder brechen Sie wartende ab, und senden Sie dann weitere.

Limits einhalten#

Webhooks statt häufiger Statusabfragen verwenden#

Wenn Sie Dutzende Aufträge jede Sekunde abfragen, ist Ihr Anfragelimit schnell aufgebraucht. Übergeben Sie stattdessen webhook_url, damit wir Sie benachrichtigen – siehe Webhooks. Bei Abfragen von Videos sollten Sie die Wartezeit auf 5–10 Sekunden erhöhen.

Aufträge in der eigenen Warteschlange verwalten#

Kurze Spitzen sind kein Problem: Ihre Warteschlange fängt sie ab. Bei Stapeln, die größer als Ihre Warteschlange sind, halten Sie den Rückstand auf Ihrer Seite und senden nach, sobald Generierungen fertig sind (Webhooks melden es Ihnen). So erhalten Sie nie das 429 einer vollen Warteschlange.

Einen Schlüssel pro Dienst verwenden#

Die Anfragerate wird pro Schlüssel gezählt, die Parallelität pro Konto. Mehrere Schlüssel erhöhen nicht die Zahl der gleichzeitig möglichen Generierungen.