Tutorial

Detaillierte Erklärung der Ratenbegrenzungen der Bildgenerierungs-API: Was Sie erwartet und wie HiAPI mit Lastspitzen umgeht

Jun 28, 2026

Was „Ratenbegrenzung“ in Bild-APIs wirklich bedeutet

Wenn ein Bildgenerierungs-Request mit HTTP 429 fehlschlägt oder Ihr Batch-Job jedes Mal bei exakt derselben Parallelität hängen bleibt, stoßen Sie auf eine Ratenbegrenzung – und nicht auf einen Bug. Jede produktionsreife Bild-API begrenzt den Verkehr in mindestens einer von drei Dimensionen, und das Verständnis dieser Unterschiede ist für die Fehlersuche entscheidend:

RPM (Requests pro Minute) – die Anzahl der POST-Aufrufe, die in einem rollierenden 60-Sekunden-Fenster gesendet werden können. Freundlich gegenüber Lastspitzen, schnelle Erholung.
RPD (Requests pro Tag) – ein Tageslimit, das normalerweise an Ihre Tarifstufe gebunden ist. Wird um UTC-Mitternacht (oder am Abrechnungstag Ihres Kontos) zurückgesetzt.
Parallelität / laufende Aufgaben – die Anzahl der Bildaufgaben, die gleichzeitig ausgeführt werden können. Selbst wenn die RPM in Ordnung ist, wird die fünfte laufende Aufgabe in die Warteschlange gestellt oder abgelehnt.

Speziell bei der Bildgenerierung ist der Engpass fast immer die Parallelität und nicht die RPM – eine einzelne 1024×1024-Aufgabe kann von Ende zu Ende 8–30 Sekunden dauern, also sind 10 parallele Aufgaben ≠ 10 RPM. Diese beiden zu verwechseln ist die häufigste Ursache für „meine Wiederholungsversuche machen es nur schlimmer“.

Häufige Ursachen nach Trefferwahrscheinlichkeit sortiert

Ihre Parallelität übersteigt das Parallelitätslimit. Die wahrscheinlichste Ursache. Ihre Schleife sendet auf einmal 50 POST /v1/tasks-Aufrufe, der Anbieter akzeptiert die ersten N und gibt für den Rest 429 zurück. Die Parallelitätslimits der meisten Anbieter werden nicht pro Schlüssel dokumentiert – sie werden aus Ihrer Stufe abgeleitet.
Eine Wiederholungsflut nach momentanen Fehlern. Eine Aufgabe, die 5xx zurückgibt, löst sofort einen Wiederholungsversuch aus, alle anderen laufenden Aufgaben tun dasselbe, und Ihre effektive Parallelität verdoppelt sich innerhalb einer Sekunde.
Ein modellspezifisches RPM-Limit, das Sie nicht kennen. Ein universeller Schlüssel einer hohen Stufe kann dennoch durch die Modell-Dimension begrenzt sein, insbesondere bei neuen oder Premium-Modellen. gpt-image-2 und flux-1-pro mit demselben Schlüssel aufzurufen bedeutet nicht, dass sie sich ein Kontingent teilen.
Das Tageskontingent ist mittags erschöpft. Weniger verbreitet, aber am verwirrendsten – Ihre Anfragen funktionieren, und dann beginnen sie jeden Tag zur selben Uhrzeit zu fehlschlagen. Es ist immer die RPD.
Störende Nachbarn auf einem gemeinsam genutzten Unterkonto. Wenn Sie Schlüssel pro Umgebung bereitstellen, diese aber ein Abrechnungskonto teilen, frisst der Staging-Verkehr das Produktionskontingent auf.

Schritte zur Behebung

Führen Sie die folgenden Schritte der Reihe nach aus. Jeder Schritt isoliert eine andere Dimension.

Lesen Sie den Fehler-Response-Body, nicht nur den Statuscode. Ein echter 429 von HiAPI sieht so aus:
```
{
  "error": {
    "code": "rate_limit_exceeded",
    "type": "hiapi_error",
    "request_id": "req_01HXXXXXXXXXXXXXXX"
  }
}
```
Notieren Sie die request_id. Dies ist die einzige Information, mit der das Support-Team genau nachverfolgen kann, welches Limit Sie ausgelöst haben.
Unterscheiden Sie 429 von 401. Ein 401 mit {"error":{"code":"permission_denied","type":"hiapi_error","request_id":...}} ist keine Ratenbegrenzung – sondern ein Authentifizierungs- oder Berechtigungsfehler. Fügen Sie bei 401 keinen Backoff hinzu; egal wie lange Sie warten, es wird nicht zu 200 werden.

Begrenzen Sie zuerst die Client-Parallelität und dann die Anzahl der Wiederholungsversuche. Ein einfaches Semaphor genügt:

import asyncio, httpx
sem = asyncio.Semaphore(4)  # Passen Sie diesen Wert an das Parallelitätslimit des Anbieters an

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

Beginnen Sie mit 4. Erhöhen Sie den Wert erst, wenn ein ganzer Batch von Aufgaben läuft, ohne dass ein einziges Mal 429 auftritt.

Verwenden Sie exponentielles Backoff mit vollständigem Jitter nur bei 429.

import asyncio, random
async def backoff(attempt):
    # 1s, 2s, 4s, 8s, Obergrenze 30s, randomisiert, um einen Herdeffekt zu vermeiden
    delay = min(30, 2 ** attempt) * random.random()
    await asyncio.sleep(delay)

Setzen Sie die Anzahl der Wiederholungsversuche auf höchstens 5. Danach den Fehler offenlegen – nicht endlos wiederholen.

Befolgen Sie Retry-After, wenn es vorhanden ist. Wenn die Antwort einen Retry-After-Header enthält, teilt Ihnen der Anbieter ausdrücklich mit, wann das Fenster zurückgesetzt wird. Dieser eine Wiederholungsversuch sollte diesen Wert verwenden und nicht Ihr berechnetes Backoff.
Trennen Sie Schlüssel nach Umgebung. Wenn Staging und Produktion einen Schlüssel teilen, ist auch Ihr Parallelitätslimit geteilt. Ein Schlüssel pro Umgebung + ein Schlüssel pro stark ausgelastetem Arbeitspool ist die günstigste Methode, um „das Limit fühlt sich niedriger an als dokumentiert“ zu lösen.

Wie HiAPI mit Lastspitzen umgeht

HiAPI stellt einen POST /v1/tasks-Endpunkt voran, der Ihre Aufgabe annimmt, sofort eine Aufgaben-ID zurückgibt und Sie dann den Fertigstellungsstatus abfragen lässt. Diese Aufteilung ist für die Berechnung der Ratenbegrenzung wichtig: Der Erstellungsaufruf ist kostengünstig und kurz, daher sind die RPM-Limits großzügig; die rechenintensive Arbeit wird durch die Parallelitätskontrolle auf der Modellseite gesteuert, wo sie hingehört. Wenn der nachgelagerte Anbieter überlastet ist, ist der Erstellungsaufruf dennoch erfolgreich – Ihre Aufgabe wartet lediglich in der Warteschlange, und GET /v1/tasks/{id} gibt status: "queued" zurück, bis ein Slot frei wird. Sie sehen niemals 429 aufgrund von momentanem Druck stromabwärts; Sie sehen es nur, wenn Sie Ihr eigenes Schlüsselkontingent überschreiten.

Das ist der praktische Grund, warum Teams, deren Bild-Workload die Kapazität eines einzelnen Kontos übersteigt, von der direkten Anbieterintegration zu HiAPI wechseln: ein Bearer-Schlüssel, ein nachvollziehbares Ratenbegrenzungsbudget, und Lastspitzen werden von der Warteschlange absorbiert statt von Ihrer Wiederholungsschleife.

Minimales Verifizierungsbeispiel

Verwenden Sie dies, um zu bestätigen, dass Ihr Schlüssel funktioniert und Ihre Parallelitätseinstellung sinnvoll ist. Es sendet eine Bildaufgabe an gpt-image-2 und gibt die Aufgaben-ID aus:

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"
    }
  }'

Erwartete Antwort:

200 mit {"id":"task_...","status":"queued"} → Schlüssel in Ordnung, Kontingent in Ordnung.
429 mit {"error":{"code":"rate_limit_exceeded",...}} → Sie haben das RPM-, RPD- oder Parallelitätslimit überschritten. Verlangsamen Sie gemäß den oben genannten Behebungsschritten.
401 mit {"error":{"code":"permission_denied",...}} → Authentifizierungsfehler, keine Ratenbegrenzung. Überprüfen Sie Ihren Schlüssel.

Wiederholen Sie diesen Aufruf mit einer schnellen seq 1 10 | xargs -n1 -P10 curl ...-Schleife, um Ihr Parallelitätslimit zu finden – die erste zurückgegebene 429 markiert Ihr effektives Limit.

Häufig gestellte Fragen

Gibt es auf HiAPI öffentliche RPM-Werte für gpt-image-2? Limits sind stufenbasiert und können sich ändern, wenn Anbieter ihre eigenen Limits anpassen. Prüfen Sie Ihr Dashboard auf die aktuell geltenden Limits, anstatt Zahlen aus Blogartikeln fest zu codieren.

Warum machen Wiederholungsversuche 429 manchmal schlimmer? Naives sleep(1)-Wiederholen auf N parallelen Workern verwandelt eine 429 in N synchrone Wiederholungsversuche, die alle erneut auf das Limit treffen. Verwenden Sie vollständigen Jitter (sleep * random.random()) statt einer festen Verzögerung.

Berechnet HiAPI für 429-Antworten? Nein. Fehlgeschlagene Aufgabenerstellungen (429, 401, allgemeine 4xx) werden nicht berechnet. Sie zahlen nur für Aufgaben, die erfolgreich Ausgaben erzeugen.

Kann eine Erhöhung der Client-Parallelität mein Limit erhöhen? Nein. Das Parallelitätslimit wird serverseitig pro Schlüssel festgelegt. Die Client-Parallelität bestimmt nur, ob Sie unter dem Limit bleiben oder es auslösen.

Was ist der Unterschied zwischen RPM und TPM? Bild-APIs werden nach Anfragen (RPM) begrenzt, nicht nach Tokens (TPM) – Bildaufgaben haben keine sinnvolle „Token“-Einheit. Wenn Sie in Ihrem Dashboard ein TPM-Limit sehen, gilt es für Text-/Chat-Endpunkte, nicht für /v1/tasks-Bildaufgaben.

Sollte ich einen Schlüssel mit hoher Parallelität oder mehrere Schlüssel mit niedriger Parallelität verwenden? Fügen Sie Bild-Workloads ist ein Schlüssel pro logischem Arbeitspool das einfachste mentale Modell. Mehrere Schlüssel unter einem Abrechnungskonto vervielfachen Ihr Kontingent nicht tatsächlich – sie teilen es.

Kann ich ein höheres Parallelitätslimit beantragen? Ja – sobald Sie bei Ihrer aktuellen Stufe eine kontinuierliche Nutzung nachgewiesen haben. Geben Sie dem Support-Team die request_id einer repräsentativen 429, und es kann nachverfolgen, welche Dimension Sie getroffen haben.

Warum sehe ich den Retry-After-Header nicht? Nicht alle Anbieter senden ihn. Wenn er fehlt, greifen Sie auf exponentielles Backoff mit Jitter zurück, beginnend bei 1s. Wenn er vorhanden ist, sollte dieser eine Wiederholungsversuch ihm vertrauen.