Generierungen

Video- und Bildmodelle benötigen zwischen wenigen Sekunden und mehreren Minuten. Jede Anfrage ist daher asynchron. Beim Absenden erhalten Sie sofort eine Generierung. Anschließend fragen Sie den Status ab oder erhalten bei Erreichen eines Endstatus einen Webhook. Ein Generierungsobjekt beschreibt den gesamten Auftrag – Eingabe, Status, Ausgabe, Fehler und Kosten.

Ablauf#

Die Statuswerte succeeded, failed und canceled kennzeichnen Endzustände: Nach Erreichen eines dieser Status ändert sich die Generierung nicht mehr. Behandeln Sie alle anderen Werte als „in Bearbeitung“, damit Ihr Code auch dann funktioniert, wenn wir Zwischenstatus hinzufügen.

1. Absenden#

POST /api/v1/run/{endpoint} mit den Modelleingaben als JSON-Body. Die Endpunkt-ID kombiniert Modell und Aufgabe, zum Beispiel bytedance/seedance-2.0-fast/text-to-video. Alle Endpunkte und ihre Felder finden Sie auf der Seite Modelle.

Wir prüfen die Eingabe, berechnen den Preis, reservieren ihn von Ihrem Guthaben und stellen den Auftrag in die Warteschlange. Die Antwort ist 202 Accepted und enthält die Generierung sowie urls.get und urls.cancel der Einfachheit halber:

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "Langsame Kamerafahrt auf einen Keramiker, der zur goldenen Stunde eine Vase formt, Staub im Licht, geringe Tiefenschärfe",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

Referenzbilder, -videos und -audiodateien#

Die Modi von reference-to-video akzeptieren bis zu drei Arten von Referenzen, jeweils als Liste von HTTPS-URLs (öffentliche Links oder URLs aus uploads): reference_image_urls für Figuren, Produkte und Szenen, reference_video_urls für Bewegungen, Kamerafahrten und Effekte sowie reference_audio_urls für Stimme, Musik und Ton.

Verweisen Sie im Prompt anhand der Position darauf: @Image1 ist die erste URL in reference_image_urls, @Video1 die erste in reference_video_urls, @Audio2 der zweite Audioclip usw. Verweise unterscheiden nicht zwischen Groß- und Kleinschreibung und werden auf @Image1 normalisiert. Ein Verweis ohne passende Referenz (zum Beispiel @Video2 mit einem angehängten Video) wird mit 400 invalid_request (param: "prompt") abgelehnt, bevor etwas berechnet wird.

{
  "prompt": "@Image1 dances on a rooftop, copying the choreography and camera move of @Video1, in sync with @Audio1",
  "reference_image_urls": [
    "https://example.com/dancer.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/choreo.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "resolution": "720p",
  "duration": 8
}

Beim Absenden laden wir den Anfang jeder Referenzvideo- und -audiodatei herunter und prüfen Dauer, Größe, Auflösung und Bildrate anhand der Modelllimits. Bei Überschreitungen – etwa einem 20-Sekunden-Clip, einem 1080p-Video für ein Modell mit 720p-Limit, einer M4A-Datei statt MP3 oder WAV oder einer nicht erreichbaren URL – gibt die API 400 invalid_request mit param für das betroffene Feld (zum Beispiel reference_video_urls) und einer Meldung zum Clip zurück, bevor etwas berechnet wird. Referenzvideos erhöhen die abgerechneten Sekunden; siehe Abrechnung.

Videos müssen H.264 oder H.265 in MP4/MOV sein. Es gelten die strengsten Limits der Kapazität, auf der das jeweilige Modell ausgeführt wird. Eine Anfrage, die diese Prüfung besteht, wird angenommen. Referenzbilder und Audio ändern den Preis nicht.

2. Ergebnis abfragen#

GET /api/v1/generations/{id} gibt den aktuellen Status zurück. Auch das Abrufen einer Generierung bringt sie voran: Falls eine Statusprüfung ansteht, erfolgt sie vor der Antwort. Abgefragte Daten sind daher höchstens wenige Sekunden alt.

const API = "https://cheapergen.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}` };
const FINAL = new Set(["succeeded", "failed", "canceled"]);

export async function wait(id, timeoutMs = 15 * 60_000) {
  let delay = 2000;
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const gen = await fetch(`${API}/generations/${id}`, { headers }).then((r) => r.json());
    if (FINAL.has(gen.status)) return gen;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10_000); // back off to every 10 s
  }
  // Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
  await fetch(`${API}/generations/${id}/cancel`, { method: "POST", headers }).catch(() => {});
  throw new Error(`Timed out waiting for ${id}`);
}

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def wait(gen_id, timeout=900):
    delay, waited = 2, 0
    while waited < timeout:
        gen = requests.get(f"{API}/generations/{gen_id}", headers=headers).json()
        if gen["status"] in ("succeeded", "failed", "canceled"):
            return gen
        time.sleep(delay)
        waited += delay
        delay = min(delay * 1.5, 10)  # back off to every 10 s
    # Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
    requests.post(f"{API}/generations/{gen_id}/cancel", headers=headers)
    raise TimeoutError(gen_id)

Empfohlene Abfrageintervalle#

• Bilder: alle 1–2 Sekunden abfragen. Die meisten Bilder sind in weniger als 30 Sekunden fertig.
• Video: zunächst alle 3–5 Sekunden abfragen und das Intervall dann bis auf 10 Sekunden erhöhen. Ein 5-Sekunden-Clip dauert üblicherweise ein bis drei Minuten, bei hoher Auflösung länger.
• Abfragen zählen zu Ihrem Ratenlimit. Wenn Sie viele Aufträge gleichzeitig ausführen, verwenden Sie bevorzugt Webhooks.

3. Ausgabe verwenden#

Bei Erfolg enthält output HTTPS-URLs zu den generierten Medien. Videomodelle geben eine Datei zurück:

{
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  }
}

Bildmodelle geben eine Liste zurück, einen Eintrag pro generiertem Bild:

{
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
        "content_type": "image/png"
      }
    ]
  }
}

Fehler und Erstattungen#

Wenn eine Generierung fehlschlägt, status ist failed, error nennt den Grund und die nächsten Schritte, und cost.amount_usd sinkt auf 0 — der gesamte reservierte Betrag wurde Ihrem Guthaben wieder gutgeschrieben. Ausfälle und Fehler bei Anbietern werden automatisch über alle anderen geeigneten Routen erneut versucht, bevor ein Auftrag als fehlgeschlagen markiert wird. Eine Ablehnung durch einen Sicherheitsfilter oder eine Eingabe, die das Modell nicht verarbeiten kann, wird nicht erneut versucht: Sie würde auf dieselbe Weise abgelehnt. Wenn ein Anbieter Ihre Eingabedatei nicht herunterladen kann, laden wir sie normalerweise selbst herunter und versuchen es mit unserer Kopie zum selben Preis erneut; input_unreachable bedeutet meist, dass die Datei gar nicht heruntergeladen werden konnte.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "Ihre Anfrage hat die Inhaltsprüfung nicht bestanden. Passen Sie den Prompt an und versuchen Sie es erneut."
  },
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  }
}

• code – die übergeordnete Fehlerklasse, seit dem Start unverändert: generation_failed (Eingabe abgelehnt oder nicht verarbeitbar), upstream_error, timeout oder model_unavailable.
• reason – der genaue Grund, siehe Tabelle unten. Verwenden Sie diesen Wert für neue Integrationen zur Fallunterscheidung; weitere Gründe können hinzukommen.
• message – beschreibt in verständlichen Worten, was passiert ist und was Nutzern angezeigt werden kann. Bei Ablehnung durch einen Sicherheitsfilter wird angegeben, welcher Modellentwickler ihn bereitstellt.
• hint – gibt an, was geändert oder als Nächstes getan werden soll.
• retryable – true, wenn dieselbe Anfrage bei erneutem Senden erfolgreich sein kann; false, wenn sie auf dieselbe Weise fehlschlagen würde.
• refunded – true, wenn die Reservierung erstattet wurde. Fehlgeschlagene Generierungen werden nie berechnet.
• param – das zu ändernde Eingabefeld, sofern erkennbar (z. B. image_url, duration).
• detail – der Wortlaut des Modellfehlers, falls er zusätzliche Informationen enthält.

Generierungen, die vor Einführung von reason fehlgeschlagen sind, behalten ihr ursprüngliches code; reason und hint werden auch für sie ausgefüllt.

Notfallpreis#

Wenn die übliche Kapazität für eine Anfrage nicht verfügbar ist, kann sie mit teurerer Kapazität zum Notfallpreisausgeführt werden. Dieser Preis liegt nie über dem offiziellen Modellpreis. allow_fallback_price legt dies fest. Standardmäßig gilt true für die REST-API und MCP: Eine neue Anfrage wird zum Notfallpreis angeboten und abgerechnet. Bei einem bereits zum Standardpreis angenommenen Auftrag, dessen Kapazität unterwegs ausfällt, kann ebenfalls auf den Notfallpreis gewechselt werden (der Aufpreis wird dann reserviert). max_cost_usd begrenzt beide Preise. Übergeben Sie allow_fallback_price: false um nie mehr als den angebotenen Preis zu zahlen (bei einem Pro- oder Max-Tarif, andernfalls kann ein angenommener Auftrag auch steigen, höchstens bis zum Standardpreis): Für eine neue Anfrage wird dann ein Preis von 503 fallback_price_declined, und bei einem angenommenen Auftrag schlägt die Generierung stattdessen fehl und wird erstattet. Studio-Aufträge wechseln nach Ihrem Klick nie zu einem höheren Preis. Wenn der Notfallpreis gilt, nennt die Generierung pricing.fallback (auch in Webhooks) beide Preise. genannt.

Sicherheitsprüfung#

enable_safety_checker ist standardmäßig true. Sie können false über die API senden. Im Studio und auf den Modellseiten ist die Option immer aktiviert. Ihre Wirkung hängt vom Modell ab:

• Geschlossene Modelle (Seedance, Kling, Veo, MiniMax H3, Wan 3.0 …) verwenden die eigene Moderation ihres Anbieters, die sich nicht deaktivieren lässt. Sie akzeptieren true und false, und bei beiden ändert sich dadurch nichts – deshalb wird die Option in den jeweiligen Schemas nicht aufgeführt. MiniMax H3 Max ist die Ausnahme: Hier lässt sich der Filter deaktivieren, daher ist die Option im Schema enthalten. Für solche Anfragen gilt eine eigene Sicherheitskonfiguration — möglicherweise zum Notfallpreis, höchstens zum offiziellen Preis.
• Seedream 4.5 and Seedream 5.0 Lite führen die Option ebenfalls auf. Ist sie deaktiviert, läuft die Anfrage auf der internationalen Modellkonfiguration des Entwicklers ByteDance, die keinen zusätzlichen Filter anwendet. Ist sie aktiviert, gelten die üblichen Filter. Unser Prüfer blockiert weiterhin alle sexuellen Inhalte, an denen Minderjährige beteiligt sind. Anfragen mit deaktivierter Option haben einen eigenen, höheren Preis: Seedream 4.5 $0.04 per image · Seedream 5.0 Lite $0.035 per image. /quote gibt diesen Preis zurück, wenn Sie enable_safety_checker: false (mit fallback.reason "safety_checker_off" senden). Die Anfrage zählt als Notfallpreis: Mit allow_fallback_price: false wird sie abgelehnt. Kann sie gerade nicht ausgeführt werden, wird sie mit 503 model_unavailable (param: "enable_safety_checker") abgelehnt. Senden Sie true, um sie mit dem Standardfilter auszuführen.
• Open-Weight-Modelle führen die Option auf. Wenn eine Generierung auf Kapazität ohne eigenen Filter ausgeführt wird, prüft unser Prüfsystem zuerst den Prompt und die Eingabebilder: Ist der Schalter aktiviert, blockiert es sexuelle, drastisch gewalttätige und selbstverletzende Inhalte; ist er deaktiviert, blockiert es weiterhin alle sexuellen Inhalte mit Minderjährigen. Verfügt die Kapazität über einen eigenen zuschaltbaren Filter, wird der Schalter unverändert weitergegeben; ist er deaktiviert, blockiert unser Prüfsystem weiterhin alle sexuellen Inhalte mit Minderjährigen.

Wenn false in einem Modus verwendet wird, der die Option nicht aufführt (und dessen Prüfsystem sich nicht deaktivieren lässt), wird 400 invalid_request zurückgegeben. Durch Ausschalten werden keine Inhalte erlaubt, die unser Richtlinie zur zulässigen Nutzung verbietet.

Datenaufbewahrung#

API-Generierungen werden standardmäßig 1 Tag aufbewahrt, gerechnet ab Abschluss. Danach löschen wir Prompt, Eingabemedien, Ausgaben und Dateien automatisch. Die Generierung selbst bleibt mit Modell, preisbestimmenden Parametern, Kosten und Zeitstempeln erhalten, damit Verlauf und Rechnungen korrekt bleiben: output wird zu null, purged_at wird gesetzt und content_expired erklärt den Grund. Laden Sie gewünschte Ausgaben vor expires_at herunter.

Übergeben Sie retention im Anfrage-Body, um die Aufbewahrungsfrist je Generierung festzulegen. Jedes Konto kann sie verkürzen (oder bis zu 1d anfragen); 7d und 30d benötigen eine Einstellung auf Kontoebene – Vertrieb kontaktieren. Eine längere Frist als für Ihr Konto erlaubt gibt 400 invalid_request mit param: "retention" zurück.

{
  "prompt": "A paper boat drifting down a rain-soaked street",
  "resolution": "720p",
  "duration": 5,
  "retention": "immediate",
  "webhook_url": "https://example.com/hooks/cheapergen"
}

Studio- und Playground-Generierungen bleiben erhalten, bis Sie sie löschen. Uploads bleiben erhalten, solange eine gespeicherte Generierung sie verwendet; ungenutzte Dateien werden nach 1 Tag gelöscht. Beim Löschen Ihres Kontos werden alle Generierungen und Dateien gelöscht. Soweit ein Modellentwickler uns die Wahl lässt, bitten wir ihn, Inhalte möglichst kurz aufzubewahren.

Generierung löschen#

Löschen Sie jede abgeschlossene Generierung mit DELETE /api/v1/generations/{id}, in der Generierungsliste im Dashboard oder im Studio-Viewer; über die API auch eine wartende, solange sie sich noch abbrechen lässt (sie wird zuerst abgebrochen und der reservierte Betrag vollständig erstattet). Dateien, Prompt und Eingaben werden sofort entfernt, und sie verschwindet aus den Listen; die Belastung bleibt in Ihrem Abrechnungsverlauf. Siehe API-Referenz.

Abbrechen#

POST /api/v1/generations/{id}/cancel bricht eine Generierung ab, die noch queued ist, und erstattet den reservierten Betrag. Sobald der Auftrag running ist, wird er bereits vom Modell verarbeitet. Beim Abbrechen erhalten Sie 409 conflict zurück, der Auftrag wird aber normal abgeschlossen und abgerechnet. Einige Modelle lassen sich nach dem Einstellen in die Warteschlange nicht abbrechen; auch dann erhalten Sie 409 zurück.

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Generierungen auflisten#

GET /api/v1/generations listet Ihre Generierungen neueste zuerst mit Cursor-Paginierung auf. Filtern Sie nach status, model oder source (playground, api, mcp). Übergeben Sie den zurückgegebenen next_cursor als cursor, um die nächste Seite abzurufen. Einzelheiten finden Sie in API-Referenz.

curl "https://cheapergen.com/api/v1/generations?status=succeeded&limit=50" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Generierungen aus dem Studio und den Playgrounds auf Modellseiten erscheinen hier ebenfalls, mit source: "playground"; API-Anfragen enthalten source: "api".