Tutorial: Ein Bild in ein Video verwandeln

Sie beginnen mit einem Bild auf Ihrem Computer und halten am Ende eine heruntergeladene Videodatei in der Hand. Jeder Schritt zeigt die CLI, das TypeScript-SDK und reines HTTP.

Dieses Tutorial nimmt ein Bild von Ihrem Computer und macht daraus einen kurzen Videoclip, den Sie herunterladen und behalten. Es geht den ganzen Weg der Reihe nach: ein Modell auswählen, das Bild hochladen, den Preis prüfen, die Generierung starten, auf sie warten, das Ergebnis herunterladen und mit allem umgehen, was dabei schiefgehen kann. Sie müssen sich nichts aus den Referenzseiten zusammensuchen.

Jeder Schritt zeigt drei Wege, dasselbe zu tun. Wählen Sie einen davon und bleiben Sie durchgehend dabei:

Weg	Wählen Sie ihn, wenn	Sie brauchen
CLI	Sie Befehle eintippen und keinen Code schreiben möchten	Node.js 22.13 oder neuer
TypeScript SDK	Sie ein Node.js-Programm entwickeln und die Aufrufe sehen möchten, die es macht	Node.js 22.13 oder neuer
HTTP (curl)	Sie die API in Rohform sehen möchten, etwa um später eine andere Programmiersprache zu verwenden	Ein Bash-Terminal mit `curl` und `jq` (macOS, Linux oder WSL unter Windows)

Möchten Sie das Ganze lieber einem KI-Assistenten überlassen? Siehe Mit einem KI-Assistenten erledigen.

Was Sie erstellen

Das Ergebnis: eine kurze Videodatei, meist MP4, die mit Ihrem Bild beginnt und sich so bewegt, wie Ihr Satz es beschreibt.
Ihr Zeitaufwand: Rechnen Sie beim ersten Mal mit etwa 20 Minuten, die meiste Zeit davon zum Lesen. Die Generierung selbst dauert meist ein paar Minuten; manche Modelle und Einstellungen brauchen länger.
Wo es läuft: bei SpicyAPI. Ihr Computer sendet nur das Bild und die Anweisungen und lädt danach die fertige Datei herunter.

Was es kostet und wie Sie das vor dem Bezahlen herausfinden

Preise sind in US-Dollar angegeben. Sie hängen vom gewählten Modell und von Ihren Einstellungen ab, etwa von Länge und Auflösung des Videos; deshalb nennt diese Seite keinen Betrag. Den Preis sehen Sie an drei Stellen, und keine davon kostet etwas:

Der Live-Katalog (Schritt 1) listet jedes Modell, das Ihr Konto nutzen kann, mit den Preisen Ihres Kontos. Videos werden meist per_second berechnet, also pro Sekunde erzeugten Videos. Nennt ein Modell mehrere Preise, gehört jeder zu einer bestimmten Einstellung, etwa einer Auflösung.
Eine Kostenschätzung (Schritt 3) nennt den genauen Preis Ihrer genauen Anfrage. Sie startet nichts und reserviert kein Geld.
Die Bestätigung: Die CLI zeigt den Preis noch einmal und wartet auf Ihr y, bevor sie irgendetwas startet.

Was mit Ihrem Geld passiert:

Nur Schritt 4 kostet Geld, ebenso das erneute Ausführen eines fehlgeschlagenen Tasks. Modelle auflisten, hochladen, eine Kostenschätzung einholen, warten und herunterladen sind kostenlos.
Sobald eine Generierung startet, wird der geschätzte Betrag in Ihrem Guthaben zurückgelegt (eine Reservierung). Dieser Betrag ist zugleich das Höchste, was das Video kosten kann.
Ist das Video erfolgreich, zahlen Sie für das, was erzeugt wurde, nie mehr als die Reservierung, und der Rest geht in Ihr Guthaben zurück.
Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.
Neue Konten starten ohne kostenloses Kontingent; Sie brauchen also zuerst Guthaben. Siehe Abrechnung.

So funktioniert es

your picture ──upload──▶ spicy:// address (usable for one day)
                                   │
your sentence + settings ──────────┴──▶ quote (free) ──▶ start the task (money set aside)
                                                                  │
                                         queued ──▶ running ──▶ succeeded / failed / expired
                                                                  │
                                              download link (about 20 minutes) ──▶ your file

Im Schema oben: Ihr Bild wird hochgeladen und erhält eine spicy://-Adresse, die einen Tag lang verwendbar ist. Zusammen mit Ihrem Satz und Ihren Einstellungen holen Sie eine kostenlose Kostenschätzung ein und starten dann den Task, wofür Geld zurückgelegt wird. Der Task durchläuft queued und running bis zu succeeded, failed oder expired; am Ende steht ein Download-Link, der etwa 20 Minuten gilt, und daraus Ihre Datei.

Ein Task ist ein einzelner Generierungsauftrag. SpicyAPI bearbeitet ihn im Hintergrund; ihn zu starten und das Ergebnis abzuholen, sind deshalb zwei getrennte Vorgänge. Jeder Task hat eine ID, die mit job_ beginnt. Bewahren Sie sie auf, denn nur über sie finden Sie den Task wieder. Weitere Begriffe dieser Seite erklärt das Glossar.

Bevor Sie beginnen

Konto, Guthaben und API-Schlüssel bereithalten

Arbeiten Sie zuerst Konto einrichten durch. Danach sollten Sie Folgendes haben:

ein SpicyAPI-Konto mit Guthaben;
einen API-Schlüssel, der mit sk-spicy- beginnt;
diesen Schlüssel in einer Umgebungsvariable namens SPICY_API_KEY. Eine Umgebungsvariable ist ein benannter Wert, den Ihr Terminal an die Programme weitergibt, die es startet. So muss der Schlüssel nie in einem Befehl oder in Ihrem Code stehen.

Prüfen Sie, ob der Schlüssel in dem Terminalfenster gesetzt ist, das Sie gerade verwenden, ohne dabei den ganzen Schlüssel auszugeben:

echo "${SPICY_API_KEY:0:9}"

Was Sie sehen sollten: sk-spicy-. Erscheint nichts oder eine Fehlermeldung, ist der Schlüssel in diesem Fenster nicht gesetzt; gehen Sie zurück zu Konto einrichten.

Ihr Bild in einen Arbeitsordner legen

Legen Sie für dieses Tutorial einen Ordner an und öffnen Sie Ihr Terminal darin. Jeder Befehl auf dieser Seite wird in diesem Ordner ausgeführt, und jede Datei, die dabei entsteht, landet hier.

mkdir -p ~/spicy-video
cd ~/spicy-video

Kopieren Sie Ihr Bild in diesen Ordner und nennen Sie es start-frame.jpg (oder start-frame.png, wenn es ein PNG ist; verwenden Sie dann diesen Namen überall dort, wo diese Seite start-frame.jpg schreibt).

Was ein gutes Startbild ausmacht:

Format und Größe: JPEG, PNG, WebP oder GIF, bis 10 MiB (etwa 10 Megabyte). Ein Modell kann eigene, strengere Grenzen setzen; die sehen Sie in Schritt 1.
Die Datei muss dieses Format wirklich haben. SpicyAPI prüft den Inhalt der Datei, nicht nur ihren Namen. Fotos vom Smartphone liegen oft als HEIC vor, und wer ein solches Foto in .jpg umbenennt, wandelt es damit nicht um. Öffnen Sie es und exportieren oder speichern Sie es zuerst als JPEG.
Form: Das Bild wird zum ersten Einzelbild (Frame) des Videos. Nehmen Sie ein Bild im Querformat für ein breites Video und eines im Hochformat für ein vertikales Video; manche Modelle bieten zusätzlich die Einstellung aspect_ratio.
Rechte: Verwenden Sie ein Bild, das Sie verwenden dürfen.

Das gewählte Werkzeug einrichten

Die CLI ist ein Programm namens spicyapi, das Sie im Terminal ausführen. Installieren Sie sie einmalig (vollständige Anleitung einschließlich Node.js: CLI: Bevor Sie beginnen):

npm install -g @spicyapi/cli
spicyapi --version

Schlägt die Installation mit EACCES fehl, lassen Sie sie aus und tippen Sie überall dort npx @spicyapi/cli, wo diese Seite spicyapi schreibt.

Prüfen Sie dann, ob Ihr Schlüssel funktioniert und ob Sie Guthaben haben:

spicyapi balance

Was Sie sehen sollten: available, held und total in US-Dollar. available muss über null liegen.

Die sieben Schritte

Ersetzen Sie MODEL_ID_FROM_CATALOG durch eine echte Modell-ID

MODEL_ID_FROM_CATALOG ist ein Platzhalter, kein Modell. In Schritt 1 wählen Sie eine echte Modell-ID aus dem Live-Katalog aus (spicyapi models list, listModels() im SDK oder GET /api/v1/models). Setzen Sie sie überall dort ein, wo diese Seite den Platzhalter zeigt. Wer den Platzhalter selbst sendet, bekommt nur einen „not found“-Fehler zurück.

Unter Windows? Nehmen Sie den Tab CLI oder TypeScript SDK

Der Tab HTTP ist für bash geschrieben. Windows PowerShell behandelt Anführungszeichen, Zeilenumbrüche mit \ und $(...) anders, deshalb laufen diese Befehle dort nicht so, wie sie dastehen. Verwenden Sie unter Windows den Tab CLI oder TypeScript SDK, oder führen Sie die HTTP-Befehle in WSL aus (Windows-Subsystem für Linux, englisch Windows Subsystem for Linux).

1. Ein Modell auswählen und seine Einstellungen lesen

Das tun Sie: Sie listen die Bild-zu-Video-Modelle auf, die Ihr Konto nutzen kann, wählen eines davon aus und lesen dann, welche Einstellungen es annimmt.

Listen Sie die Modelle auf:

spicyapi models list --modality video --task image-to-video --json

Was Sie sehen sollten: eine JSON-Liste. Diese hier ist gekürzt, und Beträge sind als … dargestellt:

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

Wählen Sie ein Modell, bei dem enabled und available beide true sind, und kopieren Sie seinen model-Wert. Lesen Sie dann seine Einstellungen:

spicyapi models get MODEL_ID_FROM_CATALOG --json

Die Antwort enthält dieselben Felder, dazu inputSchema (die Einstellungen) und examples (Eingaben, die der Server bereits geprüft hat).

Worauf Sie in der Liste achten sollten:

Feld	Was es Ihnen sagt
`model`	Die Modell-ID, die Sie in jedem weiteren Schritt verwenden
`enabled`, `available`	Verwenden Sie ein Modell nur, wenn beide `true` sind
`pricing`	Ein Eintrag pro Preisstufe: `variant` (die Einstellung, für die er gilt, oft eine Auflösung), `unit` (bei Video meist `per_second`) und `price` in US-Dollar. `regularPrice` und `offerLabel` erscheinen, wenn ein Rabatt gilt
`quantityField`	Die Einstellung, die bestimmt, für wie viele Einheiten Sie zahlen, meist `duration_seconds`. Ist das Feld leer, zählt eine Einheit pro Video
`maxOutputDurationSeconds`	Das längste Video, das das Modell erlaubt
`taskTimeoutSeconds`	Wie lange eine Generierung laufen darf, bevor sie als `expired` endet (und nicht berechnet wird)

So lesen Sie die Einstellungen. inputSchema ist die Liste der Einstellungen des Modells, geschrieben als JSON Schema:

required listet die Einstellungen, die Sie senden müssen. Bei dieser Art von Modell ist image_url immer dabei, und die meisten verlangen außerdem prompt.
properties listet jede Einstellung, die das Modell annimmt, jeweils mit einem type, einer description in einfachem Englisch und oft mit enum (den einzigen erlaubten Werten), minimum und maximum sowie default (dem Wert, der gilt, wenn Sie die Einstellung weglassen).
Innerhalb jeder Einstellung enthält x-ui Hinweise für die Darstellung. x-ui.affects_price: true bedeutet, dass sich der Preis ändert, wenn Sie diese Einstellung ändern.
Einige Modelle legen auf oberster Ebene zusätzliche Bedingungen fest, etwa „Wenn Sie A senden, müssen Sie auch B senden“. Wie Sie diese lesen, erklärt Spicy Schema.
examples enthält vollständige Eingaben, die der Server bereits geprüft hat, und ist damit ein sicherer Ausgangspunkt.

Die Einstellungen, die Ihnen am häufigsten begegnen. Die Namen sind bei allen Modellen gleich, aber jedes Modell nimmt nur einen Teil davon an, jeweils mit eigenen erlaubten Werten:

Einstellung	Was sie bewirkt	Ändert sie den Preis?
`image_url`	Das Startbild, verwendet als erstes Einzelbild. Nimmt die `spicy://`-Adresse aus Schritt 2 oder einen öffentlichen `https://`-Link an	Nein
`prompt`	Was passieren soll: die Bewegung, die Kamera, die Stimmung. Beschreiben Sie Bewegung, statt zu wiederholen, was das Bild ohnehin zeigt	Meist nicht
`duration_seconds`	Videolänge in Sekunden. Die erlaubten Werte stehen in `enum` oder liegen zwischen `minimum` und `maximum`; manche Modelle nehmen einen Sonderwert an, den die `description` der Einstellung erklärt	Bei den meisten Modellen ja: Video wird meist pro Sekunde berechnet, ein längerer Clip kostet also mehr
`resolution`	Ausgabegröße, etwa `720p` oder `1080p`	Meist ja: Höhere Auflösungen haben in der Regel einen eigenen, höheren Preis
`aspect_ratio`	Die Form des Videos, etwa `16:9`, `9:16` oder `1:1`. Manche Modelle bieten `adaptive`, das sich nach dem Bild richtet	Sehen Sie in `x-ui.affects_price` nach
`generate_audio`	Zusätzlich eine Tonspur erzeugen, die zum Bild passt	Bei manchen Modellen
`last_image_url`	Ein Bild für das letzte Einzelbild; siehe Erstes und letztes Bild	Mit einer Kostenschätzung prüfen
`negative_prompt`	Was im Video nicht vorkommen soll	Meist nicht
`seed`	Eine Zahl, mit der sich Ergebnisse verschiedener Durchläufe leichter vergleichen lassen; identische Videos garantiert sie nicht	Nein

Senden Sie nur Einstellungen, die dieses Modell auflistet

Jedes Modell hat seine eigene Liste. Eine Einstellung, die nicht in den properties dieses Modells steht, ein falsch geschriebener Name oder ein Wert außerhalb von enum lässt die ganze Anfrage mit 400 scheitern. Berechnet wird dabei nichts, aber übernehmen Sie keine Eingabe von einem anderen Modell, ohne sie zu prüfen.

Was gerade passiert ist: Sie haben den Live-Katalog für Ihr Konto gelesen, einschließlich Ihrer Preise. Es wurde nichts berechnet. Das Lesen des Katalogs zählt gegen das Rate Limit Ihres Kontos; Sie müssen es also nicht vor jedem Video wiederholen. Tun Sie es erneut, wenn Sie das Modell wechseln oder ein 400 erhalten.

2. Ihr Bild hochladen

Das tun Sie: Sie laden start-frame.jpg hoch und kopieren die spicy://-Adresse, die Sie zurückbekommen. Das Hochladen ist kostenlos.

spicyapi files upload start-frame.jpg

Was Sie sehen sollten:

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

Kopieren Sie den Wert von uri genau so, wie er ausgegeben wird.

Was gerade passiert ist: Ihr Bild wurde privat für Ihr Konto gespeichert, geprüft (sein tatsächliches Format muss zu seinem angegebenen Typ passen) und hat eine spicy://-Adresse erhalten. Diese Adresse ist kein Weblink: Nur Ihr Konto kann sie verwenden, und das nur in der Eingabe eines Tasks. Sie ist einen Tag lang verwendbar (siehe expiresAt); danach laden Sie das Bild erneut hoch.

Liegt das Bild schon online?

Liegt das Bild bereits unter einer öffentlichen https://-Adresse, die sich ohne Anmeldung öffnen lässt, können Sie diesen Schritt überspringen und stattdessen diese Adresse in image_url eintragen. Sie muss erreichbar bleiben, solange das Video generiert wird.

Wenn der Upload fehlschlägt:

Sie sehen	Bedeutung	Was zu tun ist
`Unsupported file type`, oder die CLI bzw. das SDK meldet, dass sich der Typ nicht bestimmen lässt	Die Datei ist kein JPEG, PNG, WebP oder GIF	Wandeln Sie das Bild um oder geben Sie ihm die richtige Dateiendung
`File exceeds the 10 MB limit`	Das Bild ist größer als 10 MiB	Exportieren Sie eine kleinere Fassung
`The uploaded file does not match the upload ticket`	Der Inhalt der Datei entspricht nicht dem Typ, den ihr Name oder die Angabe beim Anfordern des Tickets nennt, etwa bei einem HEIC-Foto, das in `.jpg` umbenannt wurde	Exportieren Sie es als echtes JPEG oder PNG und laden Sie es erneut hoch
`The upload ticket has expired`	Zwischen Ticket und Commit sind mehr als etwa 20 Minuten vergangen	Beginnen Sie den Upload von vorn

3. Das Video beschreiben und den Preis prüfen

Das tun Sie: Sie schreiben Ihre Einstellungen in eine Datei namens input.json und holen dann eine Kostenschätzung ein.

Schreiben Sie input.json. Beginnen Sie mit den zwei Einstellungen, die jedes Bild-zu-Video-Modell annimmt. Schreiben Sie Ihren eigenen Satz in prompt und ersetzen Sie den Wert von image_url durch die uri, die Sie in Schritt 2 kopiert haben:

input.json

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Für Einstellungen, die Sie weglassen, gilt der default des Modells. Möchten Sie sie selbst festlegen, fügen Sie nur Einstellungen hinzu, die in den properties Ihres Modells stehen, und zwar mit Werten, die es erlaubt. Ein Beispiel, wenn Ihr Modell duration_seconds und resolution listet und diese Werte erlaubt:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Speichern Sie die Datei in Ihrem Arbeitsordner:

Setzen Sie Ihren eigenen Text und Ihre uri ein und fügen Sie dann alle Zeilen auf einmal ein:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Verwenden Sie einfache gerade Anführungszeichen ("), keine typografischen, und setzen Sie nach der letzten Einstellung kein Komma.

Holen Sie die Kostenschätzung ein:

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

Was Sie sehen sollten (Beträge als … dargestellt):

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

Was gerade passiert ist: SpicyAPI hat Ihre Eingabe mit den Einstellungen des Modells abgeglichen und den Preis genau dieser Anfrage berechnet. Es wurde nichts gestartet und nichts berechnet. estimatedCost ist der Betrag, der zurückgelegt wird, wenn Sie jetzt starten, und maxCharge das, was es höchstens kosten kann. quantity und unit zeigen, wofür Sie zahlen, etwa für 5 Sekunden.

Eine Kostenschätzung gilt fünf Minuten und nur für genau diese Eingabe. Um Preise zu vergleichen, ändern Sie Länge oder Auflösung und holen eine neue Kostenschätzung ein. Die Kostenschätzung führt dieselben Prüfungen aus wie der Start des Tasks, Probleme zeigen sich also schon hier und kostenlos: Ein 400 bedeutet, dass die Eingabe nicht zu den Einstellungen des Modells passt (korrigieren Sie input.json anhand von Schritt 1), und ein 40201 bedeutet, dass Ihr Guthaben nicht ausreichen würde. Schritt 7 nennt die übrigen Codes.

Lieber erst ein Testlauf ohne eigenes Bild?

Die examples des Modells aus Schritt 1 sind vollständige Eingaben, die der Server bereits geprüft hat. Sie können eine davon unverändert in input.json übernehmen, eine Kostenschätzung dafür einholen und sie generieren. So sehen Sie den ganzen Ablauf einmal funktionieren, bevor Sie Ihr eigenes Bild verwenden.

4. Die Generierung starten

Dieser Schritt kostet Geld

Beim Start der Generierung wird der geschätzte Betrag in Ihrem Guthaben zurückgelegt. Sobald SpicyAPI sie angenommen hat, lässt sich der Task nicht mehr abbrechen: Er läuft bis zum Ende und wird berechnet, wenn er erfolgreich ist. Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.

Der Idempotenzschlüssel, einfach erklärt. Er ist eine Kennung für ein Video, ähnlich einer Bestellnummer. Bricht Ihre Verbindung ab und Sie wissen nicht, ob das Video gestartet wurde, senden Sie dieselbe Anfrage mit derselben Kennung noch einmal: SpicyAPI gibt Ihnen dann den bereits gestarteten Task zurück, statt ein zweites Video zu starten und zu berechnen. Eine Kennung gilt 24 Stunden, und zwar mit demselben API-Schlüssel. Nehmen Sie für ein anderes Video eine neue Kennung: Dieselbe Kennung mit einer anderen Eingabe wird mit 409 abgelehnt. Mehr dazu unter Idempotenz.

Das tun Sie:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Die CLI holt erneut eine Kostenschätzung ein, zeigt den Preis und wartet auf Sie:

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

Tippen Sie y und drücken Sie die Eingabetaste. Jede andere Eingabe bricht ab, und es wird nichts berechnet. Kopieren Sie den Wert von Idempotency-Key irgendwohin, bevor Sie antworten: Die CLI erzeugt bei jedem Lauf eine neue Kennung, und genau diese brauchen Sie, falls die Verbindung abbricht.

Was Sie sehen sollten:

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Kopieren Sie die taskId.

Was gerade passiert ist: SpicyAPI hat die Generierung angenommen, die jetzt ein Task ist, und estimatedCost in Ihrem Guthaben zurückgelegt. Das ist zugleich das Höchste, was dieses Video kosten kann. state: queued bedeutet, dass der Task wartet, bis er an der Reihe ist. deadlineAt ist der späteste Zeitpunkt, zu dem er fertig werden kann; ist er bis dahin nicht fertig, endet er als expired, und es wird nichts berechnet. deadlineAt ist nicht der Zeitpunkt, zu dem Ihre Dateien ablaufen.

Die Kostenschätzung mitzugeben bedeutet: „Nur zu dem Preis annehmen, der mir angezeigt wurde.“ Haben sich Preis oder Eingabe in der Zwischenzeit geändert, wird die Anfrage mit 40901 abgelehnt, statt einen anderen Betrag zurückzulegen. Die CLI erledigt das für Sie.

Ist die Verbindung abgebrochen und Sie haben nie eine Task-ID gesehen, starten Sie nicht einfach mit einer neuen Kennung neu, denn das würde ein zweites Video erzeugen und berechnen. Wiederholen Sie die Anfrage mit derselben Kennung:

CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>, wobei Sie für <the value you copied> den kopierten Wert einsetzen. Siehe Einen Task nach unterbrochenem Warten wieder aufnehmen.
SDK: Führen Sie node generate.mjs --yes erneut aus; das Skript verwendet idempotency-key.txt wieder.
HTTP: Führen Sie den Block „Das Video starten“ erneut aus; er verwendet idempotency-key.txt wieder.

Wurde Schritt 4 abgelehnt, wurde nichts erstellt und nichts berechnet; Grund und Lösung finden Sie in Schritt 7.

5. Auf das Video warten

Das tun Sie: Sie fragen den Task ab, bis er fertig ist. Videos dauern meist ein paar Minuten.

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

Verwenden Sie Ihre eigene Task-ID. Mit --wait-timeout-ms 1800000 wartet die CLI bis zu 30 Minuten statt der standardmäßigen 10.

Was Sie sehen sollten, sobald der Task fertig ist (gekürzt):

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Beim nächsten Mal können Sie die Schritte 4 und 5 zusammenfassen, indem Sie tasks create um --wait ergänzen.

Was gerade passiert ist: Ihr Werkzeug hat SpicyAPI alle paar Sekunden nach dem Task gefragt. Die Status lauten queued (wartet), running (wird generiert) und dann ein Endzustand: succeeded, failed oder expired. Nach einem Erfolg wird die Datei in den eigenen Speicher von SpicyAPI kopiert, was noch ein paar Sekunden dauert; bis dahin zeigt das Ergebnis pending: true. cost ist endgültig, sobald settled den Wert true hat.

Wenn Sie das Terminal schließen oder Strg + C drücken, wird der Task nicht abgebrochen. Nur das Warten endet. Bewahren Sie die Task-ID auf und führen Sie diesen Schritt später erneut aus.
Fragen Sie nicht öfter als alle paar Sekunden ab. Das Abfragen eines Tasks nutzt das Lesekontingent des Kontos unabhängig vom Starten neuer Tasks; siehe Ratenbegrenzungen.
Für eine App oder einen Server lassen Sie sich besser von SpicyAPI benachrichtigen, wenn der Task fertig ist, statt nachzufragen: siehe Benachrichtigen lassen statt warten.

6. Das Video herunterladen und behalten

Das tun Sie: Sie holen sich einen frischen Download-Link und speichern die Datei auf Ihrem Computer.

Holen Sie sich einen frischen Link:

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

Fügen Sie die url in einen Browser ein, um die Datei herunterzuladen, oder speichern Sie sie im Terminal, indem Sie die url anstelle von PASTE_THE_URL_HERE einsetzen (lassen Sie die Anführungszeichen stehen, denn der Link enthält &-Zeichen):

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Tippen Sie in Windows PowerShell curl.exe statt curl. Hat ein Task mehrere Dateien erzeugt, listet spicyapi tasks get <task-id> --json sie auf, und mit --key wählen Sie eine davon aus.

Was gerade passiert ist: Zu jedem Ergebnis gehört ein direkter Download-Link. Der Link funktioniert etwa 20 Minuten und braucht keinen API-Schlüssel; hängen Sie Ihren Schlüssel niemals an ihn an. Ist er abgelaufen, fragen Sie den Task erneut ab (oder verwenden Sie files download-url), um einen neuen zu erhalten.

Behalten Sie eine eigene Kopie

SpicyAPI bewahrt generierte Dateien höchstens etwa 14 Tage auf, kürzer, wenn die Aufbewahrungseinstellung Ihres Kontos kürzer ist, und löscht sie danach endgültig. Ihr hochgeladenes Bild ist einen Tag lang verwendbar, und Ihr Prompt-Text wird standardmäßig nach 30 Tagen gelöscht. Der Datensatz des Tasks und seine Kosten bleiben erhalten. Um die Dateien und den Prompt eines abgeschlossenen Tasks früher zu löschen, verwenden Sie spicyapi tasks purge, purgeTask() oder POST /api/v1/jobs/purge; das löscht nur Inhalte und ist keine Erstattung. Siehe Datenaufbewahrung und Löschung.

7. Wenn etwas schiefgeht

Es gibt zwei Arten von Problemen, und sie werden unterschiedlich behandelt.

Eine Anfrage wird abgelehnt. Ihr Befehl oder Aufruf erhält sofort einen Fehler. Es wurde nichts erstellt und nichts berechnet. Die Meldung nennt den Grund, und der Fehler enthält einen code sowie eine Anfrage-ID (req_…), die Sie angeben, wenn Sie sich an den Support wenden.

Code	Bedeutung	Was zu tun ist
`400` oder ein genauerer Code, der mit `400` beginnt	Die Eingabe passt nicht zu den Einstellungen des Modells: eine fehlende Pflichteinstellung, eine unbekannte oder falsch geschriebene Einstellung, ein nicht erlaubter Wert, eine abgelaufene oder fremde `spicy://`-Adresse, eine Kombination von Einstellungen, die das Modell derzeit nicht bedienen kann, oder eine ungültige Callback-Adresse	Vergleichen Sie `input.json` mit den Einstellungen aus Schritt 1 und korrigieren Sie die Datei. Ist die Adresse abgelaufen, laden Sie das Bild erneut hoch
`401`	Der API-Schlüssel fehlt, ist falsch geschrieben oder wurde gesperrt	Prüfen Sie `SPICY_API_KEY` wie unter Bevor Sie beginnen
`40201`	Ihr Guthaben reicht für den zurückzulegenden Betrag nicht aus	Laden Sie in der Konsole unter Abrechnung Guthaben auf
`40202`	Ein Ausgabenlimit Ihres Schlüssels (Tages-, Monats- oder Gesamtlimit) ist erreicht	Erhöhen Sie es auf der Seite API-Schlüssel oder warten Sie, bis es neu beginnt
`403`, `40301`	Dieser Schlüssel darf dieses Modell nicht verwenden, oder die Anfrage kam von einem Ort, von dem aus sie nicht erlaubt ist	Prüfen Sie auf der Seite API-Schlüssel die Angaben Erlaubte Modelle und IP-Freigabeliste des Schlüssels
`404`	Für Ihr Konto gibt es kein Modell mit dieser ID (oder Sie haben den Platzhalter gesendet), oder für diesen Schlüssel gibt es keinen Task mit dieser ID	Kopieren Sie die ID noch einmal exakt; verwenden Sie denselben Schlüssel, mit dem der Task erstellt wurde
`409`	Dieser Idempotenzschlüssel wurde bereits für eine andere Anfrage verwendet	Nehmen Sie für ein neues Video eine neue Kennung
`40901`	Die Kostenschätzung ist abgelaufen (nach fünf Minuten), oder der Preis hat sich geändert	Holen Sie eine neue Kostenschätzung ein und starten Sie dann erneut
`429`	Zu viele Anfragen in kurzer Zeit	Warten Sie so viele Sekunden, wie der Fehler angibt, und machen Sie dann langsamer weiter
`50301`	Das Modell kann gerade keine neuen Aufträge annehmen	Versuchen Sie es später erneut oder wählen Sie ein anderes Modell

Der Task schlägt fehl. Der Task wurde angenommen, endet aber als failed oder expired statt als succeeded. Der Task zeigt einen errorCode, der den Grund nennt, und eine errorMessage, die ihn ausführlicher in Worten beschreibt. Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.

So lesen Sie ihn aus:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Sehen Sie sich state, errorCode und errorMessage an.

Entscheiden Sie dann anhand von errorCode, was zu tun ist, nicht anhand des Wortlauts der Meldung:

`errorCode`	Bedeutung	Was zu tun ist
`rate_limited`, `upstream_unavailable`, `upstream_failed`	Die Generierung war ausgelastet oder vorübergehend nicht verfügbar	Führen Sie den Task nach einer kurzen Pause erneut aus
`timeout` (oder der Status ist `expired`)	Das Video wurde nicht rechtzeitig fertig	Versuchen Sie es noch einmal; passiert es erneut, wählen Sie eine kürzere Länge oder eine niedrigere Auflösung und starten Sie einen neuen Task
`generation_failed`	Die Generierung lief, hat aber nichts erzeugt	Dieselbe Eingabe scheitert meist auf dieselbe Weise. Ändern Sie den Prompt oder das Bild und starten Sie einen neuen Task
`invalid_asset`	Das Bild konnte nicht verwendet werden, etwa weil der Upload abgelaufen ist oder die Datei nicht gelesen werden konnte	Laden Sie das Bild erneut hoch und starten Sie mit der neuen Adresse einen neuen Task
`invalid_request`, `unsupported_combination`	Die Einstellungen wurden nicht angenommen	Ändern Sie die Einstellungen und starten Sie einen neuen Task
`content_rejected`	Das gewählte Modell hat diese Anfrage nach seinen eigenen Richtlinien abgelehnt	Ändern Sie den Prompt oder das Bild, oder wählen Sie ein anderes Modell

Jeden anderen Wert behandeln Sie wie upstream_failed. Die vollständige Liste steht unter Fehler.

Einen fehlgeschlagenen Task erneut ausführen. Eine Wiederholung erstellt einen neuen Task mit demselben Modell und derselben Eingabe, zum aktuellen Preis des Modells. Das kostet Geld, genau wie Schritt 4, und die ursprüngliche Eingabe bleibt unverändert: Hat sie einen Upload verwendet, der inzwischen abgelaufen ist, laden Sie stattdessen erneut hoch und starten einen neuen Task.

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

Der Befehl fragt nach einer Bestätigung, zeigt aber anders als tasks create vorher keinen Preis an. Um den Preis zu sehen, führen Sie den Befehl tasks quote aus Schritt 3 aus.

Wiederholen lassen sich nur Tasks mit failed oder expired. Für eine andere Fassung eines erfolgreichen Videos gehen Sie mit einer neuen Kennung zurück zu Schritt 3. Einen angenommenen Task abzubrechen, ist nicht möglich. Mehr dazu unter Verbindliche Tasks und Wiederholen.

Alternativ: mit einem KI-Assistenten erledigen

Nutzen Sie einen KI-Assistenten, der MCP unterstützt, etwa Claude Code, Cursor oder Codex, kann er mit dem SpicyAPI-MCP-Server alle sieben Schritte für Sie erledigen. Richten Sie den Server einmalig ein, wie unter MCP-Server: Ihren Client einrichten beschrieben, und bitten Sie dann in Ihren eigenen Worten darum, zum Beispiel:

Lade das Bild unter /Users/me/spicy-video/start-frame.jpg zu SpicyAPI hoch. Such die Bild-zu-Video-Modelle, die mein Schlüssel nutzen kann, und hol für die zwei günstigsten eine Kostenschätzung für einen 5-Sekunden-Clip ein. Generier das Video dann mit dem günstigeren, sobald ich bestätige, warte darauf und gib mir den Download-Link.

Unter Windows geben Sie den Pfad als C:\Users\me\spicy-video\start-frame.jpg an.

Was dabei passiert:

spicyapi_upload_file lädt das Bild hoch und erhält seine spicy://-Adresse. Das ist kostenlos, sendet die Datei aber tatsächlich; nennen Sie also genau die Datei, die Sie meinen. Standardmäßig können nur Dateien innerhalb Ihres Benutzerordners gelesen werden; siehe Lokale Dateien.
spicyapi_models_list und spicyapi_model_get finden ein Modell und seine Einstellungen, und spicyapi_task_quote berechnet die Preise der Optionen. Alles davon ist kostenlos.
spicyapi_task_create hält an und fragt Sie und zeigt dabei das Modell, die geschätzten und die maximalen Kosten sowie den Ablaufzeitpunkt der Kostenschätzung. Bis Sie bestätigen, wird nichts berechnet, und der Assistent kann nicht an Ihrer Stelle bestätigen.
spicyapi_task_wait wartet jeweils bis zu fünf Minuten; bei einem längeren Video wartet der Assistent deshalb unter Umständen mehrmals. Danach gibt er Ihnen den Download-Link, der etwa 20 Minuten funktioniert.

Weitere Beispiele und alle Tools: MCP-Server.

Weiterführendes

Erstes und letztes Bild

Einige Bild-zu-Video-Modelle nehmen zusätzlich last_image_url an: ein zweites Bild, mit dem das Video enden soll. Ob Ihr Modell das kann, sehen Sie, wenn Sie in den properties aus Schritt 1 nach last_image_url suchen. Steht es dort nicht, unterstützt das Modell es nicht, und eine Anfrage damit wird mit 400 abgelehnt.

Laden Sie beide Bilder wie in Schritt 2 hoch und tragen Sie dann beide Adressen in input.json ein:

{
  "prompt": "The flower slowly opens as morning light spreads across the table",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "last_image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w4"
}

Die description der Einstellung erklärt, wie das jeweilige Modell das letzte Bild verwendet. Holen Sie vor dem Start erneut eine Kostenschätzung ein, um zu sehen, ob das zweite Bild den Preis ändert.

Mehrere Videos

Den Upload wiederverwenden. Eine spicy://-Adresse lässt sich bis zu ihrem expiresAt in mehreren Tasks verwenden, es sei denn, die Upload-Aufbewahrung Ihres Kontos ist so eingestellt, dass Uploads gelöscht werden, sobald ein Task abgeschlossen ist.
Eine Kennung pro Video. Geben Sie jedem Video einen eigenen Idempotenzschlüssel, etwa campaign-clip-1, campaign-clip-2. Führen Sie Ihr Skript dann erneut aus, erhalten Sie die bereits gestarteten Videos zurück, statt doppelt für sie zu bezahlen.
Nicht alles auf einmal starten. Für jeden laufenden Task ist Geld zurückgelegt, ein Ausgabenlimit lehnt Tasks jenseits seiner Grenze mit 40202 ab, und jede Statusabfrage zählt gegen Ihr Rate Limit. Beginnen Sie mit zwei gleichzeitig.

Fertige Skripte: Einen Stapel mit begrenzter Parallelität ausführen (SDK) und Die CLI aus einem Skript ausführen.

Benachrichtigen lassen statt warten

Bei einer Website oder einem Hintergrunddienst ist es Verschwendung, ein Programm nur deshalb laufen zu lassen, damit es immer wieder fragt: „Ist es schon fertig?“ Geben Sie dem Task stattdessen eine Callback-Adresse mit: eine öffentliche Webadresse auf Ihrem eigenen Server, die SpicyAPI einmal aufruft, wenn der Task abgeschlossen ist, und zwar mit denselben Task-Angaben, die Schritt 5 zeigt.

Was Sie brauchen:

einen Server, der aus dem Internet unter einer https://-Adresse auf dem Standardport erreichbar ist (localhost wird abgelehnt);
Ihren Webhook-Signaturschlüssel aus der Konsole, damit Ihr Server prüfen kann, dass jeder Aufruf wirklich von SpicyAPI kommt;
Code, der die Signatur prüft, schnell antwortet und damit umgehen kann, dass dieselbe Benachrichtigung zweimal eintrifft.

Webhooks erklärt das Format, die Signatur und den Wiederholungsplan, und das SDK enthält einen minimalen Empfänger. Behalten Sie eine Rückfallebene: Prüfen Sie ab und zu Tasks, die ihr deadlineAt längst überschritten haben, ohne dass eine Benachrichtigung kam.

Geben Sie die Callback-Adresse mit, wenn Sie die Kostenschätzung einholen und den Task starten:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --callback-url https://your-app.example.com/hooks/spicy

Die CLI nimmt die Adresse in ihre eigene Kostenschätzung auf, sodass die Preisprüfung weiterhin übereinstimmt.