Rate-Limits der KI-Video-API erklärt: Multiplikatoren, Retries

Rate-Limits sind der Teil einer API, den du ignorierst – bis an einem Dienstagnachmittag ein Batch-Job und ein Produktlaunch in dieselbe Minute fallen und plötzlich alles 429 zurückgibt. Dann stellst du fest, dass deine Retry-Logik ein setTimeout von einer Sekunde in einer Schleife ist. Das ist kein Backoff – das ist derselbe Ansturm in etwas langsamerem Takt.

So berechnet eroq seine Limits, in der Reihenfolge, in der die Zahlen angewendet werden, und so schreibst du einen Client, der sich anständig verhält, wenn er an eines stößt.

Die Basis-Limits, pro Schlüssel, pro Minute

Drei Zahlen, gezählt pro API-Schlüssel über ein gleitendes Fenster von sechzig Sekunden:

• Chat – 60 Requests pro Minute. Gilt für POST /v1/chat/completions, mit oder ohne Streaming. Ein SSE-Stream zählt einmal, in dem Moment, in dem du ihn öffnest, nicht pro Token.
• Bilder – 20 Requests pro Minute. Ein Aufruf mit einem Batch aus vier Bildern zählt als ein Request.
• Video und Sprache – 6 Requests pro Minute, jeweils.

Sechs Video-Requests pro Minute wirken wenig, bis du dir klarmachst, was ein Video-Request ist: eine Einreichung, kein Render. POST /v1/videos/generations gibt sofort eine Job-ID zurück, und der Clip kommt Minuten später – sechs Einreichungen pro Minute sind also sechs neue Renders pro Minute, und das ist eine ordentliche Menge Produktionsarbeit. Die vollständige Endpunkt-Referenz steht unter /docs/video.

Achte auf die Einheit: pro Schlüssel, nicht pro Konto. Zwei Schlüssel sind zwei unabhängige Fenster. Genau das steckt hinter dem Rat, für jede Pipeline einen eigenen Schlüssel auszugeben – eine aus dem Ruder gelaufene Schleife im Staging drosselt dann nur das Staging.

Der Plan-Multiplikator

Ein aktiver Plan multipliziert jedes dieser Basis-Limits, und zwar für jeden Schlüssel im Workspace:

• Kein Plan und Hobby – 1×
• Creator – 2×
• Studio – 4×
• Team – 6×
• Agency – 8×

Video-Einreichungen steigen also von 6 pro Minute auf 24 bei Studio und 48 bei Agency, Chat von 60 auf 240 und 480. Die Zahl der Schlüssel wächst mit – 10 Schlüssel bei Hobby, 20 bei Creator, 50 bei Studio, 100 bei Team, 200 bei Agency –, die echte Obergrenze in einem großen Plan ist also der Multiplikator mal die Zahl der Schlüssel, die du zu betreiben bereit bist. Die Übersicht steht unter /pricing.

Der Anteil pro Mitglied, obendrauf

Innerhalb eines Workspace schränkt die Rolle eines Mitglieds ein, was seine Schlüssel bekommen. Entwickler und Admin erhalten das volle Kontingent des Plans; die Rolle Creator startet mit der Hälfte – nach dem Gedanken, dass interaktive Arbeit im Studio eine Produktions-Pipeline, die sich denselben Plan teilt, nicht aushungern können soll.

Ein Admin kann das pro Mitglied weiter einschränken, als Prozentwert, im Tab Mitglieder unter /dashboard/workspace. Diese Anpassung kann den Anteil der Rolle nur senken, nie über das hinaus anheben, was die Rolle gewährt.

Die Rechnung setzt sich in nur eine Richtung zusammen und ist deshalb leicht vorherzusagen – effektives Limit gleich Basis-Limit mal Plan-Multiplikator mal Anteil des Mitglieds:

effective limit = base cap × plan multiplier × member share

Ein Teammitglied mit der Rolle Creator in einem Studio-Plan, das den Video-Endpunkt aufruft:

6 × 4 × 0.5 = 12 video submissions per minute, per key

Also 12 Video-Einreichungen pro Minute und Schlüssel. Beschränkst du dieses Mitglied auf 25 %, bekommt es 6. Zwei Dinge passieren dabei nicht, und beides ist Absicht. Ein eingeschränkter Anteil drosselt nie die kostenlosen, rein lesenden Endpunkte – Jobs auflisten oder das Guthaben abfragen funktioniert weiterhin. Und ein Mitglied, das überhaupt nicht generieren darf, wird genau in dem Moment, in dem Credits fließen würden, mit einem klaren Berechtigungsfehler abgewiesen – nicht mit einer Flut rätselhafter 429er.

Wie ein 429 tatsächlich aussieht

Du bekommst den Status, einen Header Retry-After in Sekunden und einen Body, der den Bereich und das angewendete Limit nennt:

{
  "error": {
    "message": "Rate limit reached for video (24/min per key). Retry in 37s.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Der Header ist der nützliche Teil. Weil das Fenster gleitet, ist Retry-After keine feste Abkühlzeit – es ist die Zahl der Sekunden, bis der älteste Request in deinem aktuellen Fenster herausfällt und ein Platz frei wird. Genau so lange zu warten ist richtig; eine Sekunde zu warten und es dann noch einmal zu versuchen nicht.

Richtig mit Backoff arbeiten

Vier Regeln, nach Priorität geordnet.

1. Halte dich an Retry-After, wenn der Header da ist. Er wird aus dem tatsächlichen Fenster berechnet und schlägt damit jede Heuristik, die du dir ausdenkst.

2. Nutz exponentielles Backoff mit Jitter, wenn er fehlt. Reines Verdoppeln synchronisiert alle deine Clients wieder auf denselben Retry-Zeitpunkt. Full Jitter – eine zufällige Verzögerung zwischen null und der aktuellen Obergrenze – verteilt sie.

3. Wiederhole keine Fehler, die nicht vorübergehend sind. 402 insufficient_credits, 403 plan_required, 403 role_forbidden und eine Ablehnung mit content_blocked liefern in dreißig Sekunden exakt dieselbe Antwort. Zeig sie an. Ein 503 model_unavailable heißt, dass die Engine für dein Konto gerade nicht verfügbar ist – eine andere Engine aus /models ist dann die bessere Reaktion als eine Retry-Schleife.

4. Begrenze die Parallelität, statt immer wieder gegen eine Wand zu laufen. Ein Semaphor, der auf dein effektives Limit oder knapp darunter dimensioniert ist, macht aus Rate-Limiting eine Planungsfrage statt eines Fehlerpfads – und genau dort gehört es hin.

Hier das Ganze, klein genug zum Einfügen:

const sleep = ms => new Promise(r => setTimeout(r, ms))

async function submitVideo(body, { attempts = 5 } = {}) {
  let delay = 1000
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const res = await fetch('https://eroq.ai/v1/videos/generations', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    })

    if (res.ok) return res.json()          // 202 with a job id
    if (res.status !== 429) {              // 402/403/503 are not transient
      throw new Error(`${res.status} ${(await res.json()).error?.code}`)
    }

    const header = Number(res.headers.get('retry-after'))
    const wait = Number.isFinite(header) && header > 0
      ? header * 1000
      : Math.random() * delay              // full jitter
    await sleep(wait)
    delay = Math.min(delay * 2, 30_000)
  }
  throw new Error('rate limited after all attempts')
}

Fünf Versuche sind eine vernünftige Obergrenze für einen Pfad, an dem Nutzer warten. Bei einem Batch-Worker lässt du die Retry-Schleife ganz weg und überlässt das Tempo einer Queue mit fester Einreichungsrate – dann stößt du viel seltener ans Limit, und wenn doch, ist die Queue der natürliche Ort zum Warten.

Welches Limit du tatsächlich zuerst erreichst

In der Praxis kommen die meisten Teams nie ans Video-Limit. Sechs Einreichungen pro Minute sind 360 pro Stunde, und ein Guthaben ist lange leer, bevor sich ein Rate-Limiter beschwert – bei Videoarbeit sind Credits und die reale Renderzeit die eigentlichen Engpässe. Deshalb sind der Artikel zur Budgetplanung und /pricing hier wichtiger als dieser.

Chat ist das Gegenteil. Sechzig Requests pro Minute im kostenlosen oder im Hobby-Plan sind schnell erreicht, sobald eine Companion-App oder ein Rollenspiel-Produkt einen vollen Abend hat, und jeder Zug eines Nutzers ist ein Request. Wenn du auf Chat aufbaust, plan mit dem Multiplikator, verteil die Last pro Oberfläche auf mehrere Schlüssel und lies den Praxisleitfaden zu SSE-Streaming, bevor du den Retry-Pfad entwirfst – ein Stream, der mitten in der Antwort abbricht, braucht eine andere Behandlung als ein Request, der nie gestartet ist.

Bilder liegen dazwischen. Zwanzig pro Minute sind für interaktive Nutzung reichlich und für einen großen Katalog-Job knapp – ein weiteres Argument für eine Queue, die du selbst steuerst, statt für einen Fan-out paralleler Requests.

Häufige Fragen

Gelten die Rate-Limits von eroq pro Schlüssel oder pro Konto?

Pro Schlüssel. Jeder API-Schlüssel bekommt sein eigenes gleitendes Ein-Minuten-Fenster. Deshalb verhindert ein eigener Schlüssel pro Umgebung oder Pipeline, dass eine aus dem Ruder gelaufene Schleife alles andere im Workspace drosselt.

Erhöht ein Upgrade meines Plans die Rate-Limits?

Ja. Die dokumentierten Limits sind die Basis, und der Plan multipliziert sie für jeden Schlüssel – 2× bei Creator, 4× bei Studio, 6× bei Team, 8× bei Agency. Auch die Zahl der Schlüssel steigt mit dem Plan.

Was soll ich tun, wenn der Video-Endpunkt ein 429 zurückgibt?

Lies den Header Retry-After, warte genau so lange und versuch es dann einmal erneut. Fehlt der Header, nutz exponentielles Backoff mit Full Jitter und begrenz deine Parallelität, damit der nächste Batch nicht gegen dieselbe Wand läuft.

Lies die Endpunkt-Referenz unter /docs und schau dann unter /faq nach, was dein Plan multipliziert.