CheaperGen/skills

Cheaper Gen. API

Eine asynchrone REST-API für offizielle Video- und Bildmodelle. Die Abrechnung erfolgt über ein vorab bezahltes USD-Guthaben: Sie zahlen pro Sekunde Video oder pro Bild. Fehlgeschlagene Generationen werden automatisch rückerstattet.

• Basis-URL: https://cheapergen.com/api/v1
• Authentifizierung: Authorization: Bearer $CHEAPERGEN_API_KEY (Schlüssel beginnen mit cg_live_; einen unter https://cheapergen.com/dashboard/keys erstellen). Lesen Sie den Schlüssel aus der Umgebung. Geben Sie ihn niemals aus, protokollieren Sie ihn nicht und committen Sie ihn nicht.
• Bevorzugen Sie den MCP-Server, wenn er verbunden ist. Seine Werkzeuge sind list_models, get_model, quote, generate (mit wait_seconds und einer Budgetsicherung max_cost_usd), get_generation, get_account und add_credits (ein Zahlungslink, den der Benutzer öffnet, wenn das Guthaben niedrig ist); verwenden Sie diese anstelle von HTTP-Aufrufen. Der folgende Workflow ist derselbe. Um ihn zu verbinden, fügen Sie den entfernten Server https://cheapergen.com/api/mcp hinzu; der Benutzer meldet sich an und genehmigt im Browser (OAuth), ohne dass ein Schlüssel erforderlich ist. In Claude Code: claude mcp add --transport http cheapergen https://cheapergen.com/api/mcp, dann /mcp → Authentifizieren. Vollständige Einrichtung: https://cheapergen.com/docs/mcp

Workflow

1. Modell auswählen: GET /models (öffentlich). Es gibt jedes Modell mit endpoints[].id und Preisstufen zurück. Verwenden Sie immer die aktuelle Liste; Modelle ändern sich.
   • Video: Seedance 2.0 (beste Qualität, 4K, synchronisierter Ton), Seedance 2.0 Fast / Mini (günstiger und schneller), Seedance 2.5 (neueste, längste Referenzen), Wan 3.0 / Prime (Alibaba), MiniMax H3 / H3 Max.
   • Bild: Seedream 5.0 Pro / Lite / Flash (Text-zu-Bild und edit).
   • Endpunkt-IDs sind {vender}/{modell}/{modus}, z.B. bytedance/seedance-2.0-fast/text-to-video, bytedance/seedream-5.0-lite/text-to-image.
2. Eingabeschema lesen: GET /models/{vender}/{modell} (öffentlich) gibt endpoints[].input_schema (JSON-Schema mit Aufzählungen, Standardwerten und Grenzen) und pricing.tiers zurück. Senden Sie nur Felder aus dem Schema: unbekannte Felder werden mit 400 abgelehnt.
3. Angebot einholen: POST /quote/{endpunkt} mit der Eingabe (öffentlich, kostenlos) gibt { amount_usd, list_usd, discount_pct, available } zurück. Teilen Sie dem Benutzer vor einem teuren Auftrag (Video in 1080p/4K, lange Laufzeiten, Stapel) den Preis mit.
4. Einreichen: POST /run/{endpunkt} mit der Eingabe als JSON-Textkörper gibt 202 und eine Generation mit status: "queued" zurück. Der Preis wird zu diesem Zeitpunkt vom Guthaben abgezogen.
5. Warten: Pollen Sie GET /generations/{id}, bis status succeeded, failed oder canceled ist. Pollen Sie Bilder alle 1–2 s; pollene Sie Videos alle 3–5 s, mit Backoff auf 10 s, da ein 5 s Clip normalerweise 1–3 Minuten dauert. Oder übergeben Sie webhook_url (siehe unten).
6. Ausgabe verwenden: output.video.url (Video) oder output.images[].url (Bilder). Die URLs sind öffentlich, laufen aber gemäß der Aufbewahrungsfrist des Kontos ab (Standard 1 Tag; siehe expires_at). Laden Sie daher alles herunter, was aufbewahrt werden soll.

curl -s https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Ein Papierboot treibt eine regennasse Neonstraße entlang, langsamer Dolly-In","resolution":"720p","duration":5,"aspect_ratio":"16:9"}'
# → 202 {"id":"gen_…","status":"queued","cost":{"amount_usd":…,"estimated":true},…}
curl -s https://cheapergen.com/api/v1/generations/gen_… -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

import os, time, requests
API = "https://cheapergen.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def generate(endpoint: str, inp: dict, timeout_s: int = 900) -> dict:
    r = requests.post(f"{API}/run/{endpoint}", json=inp, headers=H, timeout=60)
    r.raise_for_status()  # 4xx bodies: {"error": {"code", "message", "param"}}
    gen, delay, start = r.json(), 2.0, time.time()
    while gen["status"] in ("queued", "running"):
        if time.time() - start > timeout_s:
            raise TimeoutError(gen["id"])
        time.sleep(delay)
        delay = min(delay * 1.5, 10)
        r = requests.get(f"{API}/generations/{gen['id']}", headers=H, timeout=30)
        if r.status_code == 429 or r.status_code >= 500:
            continue  # transient: keep polling
        r.raise_for_status()
        gen = r.json()
    if gen["status"] != "succeeded":
        raise RuntimeError(gen["error"])  # the hold was refunded
    return gen  # gen["output"]["video"]["url"] or gen["output"]["images"][0]["url"]

Modi und Eingaben

• text-to-video und text-to-image: benötigen prompt plus Optionen (resolution, duration, aspect_ratio, size, seed, generate_audio…). Überprüfen Sie das Schema auf die Aufzählungen des jeweiligen Modells.
• image-to-video: benötigt image_url (erstes Bild) und bei einigen Modellen end_image_url (letztes Bild).
• edit (Seedream): image_urls (zu bearbeitende oder zu kombinierende Bilder; bezeichnen Sie sie im Prompt als "Bild 1", "Bild 2") plus die Anweisung in prompt.
• reference-to-video: benötigt reference_image_urls, reference_video_urls und reference_audio_urls. Verweisen Sie im Prompt auf sie mit 1-basierten Positionen: @Image1, @Image2, @Video1, @Audio1 (Groß-/Kleinschreibung nicht beachtend). Eine Erwähnung ohne passende Referenz führt zu einer 400 mit param: "prompt". Beispiel: "@Image1 geht durch den Markt von @Image2, Kamera bewegt sich wie @Video1".
  • reference_rules im Schema legt die maximale Anzahl von Dateien fest und ob mindestens ein Bild oder Video erforderlich ist (Audio allein reicht für Seedance und H3 nicht).
  • Referenzvideos und -audio werden auf dem Server gemessen (Dauer, Größe, Auflösung, fps) gegen media_limits / x-media-limits. Seedance 2.0 akzeptiert MP4/MOV-Videos von 2–15 s pro Stück und insgesamt 15 s; Audio muss MP3/WAV sein. Ein Verstoß führt zu einer 400, die die Datei benennt, z.B. @Video2 ist 16 s lang….
  • Referenzvideossekunden werden zusammen mit den Ausgabesekunden abgerechnet. Referenzbilder und -audio sind kostenlos. Um ein Angebot zu erhalten, übergeben Sie reference_video_durations: [6.5] (Sekunden pro Clip).
• Medieneingaben müssen öffentliche https-URLs sein. Für lokale Dateien rufen Sie POST /uploads mit JSON { "filename", "content_type", "size" } auf. Es gibt Folgendes zurück: { upload_url, headers, url }: Führen Sie einen PUT der Bytes auf upload_url mit genau diesen headers durch und verwenden Sie dann url als Eingabe. Grenzen: Bilder (PNG/JPEG/WebP/GIF) ≤ 20 MB, Video (MP4/MOV) ≤ 50 MB, Audio (MP3/WAV/M4A) ≤ 15 MB.
• Optional bei jedem Durchlauf: webhook_url (HTTPS) und retention (immediate | 1h | 1d; 7d / 30d benötigen eine Kontoeinstellung).

Webhooks

Wenn der Auftrag abgeschlossen ist (erfolgreich oder fehlgeschlagen), senden wir { "type": "generation.succeeded" | "generation.failed", "data": <generation> } an die webhook_url, mit dem Header CheaperGen-Signature: t=<unix>,v1=<hex>. Um dies zu überprüfen, berechnen Sie hex(HMAC_SHA256(secret, "<t>.<raw body>")) mit dem Webhook-Signingschlüssel des Kontos (whsec_…, im Dashboard → API-Schlüssel), vergleichen Sie in konstanter Zeit und lehnen Sie Anfragen ab, deren t älter als 5 Minuten ist. Verwenden Sie den rohen Anfragekörper, kein neu serialisiertes JSON. Geben Sie schnell eine 2xx zurück; fehlgeschlagene Zustellungen werden wiederholt (insgesamt 3 Versuche).

Preise und Abrechnung

• Preise gelten pro Sekunde Ausgabevideo oder pro Bild. GET /models zeigt für jede Stufe den price_usd neben dem list_price_usd (dem offiziellen Preis).
• Bei der Einreichung wird der angefragte Preis zurückgehalten (cost.estimated: true). Bei Erfolg wird er endgültig; bei Fehlschlag oder Abbruch wird er vollständig zurückerstattet (cost.amount_usd: 0). cost.official_usd und cost.saved_usd zeigen die Ersparnis.
• Guthaben: GET /account gibt balance_usd und reserved_usd (für laufende Aufträge zurückgehalten) zurück. Ein 402 bedeutet, dass das Guthaben zu niedrig ist: Rufen Sie über MCP add_credits auf und zeigen Sie dem Benutzer den Zahlungslink; andernfalls fügt der Benutzer unter https://cheapergen.com/dashboard/billing Guthaben hinzu.
• Brechen Sie einen wartenden Auftrag mit POST /generations/{id}/cancel ab (409, sobald er läuft). Löschen Sie einen abgeschlossenen mit DELETE /generations/{id}.

Fehler

Jeder Fehler hat die Form { "error": { "code", "message", "param"? } }.

HTTP	code	Handlung
400	invalid_request	Beheben Sie das in param genannte Feld (überprüfen Sie Schema, Aufzählungen, Grenzen und Erwähnungen). Wiederholen Sie nicht unverändert.
401	unauthorized	Fehlender, ungültiger oder widerrufener Schlüssel.
402	insufficient_balance	Holen Sie sich einen Zahlungslink mit add_credits (MCP) und bitten Sie den Benutzer zu zahlen, oder wählen Sie eine günstigere Stufe.
404	not_found	Falscher Endpunkt oder Generations-ID.
409	conflict	Z.B. ein Auftrag abbrechen, der bereits gestartet wurde.
429	rate_limited	Warten Sie und wiederholen Sie. Das Limit liegt bei etwa 20 Anfragen in einem Schub, aufgefüllt mit 10/s pro Schlüssel, plus einer Obergrenze für gleichzeitige Generationen pro Konto (Standard 20).
502	upstream_error	Einmal wiederholen, dann ein anderes Modell versuchen.
503	model_unavailable	Später wiederholen oder Modell wechseln.

Eine Generation, die mit failed endet, hat error.code (z.B. generation_failed, timeout) und wurde zurückerstattet. Wiederholen Sie höchstens einmal mit derselben Eingabe.

Weiteres

• Dokumentation: https://cheapergen.com/docs, MCP-Einrichtung: https://cheapergen.com/docs/mcp
• Quelle dieses Skills und des Claude Code Plugins: https://github.com/CheaperGen/skills
• API-Seiten pro Modell: https://cheapergen.com/models/{vender}/{modell}/api
• Maschinenlesbare Zusammenfassung: https://cheapergen.com/llms.txt