API FÜR ENTWICKLER · ÖFFENTLICHE BETA

MegaPotato API

Vergrößere Fotos direkt aus deinem Code – mit demselben Modell und zu denselben Chip-Preisen wie auf der Website. Zwei Anfragen: Foto senden, Ergebnis abholen. In unserem Vergleich von 18 KI-Upscalern im Oktober 2026 belegte das Modell den ersten Platz und war unter den Spitzenreitern am günstigsten.

Auf dieser Seite

Schnellstart

Erstelle einen Schlüssel auf deiner Kontoseite, speichere ihn in der Umgebungsvariablen MEGAPOTATO_API_KEY und führe Folgendes aus:

shell
# 1. Foto senden
curl https://megapotato.app/v1/upscale \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
  -H "Idempotency-Key: photo-001" \
  -F file=@photo.jpg \
  -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Warten (der Server hält die Anfrage bis zu 55 s offen)
curl "https://megapotato.app/v1/jobs/6f6f4c1e-…?wait=55" \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY"
# → {"status": "completed", "result_url": "https://…", …}

Ohne Schlüssel testen

Ohne Konto und Schlüssel: Sende ein Foto an /v1/try und frage /v1/try/{id} ab. Der Auftrag läuft tatsächlich auf demselben Modell. cost_chips zeigt den Preis mit Schlüssel an, berechnet wird nichts. Testaufträge werden nach allen Aufträgen mit Schlüssel verarbeitet und können bei hoher Auslastung länger warten. Der Testzugang hat ein Budget: Bei 429 warte gemäß Retry-After oder erstelle einen Schlüssel. 403 bedeutet, dass der Testzugang geschlossen ist. Zurzeit geschlossen. Nutze einen Testschlüssel oder einen API-Schlüssel von deiner Kontoseite.

shell
# 1. Foto senden (ohne Konto, ohne Schlüssel)
curl https://megapotato.app/v1/try -F file=@photo.jpg -F upscale=4
# → {"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

# 2. Warten (der Server hält die Anfrage bis zu 55 s offen)
curl "https://megapotato.app/v1/try/6f6f4c1e-…?wait=55"
# → {"status": "completed", "result_url": "https://…", …}

Testschlüssel

Du möchtest die Anbindung testen, bevor du Chips kaufst? Jedes angemeldete Konto kann auf der Kontoseite einen Testschlüssel (mp_test_…) erstellen. Er durchläuft den gesamten Ablauf: Uploads werden wie mit einem Live-Schlüssel geprüft und bepreist. Es wird aber nichts verarbeitet oder berechnet. Jeder Auftrag liefert completed mit einem Beispielbild unter result_url und result_jpeg_url. jpeg_status ist immer ready, unabhängig davon, ob jpeg=true gesendet wurde. Eine erneute Anfrage mit demselben Idempotency-Key und Foto liefert dieselbe Auftrags-ID. Die Wiederverwendung für ein anderes Foto wird nur bei Live-Schlüsseln abgelehnt (422). Wechsle zu einem Live-Schlüssel, sobald du bereit bist. Live-Schlüssel werden mit deinem ersten Chip-Paket freigeschaltet.

Authentifizierung

Sende deinen Schlüssel bei jeder Anfrage im Header Authorization: Bearer mp_live_…. Schlüssel werden nur einmal beim Erstellen angezeigt. Wir speichern nur einen Hash. Bewahre sie auf deinem Server auf, niemals in einer mobilen App, einer Webseite oder einem Repository. Gerät ein Schlüssel in falsche Hände, widerrufe ihn auf deiner Kontoseite. Er funktioniert dann sofort nicht mehr.

Preis prüfen – POST /v1/quote

Sende Ausgangsgröße und Faktor, um den Preis zu erhalten. Es wird nichts hochgeladen oder berechnet.

shell
curl https://megapotato.app/v1/quote \
  -H "Authorization: Bearer $MEGAPOTATO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width": 4032, "height": 3024, "upscale": 2}'
# → {"cost_chips": 5, "output_width": 8064, "output_height": 6048, "upscale": 2}

Foto vergrößern – POST /v1/upscale

Multipart-Formular mit file (PNG, JPG, WEBP und HEIC, bis zu 40 MB) und upscale: 1 (Verfeinern, gleiche Größe), 2, 4 oder 8. Die längste Seite darf beim Original bis zu 6 000 px und beim Ergebnis bis zu 16 400 px lang sein. Wähle für große Fotos einen kleineren Faktor.

response
{"id": "6f6f4c1e-…", "status": "queued", "upscale": 4, "cost_chips": 2}

cost_chips wird sofort von deinem Guthaben reserviert und abgebucht, wenn das Foto fertig ist. Schlägt die Verarbeitung fehl, bekommst du die Chips automatisch zurück.

Optional fügt jpeg=true neben dem PNG ein JPEG in voller Größe hinzu (Qualität 92, ohne Chroma-Subsampling), ohne Aufpreis. Ein verlustfreies 16K-PNG kann mehrere hundert MB groß sein; das JPEG desselben Ergebnisses ist meist nur einen Bruchteil so groß. Der Auftrag enthält dann result_jpeg_url und jpeg_status. Wird ein Idempotency-Key mit einem anderen Foto oder einem anderen Wert für upscale oder jpeg wiederverwendet, folgt 422.

Ergebnis abrufen – GET /v1/jobs/{id}

Mit ?wait=55 hält der Server die Anfrage offen, bis der Auftrag fertig ist oder 55 Sekunden vergangen sind – je nachdem, was zuerst eintritt. Meist reicht ein Aufruf für den ganzen Auftrag.

Die meisten Fotos sind in Sekunden fertig. Bei steigender Nachfrage schalten wir weitere Kapazitäten hinzu. Die ersten Anfragen danach können ein paar Minuten dauern, dann läuft alles mit voller Geschwindigkeit. Frage weiter mit ?wait=55 ab. Du musst nichts Besonderes beachten.

response
{
  "id": "6f6f4c1e-…",
  "status": "completed",          // queued → running → completed | failed
  "result_url": "https://…",      // PNG; Link etwa eine Stunde gültig, kein Auth-Header nötig
  "error": null,                  // Grund bei Fehlschlag, mit „deine Chips wurden erstattet“
  "upscale": 4,
  "created_at": "2026-09-15T10:00:00Z",
  "eta_seconds": null,            // Schätzung während der Wartezeit oder Verarbeitung
  "result_jpeg_url": "https://…", // Mit jpeg=true: JPEG in voller Größe, gleiche Regeln wie für result_url
  "jpeg_status": "ready"          // null ohne jpeg=true; pending → ready | unavailable
}

Rufe den Auftrag erneut ab, um eine neue result_url zu erhalten. Ergebnisse bleiben 90 Tage verfügbar.

jpeg_status ist pending, solange der Auftrag wartet oder läuft, ready, sobald result_jpeg_url gesetzt ist, und unavailable, wenn der Auftrag ohne JPEG abgeschlossen wurde (das PNG wird trotzdem geliefert), fehlgeschlagen oder abgelaufen ist. Ohne jpeg=true sind beide Felder null. Ausnahme: Bei Testschlüsseln enthalten beide URLs das Beispielbild und jpeg_status ist immer ready.

Bei einem Auftrag mit Status completed kann noch pending stehen, während sein JPEG hochgeladen wird. Das dauert meist Sekunden, selten bis zu etwa einer Stunde. result_url funktioniert bereits. Erneutes Abfragen liefert result_jpeg_url (oder unavailable, falls das JPEG nicht verfügbar wird).

Fehler

Alle Fehler haben dieselbe Struktur:

response
{"error": {"type": "insufficient_credits", "message": "insufficient chips: available 0, needed 2"}}
  • 400 · invalid_request_error
    Das Bild lässt sich nicht dekodieren oder überschreitet die Größenlimits.
  • 401 · authentication_error
    Der Schlüssel fehlt, ist falsch oder wurde widerrufen.
  • 402 · insufficient_credits
    Nicht genug Chips für dieses Foto. Die Meldung nennt die benötigte Anzahl.
  • 404 · invalid_request_error
    Auftrag nicht gefunden (oder gehört dir nicht).
  • 413 · invalid_request_error
    Die Datei überschreitet das Upload-Limit.
  • 415 · invalid_request_error
    Bildformat nicht unterstützt.
  • 422 · invalid_request_error
    Ungültiger Wert für upscale oder jpeg, fehlende Datei oder Wiederverwendung eines Idempotency-Keys mit einem anderen Foto oder einem anderen Wert für upscale oder jpeg.
  • 429 · rate_limit_error
    Zu viele Anfragen oder zu viele Fotos gleichzeitig in Verarbeitung. Beachte Retry-After.
  • 422 · content_not_allowed
    Unsere automatische Inhaltsprüfung hat das Bild blockiert (siehe Nutzungsbedingungen). Es wurde nichts berechnet.
  • 429 · spend_limit_reached
    Das heutige API-Tageslimit ist erreicht. Es wird um 00:00 UTC zurückgesetzt.
  • 500 · server_error
    Unser Fehler. Versuche es erneut – bei Uploads mit demselben Idempotency-Key.
  • 503 · service_unavailable
    Wir können gerade keine Bilder annehmen. Es wurde nichts berechnet. Versuche es nach der in Retry-After angegebenen Wartezeit erneut.

Limits

  • Pro Konto können bis zu 10 Fotos gleichzeitig verarbeitet werden. Darüber hinaus erhält ein neuer Upload 429. Es wird nichts berechnet.
  • Bis zu 100 Uploads pro Minute und Schlüssel. Für Statusabfragen gelten höhere Limits.
  • Ein Tageslimit für den API-Verbrauch (UTC-Tag) verhindert, dass ein Schlüssel in falschen Händen dein Guthaben aufbraucht. Standardmäßig gilt 5 000 Chips pro Tag. Auf deiner Kontoseite kannst du ein niedrigeres Limit festlegen.

Preise

Die API kostet bei gleichem Foto und Faktor genauso viel wie die Website und nutzt dasselbe Chip-Guthaben. Der Preis steigt mit der Ergebnisgröße: Ein Foto mit 1 MP kostet bei ×4 etwa 2 Chips, ein Handyfoto mit 12 MP bei ×2 etwa 5 Chips. Je nach Paket kostet ein Chip $0.033–0.05. Prüfe jede Größe mit /v1/quote. Fehlgeschlagene Aufträge werden automatisch erstattet. Kaufe Chips auf der Preisseite – sie verfallen nie.

Wiederholte Anfragen

  • Sende bei Uploads immer einen Idempotency-Key (bis zu 128 Zeichen, eindeutig pro Foto). Eine erneute Anfrage mit demselben Schlüssel liefert denselben Auftrag und wird nur einmal berechnet. Nach einem Timeout kannst du die Anfrage also bedenkenlos wiederholen.
  • Warte bei 429 gemäß Retry-After. Wiederhole bei 5xx oder Netzwerkfehlern mit wachsenden Pausen (1 s, 2 s, 4 s …). Andere 4xx-Fehler lassen sich durch Wiederholen nicht beheben – korrigiere die Anfrage.
  • Nutze ?wait=55 zum Abfragen statt eines Aufrufs pro Sekunde.

Beta & Versionierung

Die API ist in der öffentlichen Beta. Es gibt noch keine Verfügbarkeitsgarantie. Über geplante Änderungen informieren wir dich per E-Mail. Innerhalb von /v1 ergänzen wir nur, etwa neue Felder oder Fehlertypen. Ignoriere daher unbekannte Felder. Änderungen, die bestehende Integrationen beeinträchtigen würden, erscheinen als /v2 mit mindestens 90 Tagen Vorankündigung.

Erlaubte Nutzung

Die Ergebnisse gehören dir. Nutze die API nur für Bilder, die du verarbeiten darfst. Verboten sind illegale Inhalte, sexuelle Inhalte mit Minderjährigen und intime Bilder von Personen ohne deren Einwilligung. Konten, die gegen diese Regeln oder die Nutzungsbedingungen verstoßen, werden gesperrt. Melde Missbrauch an abuse@megapotato.app, Fragen an support@megapotato.app.

API-Schlüssel erstellen

Spezifikation, Beispiele, Node