API Rate Limits

Die 5 Stufen

Jede Anfrage durchläuft fünf Kontrollen. Die erste, die ablehnt, gewinnt.

Stufe	Fenster	Standardlimit	Zweck
Cooldown	zwischen Anfragen	1 second	Stoppt schnell feuernde Scraper; benutzerfreundlich
Burst	60-Sekunden rollend	20 requests	Fängt Skripte ab, die sich langsam hochschaukeln
Stündlich	1-Stunden-Fenster	150 requests	Weiche Obergrenze für Dauerbetrieb
Täglich	24-Stunden-Fenster	1000 requests	Harte Tagesobergrenze
Pro Endpoint	täglich	50–1000 (varies)	Schützt teure Ressourcen

Tägliche Limits pro Endpoint

Einige Endpoints haben strengere Limits, weil sie deutlich CPU- oder GPU-Zeit verbrauchen:

Endpoint	Tageslimit pro IP
`tools/upscale-image`, `tools/colorize-photo`, `tools/enhance-photo`, `tools/restore-old-photo`, `tools/noise-reduction`, `tools/remove-object`, `tools/vocal-remover`	50/day
`tools/speech-to-text`, `tools/remove-background`, `tools/change-background`, `tools/passport-photo`, `tools/image-to-text`	100/day
`tools/compress-video`, `tools/trim-video`, `tools/video-speed-changer`, `tools/extract-audio`, `tools/remove-audio`	100/day
`tools/merge-videos`, `tools/reverse-video`	50/day
Alles andere (`convert`, `jobs`, `batch`, Formatkonverter, Bildbearbeitung)	1000/day

Dateigrößenlimit

200 MB pro Datei für die API (im Vergleich zu 100 MB auf der Website).
Einige rechenintensive KI-Tools haben niedrigere interne Limits — z. B. ist upscale-image auf 20 MB begrenzt, damit GPU-Durchläufe unter 2 Minuten bleiben.

Headers in jeder Antwort

Jede erfolgreiche API-Antwort enthält die folgenden Headers, damit Sie Ihr Kontingent verfolgen können, ohne /api/v1/limits abzufragen:

HTTP headers

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

Was passiert, wenn Sie ein Limit erreichen

Die API gibt 429 Too Many Requests zurück mit einem Retry-After-Header (in Sekunden) und einem X-RateLimit-Reason-Header, der angibt, welche Stufe erreicht wurde:

HTTP/1.1 429

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Mögliche X-RateLimit-Reason-Werte: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Ban-Eskalation

Wiederholter Missbrauch löst einen temporären Ban aus. Konkret: 10 Rate-Limit-Ablehnungen innerhalb 1 Stunde von derselben IP → 24-Stunden-Ban mit HTTP 403 Forbidden und error.code: BANNED.

Falls Sie glauben, zu Unrecht gebannt worden zu sein (z. B. weil Sie sich eine IP mit vielen Nutzern teilen), kontaktieren Sie uns unter /contact und wir prüfen den Fall.

Best Practices gegen Drosselung

Warten Sie mindestens 1 Sekunde zwischen aufeinanderfolgenden Anfragen (oder nutzen Sie den Retry-After-Header bei 429).
Nutzen Sie Batch-Endpoints für Massenverarbeitung: POST /api/v1/batch verarbeitet bis zu 20 Dateien in einem einzigen HTTP-Aufruf (jede Datei zählt weiterhin zu Ihrem Tageslimit, aber Sie sparen Round Trips).
Beachten Sie die Headers: Wenn X-RateLimit-Remaining-Day unter 100 fällt, verlangsamen Sie oder cachen Sie Ihre Ergebnisse.
Prüfen Sie Ihre Nutzung jederzeit mit GET /api/v1/limits — dieser Endpoint zählt NICHT zu Ihrem Kontingent.
Wiederholen Sie nicht sofort bei 429 — respektieren Sie Retry-After. Sofortige Wiederholungen können eine Ban-Eskalation auslösen.

Höhere Limits nötig?

Die aktuellen Limits sind MVP-Standardwerte. Wir beobachten die tatsächliche Nutzung und passen sie je nach Bedarf an. Wenn Sie einen berechtigten Anwendungsfall haben, der höhere Kontingente benötigt, melden Sie sich über /contact.

Ein zukünftiger kostenpflichtiger Tarif könnte dedizierte Kontingente, Prioritätswarteschlangen und längere Dateiaufbewahrung bieten — aber der kostenlose Tarif bleibt immer erhalten.