API- und MCP-Dokumentation

Der kostenlose API-Zugang ist eine vom Browser-Tool getrennte Cloud-Funktion. Nach der Anmeldung mit einem von Google verifizierten @gmail.com-Konto und Turnstile-Freigabe erhältst du ohne Kreditkarte 500 credits pro UTC-Monat, vorbehaltlich eines monatlichen Budgets von $20 für kostenlose Rechenleistung.

Erstelle nach der Aktivierung einen API-Schlüssel in den Kontoeinstellungen. Alle Schlüssel eines Kontos teilen sich denselben Credit-Pool, dieselben Ratenlimits und dieselben Grenzen für unfertige Jobs. Wenn das kostenlose Rechenbudget erschöpft ist, pausieren neue kostenlose Jobs bis zur angezeigten Reset-Zeit; bezahlte Developer-Jobs und lokale Browser-Komprimierung laufen getrennt weiter.

Sende eine Multipart-Anfrage mit einer GIF-Datei und einem options-Feld, das JSON enthält. Der Zielgrößenmodus nutzt Dezimalbytes in targetBytes; sende mode oder targetBytes nicht als separate Formularfelder.

Jede Erstellungsanfrage muss einen kontobezogenen Idempotency-Key enthalten. Wenn du denselben Schlüssel mit derselben Datei und denselben Optionen wiederverwendest, wird der ursprüngliche Job zurückgegeben, ohne erneut Credits zu reservieren.

Die Erstellungsantwort enthält eine id auf oberster Ebene. Speichere sie als JOB_ID und verwende sie in der Status-URL; sie liegt nicht in einer job-Eigenschaft. Die Erstellungsantwort allein enthält keinen Download-Link. Frage den Status-Endpunkt auch dann ab, wenn die Erstellung einen bereits abgeschlossenen Job wiedergibt. Ersetze YOUR_JOB_ID im Beispiel durch diese id und kopiere dann result.downloadUrl aus einer succeeded-Antwort in DOWNLOAD_URL, bevor du den Download-Befehl ausführst.

Solange der Status queued oder processing ist, ist result null. Bei succeeded liest du result.downloadUrl und result.expiresInSeconds. Bei failed oder canceled beendest du das Polling und prüfst error.code und error.message, statt einen Download erneut zu versuchen.

Frage alle paar Sekunden ab und bleibe innerhalb des Lese-Limits deines Kontos. Eine neue Statusabfrage kann einen abgelaufenen Download-Link erneuern, solange die Datei noch zugänglich ist. Links gelten bis zu 15 Minuten und verlängern den Dateizugriff nie über 24 Stunden hinaus. Polling, Download und exakte idempotente Wiederholung verbrauchen keine Credits.

JSON-Anfragen zum Erstellen eines Jobs verwenden sourceUrl und options. Der Server ruft ausschließlich HTTPS-URLs ab, prüft jede Weiterleitung, blockiert private Netzwerke und wendet dieselben Dateigrößenlimits wie beim Upload an.

Wenn eine Website Browser-CORS blockiert, kann der lokale URL-Import fehlschlagen. Der REST-URL-Import bleibt ein Cloud-Job und nutzt deinen API-Schlüssel, deine Credits, Ratenlimits und Aufbewahrungsregeln.

GET /api/v1/usage gibt { usage } zurück. Das usage-Objekt enthält aktiven Pool, limit, used, reserved, remaining, resetAt, windowStart und windowEnd. Kostenlose Erstellungsanfragen sind auf 10 rpm begrenzt, Developer-Erstellungsanfragen auf 60 rpm und Status- oder Nutzungsabfragen auf 120 rpm pro Konto.

Kostenlose API-Fenster werden nach UTC-Kalendermonat zurückgesetzt. Developer-Fenster werden monatlich zum Abonnement-Anker zurückgesetzt, auch bei Jahresabonnements. Credits werden nicht übertragen. Free-Konten dürfen 2 unfertige Jobs haben, Developer-Konten 20, und die kostenlose Warteschlange kann 100 Jobs halten. Ein kostenloser Job, der länger als 10 Minuten wartet, wird beendet und gibt seine Reservierung frei.

Der MCP-Endpunkt ist Streamable HTTP unter /api/mcp. Er stellt compress_gif, get_compression und get_usage bereit und nutzt denselben API-Schlüssel wie REST.

MCP akzeptiert entfernte HTTPS-GIF-URLs. Lokale Dateien sollten über REST hochgeladen werden; übergib keine lokalen Serverpfade oder großen Base64-Nutzlasten an das MCP-Werkzeug.

Rufe compress_gif mit sourceUrl, einem optionalen options-Objekt und einem erforderlichen idempotencyKey auf. Übergebe anschließend die zurückgegebene id an get_compression. Der Adapter legt die REST-Antwort in structuredContent.data ab; erfolgreicher Tool-Transport bedeutet nicht, dass der Komprimierungsjob fertig ist. Nutze get_usage mit einem leeren Objekt, um dein Guthaben zu prüfen.

Eingaben bis 5MB kosten im quality- oder size-Modus 1 Credit und im target-Modus 2 Credits. Eingaben über 5MB bis einschließlich 20MB kosten 2 Credits beziehungsweise 4 Credits im target-Modus. Jeder Verarbeitungsversuch hat ein Budget von 60 Sekunden und höchstens 8 kodierte Kandidaten.

Validierungsfehler, Systemfehler und Zeitüberschreitungen verbrauchen keine Nutzer-Credits. Ein gültiges Ergebnis, das die gewünschte Zielgröße verfehlt, verbraucht dennoch das angezeigte Kontingent, weil die Rechenarbeit abgeschlossen wurde; der Job markiert targetMet: false.

Die Felder credits und cost.credits des Jobs zeigen die angebotenen Kosten, nicht den Nachweis einer abgeschlossenen Abbuchung. Credits werden bei Annahme eines Jobs reserviert, bei Erfolg abgerechnet und bei Fehlschlag freigegeben. Prüfe /api/v1/usage für die aktuellen Werte used, reserved und remaining.

Häufige Fehlercodes sind API_KEY_REQUIRED, API_KEY_INVALID, INSUFFICIENT_CREDITS, FREE_API_NOT_ACTIVE, IDEMPOTENCY_CONFLICT, INPUT_TOO_LARGE, INVALID_GIF, RATE_LIMITED, TOO_MANY_OUTSTANDING_TASKS und FREE_COMPUTE_BUDGET_EXHAUSTED.

401 steht für fehlende oder ungültige API-Schlüssel. 402 gilt nur für erschöpfte Nutzer-Credits. 403 steht für nicht aktiven kostenlosen API-Zugang. 409 steht für Idempotenzkonflikte. 413 steht für Cloud-Eingabegrößenlimits. 422 steht für ungültige GIF-Daten oder Optionen. 429 steht für Erstellungs-/Leseratenlimits und Grenzen für unfertige Jobs. 503 steht für vorübergehenden Warteschlangendruck oder FREE_COMPUTE_BUDGET_EXHAUSTED; beachte Retry-After, wenn vorhanden.

Lokale Browser-Komprimierung und Cloud-API-Jobs haben unterschiedliche Datenflüsse. Wähle das Browser-Tool, wenn das GIF auf deinem Gerät bleiben soll; nutze REST oder MCP, wenn ein Remote-Workflow es verarbeiten muss.

Das Browser-Tool lädt dein GIF nicht hoch. Beim Import über eine URL kontaktiert dein Browser direkt die Website, die das Bild hostet. API- und MCP-Anfragen laden eine Datei hoch oder bitten unseren Dienst, eine öffentliche HTTPS-URL abzurufen. Cloudflare hostet Anwendung, Datenbank und Dateispeicher. Der Zugriff auf API-Eingabe- und Ausgabedateien endet nach 24 Stunden; Download-Links gelten bis zu 15 Minuten. Die Hintergrundbereinigung entfernt abgelaufene Dateien, daher kann die physische Löschung später erfolgen. Für Zuverlässigkeits- und Nutzungsanalysen erfassen wir technische Ereignisse wie erfolgreiche oder fehlgeschlagene Komprimierung, Eingabe- und Ausgabegröße, Zielstatus und Downloads in Cloudflare-Dienstprotokollen. Diese Ereignisse enthalten keine Dateinamen, Quell-URLs oder Dateiinhalte. Cloudflare verarbeitet außerdem Anfragedaten, um den Dienst bereitzustellen und zu schützen. Produkt-Ereignisprotokolle werden bis zu 7 Tage aufbewahrt.

Sende Authorization: Bearer YOUR_API_KEY bei Erstellungs-, Status- und Nutzungsanfragen. Die API akzeptiert auch den Header x-api-key. Konto-Anmelde-Cookies ersetzen keinen API-Schlüssel. Alle Schlüssel eines Kontos teilen sich Kontingente und Limits.

Bewahre den Schlüssel in einer serverseitigen Umgebungsvariable oder in der geschützten Konfiguration deines KI-Clients auf. Lege ihn nicht in einer öffentlichen Webseite, einem Repository oder einer Bild-URL ab. Wenn ein Schlüssel offengelegt wurde, widerrufe ihn in den API-Key-Einstellungen und erstelle einen Ersatz. Das kostenlose Browser-Tool benötigt keinen API-Schlüssel.

mode akzeptiert quality, size oder target und ist standardmäßig quality. target erfordert einen positiven ganzzahligen targetBytes-Wert, gemessen in Dezimalbytes: 100KB sind 100000 und 1MB ist 1000000. Bei Multipart-Uploads gehören diese Felder in das JSON-kodierte options-Feld.

Optional akzeptiert colors die Werte auto, 64, 128 oder 256. lossyLevel akzeptiert eine ganze Zahl von 0 bis 200. width akzeptiert eine ganze Zahl von 1 bis 4096 und fordert eine Größenänderung an; lasse es weg, um die ursprünglichen Abmessungen zu behalten. Es gibt keine Option für Frame-Dropping oder Formatkonvertierung.

Eine Anfrage verarbeitet ein GIF. Free-API-Eingaben sind auf 5MB begrenzt, Developer-Eingaben auf 20MB. Außerdem muss jede Kante höchstens 4096 Pixel haben, es dürfen höchstens 1.000 Frames vorhanden sein und Breite × Höhe × Framezahl darf höchstens 50.000.000 betragen. Eine kurze, aber sehr große Animation kann diese Sicherheitslimits vor dem Byte-Limit erreichen.

Wähle für jede neue Datei-und-Optionen-Anfrage einen neuen Idempotency-Key und behalte diesen Schlüssel, wenn du nach einer unklaren Netzwerkantwort wiederholst. Schlüssel enthalten 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Eine identische Wiederholung gibt die bestehende Aufgabe zurück; eine Änderung von Eingabe oder Optionen unter demselben Schlüssel ergibt 409 IDEMPOTENCY_CONFLICT.

Bei 429 oder vorübergehenden 503-Antworten beachte Retry-After, wenn vorhanden, und warte länger. Ein 402-Credit-Mangel braucht eine Kontingent-Erneuerung oder einen Tarifwechsel; wiederholte Anfragen beheben ihn nicht. Ein 503 FREE_COMPUTE_BUDGET_EXHAUSTED pausiert neue kostenlose Jobs bis zum angezeigten Reset, während bezahlte Jobs und das lokale Browser-Tool getrennt bleiben.

Wenn ein Job fehlgeschlagen ist, lies error.code, bevor du erneut startest. Ein erneuter Versuch nach INVALID_GIF braucht normalerweise eine andere Datei; ein erneuter Versuch nach INPUT_TOO_LARGE braucht eine kleinere Eingabe oder einen anderen Tarif. Starte einen bewussten Neuversuch mit einem neuen Idempotency-Key, aber behalte denselben Key für echte Netzwerk-Wiederholungen.