Kommandozeilen-Tool (CLI)

Was die CLI ist

spicyapi ist ein kleines Programm, das Sie in einem Terminal ausführen, also in dem Fenster, in das Sie Befehle tippen, statt Schaltflächen anzuklicken. Jeder Befehl erledigt genau eine Aufgabe: die Modelle auflisten, die Ihr Konto nutzen kann, Ihnen sagen, was eine Generierung kosten wird, eine Bild- oder Videogenerierung starten, auf ihren Abschluss warten und Ihnen einen Link zum Herunterladen des Ergebnisses geben.

Code schreiben Sie dabei nicht. Sie tippen einen Befehl, drücken die Eingabetaste und lesen die Antwort.

Die CLI ist die richtige Wahl, wenn Sie:

• Modelle ausprobieren und Preise vergleichen möchten, bevor jemand eine Integration schreibt;
• Bilder oder Videos auf Ihrem eigenen Computer generieren und die Dateien speichern möchten;
• dieselbe Art von Generierung wiederholen möchten, ohne sich jedes Mal durch eine Seite zu klicken;
• die genauen Einstellungen eines Modells prüfen möchten, bevor Sie etwas darauf aufbauen.

Die CLI deckt die Bild- und Videogenerierung ab. Text- und Chatmodelle rufen Sie über die chat-kompatiblen Endpunkte auf, die unter Text und Streaming beschrieben sind.

Es gibt drei weitere offizielle Werkzeuge. Nehmen Sie die CLI, wenn Sie Befehle selbst eintippen möchten:

Sie schreiben in einer anderen Sprache? Auch für Python, Go, PHP und Java gibt es offizielle SDKs.

Was Sie tun können

Ein Wort in spitzen Klammern wie <task-id> bedeutet in den Befehlen oben: „Hier Ihren eigenen Wert einsetzen“, und zwar ohne die Klammern.

Bevor Sie beginnen

Sie brauchen vier Dinge: ein Terminal, Node.js, einen API-Schlüssel und eine Möglichkeit, die CLI auszuführen. Beim ersten Mal dauert das etwa zehn Minuten.

node -v

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Ihr erstes Ergebnis

Diese Anleitung generiert ein Bild und lädt es herunter. Jeder Schritt zeigt den Befehl, ungefähr das, was Sie sehen werden, und was dabei gerade passiert ist. Ihre Zahlen, IDs und Zeiten werden abweichen.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

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

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

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

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

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

So lesen Sie die Ausgabe

• Die normale Ausgabe zeigt pro Zeile ein name: value. Werte, die aus mehreren Teilen bestehen, etwa output oder retention, erscheinen als JSON in einer einzigen Zeile.
• --json gibt die vollständige Antwort als eingerücktes JSON aus. Die Option funktioniert bei jedem Befehl, vor oder nach dem Befehlsnamen: spicyapi --json balance und spicyapi balance --json bewirken dasselbe.
• Ergebnisse gehen in die normale Ausgabe, Meldungen in die Fehlerausgabe. Preise, der Idempotenzschlüssel, die Accepted:-Zeilen und Fehler sind Meldungen. Deshalb speichert spicyapi --json tasks get <task-id> > task.json nur das Ergebnis in task.json, während die Meldungen weiterhin auf dem Bildschirm erscheinen.
• Fehler sehen aus wie Error: <what went wrong> (request req_…), meist gefolgt von einer Zeile Next:, die sagt, was zu tun ist. Mit --json ist ein Fehler ein einzeiliges JSON-Objekt mit error, type, status, code und requestId, ohne Next:-Zeile. Ist kein Schlüssel gesetzt, lautet type MissingApiKeyError. Nennen Sie den Wert req_…, wenn Sie sich an den Support wenden.
• Geldbeträge sind US-Dollar, geschrieben als reiner Text ohne $-Zeichen, etwa 0.03.
• Zeitangaben sind in UTC. Das Z am Ende von 2026-09-17T08:05:00Z steht für UTC.
• Der Exit-Status ist 0, wenn ein Befehl erfolgreich war, und ungleich 0, wenn er fehlgeschlagen ist; Skripte können das auswerten.

Befehlsreferenz

Jeder Befehl hat außerdem eine eingebaute Hilfe: Ergänzen Sie --help, zum Beispiel spicyapi tasks create --help.

Globale Optionen und Umgebungsvariablen

Diese Optionen funktionieren bei jedem Befehl.

status

Was er tut: prüft, ob SpicyAPI läuft und von Ihrem Computer aus erreichbar ist.

spicyapi status

Keine Optionen. Kein Schlüssel nötig. Kostenlos.

Ausgabe: ein Satz. SpicyAPI is reachable — … answered in … ms. bedeutet, dass alles in Ordnung ist. could not be reached bedeutet, dass Ihr Computer keine Antwort bekommen hat: Prüfen Sie Ihr Netzwerk oder Ihren Proxy. is not healthy oder reports it is not ready weist auf ein Problem auf unserer Seite hin; aktuelle Störungen stehen auf status.spicyapi.ai.

Mit --json sehen Sie die einzelnen Prüfungen im Rohformat. Entscheidend ist operational: true; ein Eintrag readiness mit dem Status 404 ist an der öffentlichen Adresse normal.

docs search

Was er tut: findet die Dokumentationsseite zu einem Thema. Er durchsucht einen kleinen Index, der in die CLI eingebaut ist, und funktioniert deshalb ohne Schlüssel und ohne SpicyAPI aufzurufen. Jedes Ergebnis verlinkt auf die passende Seite dieser Dokumentation unter docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

Gibt es mehrere Ergebnisse, erscheinen sie nacheinander, und jedes beginnt mit slug:. Passt nichts, meldet der Befehl das und beendet sich trotzdem mit dem Status 0:

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

Mit --json ergibt eine Suche ohne Treffer eine leere Liste, []. Kostenlos.

models list

Was er tut: listet die Modelle, die Ihr Konto heute aufrufen kann, mit den Preisen, die Ihr Konto zahlt.

spicyapi models list [options]

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

Ausgabe: total und items. Verwenden Sie --json, denn ohne diese Option landen alle Einträge in einer Zeile. Die nützlichsten Felder jedes Eintrags:

Kostenlos. Der Abruf der Modellliste zählt gegen das Rate Limit Ihres Kontos; Sie müssen ihn also nicht vor jeder Generierung ausführen.

models get

Was er tut: zeigt ein einzelnes Modell vollständig an, einschließlich der Einstellungen, die es annimmt.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Ausgabe: dieselben Felder wie bei models list, dazu inputSchema. Lesen Sie in inputSchema die Einträge required (Einstellungen, die Sie senden müssen), properties (jede erlaubte Einstellung mit ihrem Typ), enum (die einzigen erlaubten Werte), minimum und maximum (Grenzen für Zahlen) sowie default (wird verwendet, wenn Sie die Einstellung weglassen). Einträge namens x-ui sind Hinweise für den Bau von Formularen; Sie können sie ignorieren. Kostenlos.

balance

Was er tut: zeigt, wie viel Geld auf Ihrem Konto verfügbar ist.

spicyapi balance

Keine Optionen. Kostenlos.

Ausgabe: available (was Sie jetzt ausgeben können), held (für noch laufende Tasks reserviert) und total, alles in US-Dollar. Möglicherweise ist außerdem funding enthalten, das das Guthaben in vorausbezahlte Mittel und Bonusguthaben aus Aktionen aufteilt, samt der Angabe, wann Bonusguthaben verfallen und für welche Modelle sie gelten. Sie müssen das Guthaben nicht vor jeder Generierung prüfen: Das übernimmt tasks create für Sie.

usage

Was er tut: zeigt, wie viele Generierungen der aktuelle API-Schlüssel ausgeführt hat und was sie gekostet haben, gruppiert nach Tag und nach Modell.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

Das deckt den ganzen September ab: --to ist der erste Tag, der nicht mehr dazugehört. Lassen Sie beide Optionen weg, sehen Sie die letzten sieben Tage einschließlich heute.

Ausgabe: from, to, currency, totalCalls, totalSpend, dann days (pro Tag: calls, succeeded, failed, spend) und models (dieselben Zahlen pro Modell). totalSpend zählt nur endgültige Belastungen. days und models beschreiben dieselben Tasks auf zwei Arten; addieren Sie sie also nicht. Für Ihr gesamtes Konto statt nur für einen Schlüssel verwenden Sie in der Konsole die Seite Verbrauch.

Kostenlos. Der Befehl ist auf 30 Aufrufe pro Minute begrenzt; nutzen Sie ihn also, um Summen zu prüfen, nicht in einer Schleife.

tasks quote

Was er tut: sagt Ihnen genau, was eine Generierung kosten würde, ohne sie zu starten und ohne Geld zu reservieren.

spicyapi tasks quote --model <model> --input-file <path>

Ausgabe: quoteId, model, estimatedCost, maxCharge, currency, quantity (zum Beispiel die Anzahl der berechneten Sekunden), unit und expiresAt. Eine Kostenschätzung gilt fünf Minuten.

Kostenlos und ohne Bestätigung. Nutzen Sie den Befehl, um Modelle oder Einstellungen zu vergleichen. Vor tasks create müssen Sie ihn nicht ausführen, denn dieser Befehl holt eine eigene Kostenschätzung ein.

tasks create

Was er tut: startet eine Bild- oder Videogenerierung. Das kostet Geld. Die CLI zeigt immer zuerst den Preis und fragt nach.

spicyapi tasks create --model <model> --input-file <path> [options]

Was nacheinander passiert:

1. Die CLI liest Ihre Eingabe und prüft, ob sie ein JSON-Objekt ist. Haben Sie keine Eingabe angegeben, bricht sie hier ab.
2. Kann niemand eine Rückfrage beantworten, zum Beispiel in einem Skript, und haben Sie --yes nicht angegeben, bricht sie hier ab.
3. Sie holt eine Kostenschätzung ein und gibt die geschätzte Belastung, die Höchstbelastung, den Ablaufzeitpunkt der Kostenschätzung und den Idempotenzschlüssel aus.
4. Sie fragt Continue? [y/N]. Nur y oder yes setzt fort. Die Voreinstellung ist nein.
5. Sie erstellt den Task zum geschätzten Preis. Der geschätzte Betrag wird in Ihrem Guthaben reserviert, und dieser Betrag ist zugleich das Höchste, was der Task kosten kann.
6. Ohne --wait gibt sie idempotencyKey, taskId, state (queued), estimatedCost und deadlineAt aus und kehrt zurück. Mit --wait gibt sie sofort Accepted: <task-id> und einen Befehl zur Wiederaufnahme aus, wartet und gibt dann idempotencyKey, accepted und den fertigen task aus.

deadlineAt ist der späteste Zeitpunkt, zu dem der Task fertig werden kann, bevor er als expired endet. Es ist nicht der Zeitpunkt, zu dem Ihr Download-Link oder Ihre Dateien ablaufen.

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

Unter macOS und Linux können Sie die Eingabe auch direkt in den Befehl schreiben:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Endet das Warten mit einem Fehler (und nicht mit Strg + C), wiederholen die letzten Zeilen alles, was Sie brauchen, sodass Sie nicht zur Accepted:-Zeile zurückscrollen müssen:

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

War es ein Fehler mit bekannter Lösung, etwa 429 oder ein Serverfehler, folgt eine Zeile Next:. Mit --json stehen dieselben Angaben im Fehlerobjekt als taskId, idempotencyKey und recover.

tasks wait

Was er tut: wartet auf einen Task, den Sie bereits gestartet haben, bis er fertig ist.

spicyapi tasks wait <task-id> [options]

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

Ausgabe: der fertige Task mit denselben Feldern wie bei tasks get, sobald sein Status succeeded, failed oder expired ist. War der Task erfolgreich, werden seine Dateien aber noch kopiert, wartet der Befehl noch ein wenig länger.

Läuft das Zeitlimit ab, sehen Sie Error: task … did not reach a terminal state within 600000ms. Das ist kein Fehlschlag: Der Task läuft noch. Warten Sie erneut, bei Bedarf mit einem längeren --wait-timeout-ms. Das Warten zu beenden bricht nie einen Task ab. Kostenlos.

tasks get

Was er tut: zeigt einen Task, wie er gerade ist: Status, Kosten, Ergebnislinks und wann seine Inhalte gelöscht werden.

spicyapi tasks get <task-id>

Verwenden Sie denselben API-Schlüssel, mit dem der Task erstellt wurde: Mit einem anderen Schlüssel erhalten Sie „not found“.

Ausgabefelder:

Die normale Ausgabe endet mit einer Zusammenfassung in Klartext, etwa Outputs expire: … oder Content: Destroyed — you removed the outputs …. Jeder Aufruf liefert frische Download-Links. Kostenlos.

tasks list

Was er tut: listet die mit dem aktuellen API-Schlüssel erstellten Tasks auf, jeweils eine Seite auf einmal.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Ausgabe: items (jeweils mit taskId, model, state, cost, settled, createdAt, deadlineAt und completedAt), hasMore und nextCursor. Ist hasMore gleich true, führen Sie denselben Befehl mit denselben Werten für --from und --to erneut aus und ergänzen --cursor mit dem Wert von nextCursor. Die Liste enthält keine Download-Links; verwenden Sie für den gewünschten Task tasks get. Kostenlos.

tasks retry

Was er tut: führt einen Task mit dem Status failed oder expired erneut aus, und zwar als neuen Task mit neuer ID. Das kostet Geld.

spicyapi tasks retry <task-id> [options]

Der Befehl fragt Retry source task … Continue? [y/N]. Anders als tasks create zeigt er vor der Frage keinen Preis. Der neue Task wird zum aktuellen Preis des Modells berechnet; prüfen Sie diesen deshalb vorher mit spicyapi models get <model>, wenn der Preis für Sie eine Rolle spielt.

Ausgabe: idempotencyKey, die neue taskId, sourceTaskId (der ursprüngliche Task), state, estimatedCost (der reservierte Betrag) und deadlineAt.

• Nur Tasks mit failed oder expired lassen sich wiederholen, außerdem ältere mit canceled. Für eine weitere Fassung eines erfolgreichen Ergebnisses verwenden Sie tasks create.
• Die ursprüngliche Eingabe wird unverändert wiederverwendet; eine Wiederholung hilft also nur, wenn die Ursache vorübergehend war. Prüfen Sie zuerst errorCode; siehe Einen fehlgeschlagenen Task wiederholen und Fehler.
• Verwies die Eingabe auf eine hochgeladene Datei, die inzwischen abgelaufen ist, schlägt die Wiederholung fehl; laden Sie die Datei erneut hoch und verwenden Sie tasks create.
• Die Wiederholung übernimmt die Aufbewahrungseinstellung des ursprünglichen Tasks.
• Hat tasks create die Verbindung verloren, bevor Sie eine Task-ID gesehen haben, ist das kein fehlgeschlagener Task. Folgen Sie stattdessen den Schritten unter Einen Task nach unterbrochenem Warten wieder aufnehmen.

tasks purge

Was er tut: löscht die generierten Medien, die Ergebnisdaten (das gespeicherte Ergebnis), den Prompt und andere Eingabetexte eines beendeten Tasks endgültig, und zwar sofort, statt auf den Ablauf ihrer Fristen zu warten.

spicyapi tasks purge <task-id> [--yes]

Ein Task, der noch queued oder running ist, lässt sich nicht löschen. Abbrechen lässt er sich auch nicht, denn dafür gibt es weder einen Befehl noch eine API. Warten Sie also mit spicyapi tasks wait <task-id>, bis er fertig ist, und löschen Sie ihn dann.

Der Befehl erklärt, was gelöscht wird, und bittet Sie um Bestätigung, denn das lässt sich nicht rückgängig machen. Laden Sie vorher alles herunter, was Sie behalten möchten.

Ausgabe: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (immer true) und mediaDeletionPending, gefolgt von einer Zeile, die nennt, was vernichtet wurde, und angibt, dass die gespeicherten Medien innerhalb von etwa einer Minute entfernt werden. Steht contentState noch auf present, wurde diesmal nichts entfernt; versuchen Sie es später erneut.

Kostenlos und keine Erstattung: Der Ledger-Eintrag, der berechnete Betrag, das Modell, der Status, die Zeitstempel und die Request-ID bleiben gespeichert. Siehe Datenaufbewahrung und Löschung.

files upload

Was er tut: lädt eine Datei von Ihrem Computer hoch, etwa das Startbild für eine Bild-zu-Video-Generierung, und gibt Ihnen eine spicy://-Adresse, die Sie in Ihre Eingabe schreiben.

spicyapi files upload <path> [--content-type <type>]

Unterstützt werden Bilder im Format .jpg, .jpeg, .png, .webp und .gif bis 10 MiB, Videos im Format .mp4 und .webm sowie Audio im Format .mp3 und .wav bis 90 MiB und 600 Sekunden. Ein Modell kann eigene, niedrigere Grenzen setzen.

spicyapi files upload ./start-frame.jpg

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

Ausgabe: Kopieren Sie den Wert uri genau so, wie er ausgegeben wird, in die Dateieinstellung des Modells, häufig image_url. Er ist bis expiresAt verwendbar, normalerweise einen Tag lang. Danach laden Sie die Datei erneut hoch. Das Hochladen ist kostenlos.

files download-url

Was er tut: erstellt einen neuen Download-Link für das Ergebnis eines beendeten Tasks. Er gibt den Link aus, speichert die Datei aber nicht.

spicyapi files download-url <task-id> [--key <key>]

Ausgabe: key, url und expiresAt. Der Link funktioniert etwa 20 Minuten; öffnen Sie ihn im Browser oder laden Sie die Datei mit curl herunter. Ein Task, der noch nicht erfolgreich ist, antwortet mit „not found“. Wird die Datei noch kopiert, erhalten Sie einen Konfliktfehler; warten Sie ein paar Sekunden und versuchen Sie es erneut. Sind die Dateien des Tasks bereits gelöscht, lässt sich kein neuer Link mehr erstellen. Kostenlos.

webhooks verify

Was er tut: Betreiben Sie einen Server, der Callbacks von SpicyAPI empfängt (siehe --callback-url), prüft dieser Befehl, ob ein gespeicherter Callback echt und unverändert ist. Er läuft vollständig auf Ihrem Computer und braucht keinen API-Schlüssel.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Ausgabe: bei Erfolg payload (der Inhalt des Callbacks), payloadVersion, taskId, deliveryId (Version 2) und timestamp. Stimmt etwas nicht überein, gibt der Befehl einen Fehler aus und beendet sich mit einem Status ungleich null. Kostenlos.

Bei der Registrierung wird automatisch ein Signaturschlüssel angelegt, sein Wert wird aber nie angezeigt. Um einen zu erhalten, den Sie kopieren können, öffnen Sie in der Konsole Webhooks und klicken auf Erzeugen (oder auf Erneuern, wenn bereits einer eingerichtet ist). Der neue Schlüssel wird nur ein einziges Mal angezeigt. Das Erneuern wirkt sofort und ohne Übergangszeit: Der alte Schlüssel signiert ab diesem Moment nicht mehr. Siehe Webhooks.

Häufige Rezepte

Ein Bild generieren

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Wählen Sie mit dem ersten Befehl eine ID aus, bauen Sie input.json aus den Einstellungen, die der zweite anzeigt, führen Sie dann den dritten aus und bestätigen Sie mit y. Die Anleitung unter Ihr erstes Ergebnis erklärt jeden Schritt.

Ein Bild in ein Video verwandeln

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

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

Das hochgeladene Bild ist einen Tag lang verwendbar. Danach laden Sie es erneut hoch.

Einen Task nach unterbrochenem Warten wieder aufnehmen

Ein Task läuft weiter, auch wenn das Terminal geschlossen wird, die Netzwerkverbindung abbricht, Ihr Computer in den Ruhezustand geht oder das Warten sein Zeitlimit erreicht. Wie Sie wieder an ihn herankommen, hängt davon ab, was Sie gesehen haben:

• Sie haben Accepted: job_… gesehen oder unter dem Fehler eine Zeile Recover:. Dann haben Sie die Task-ID. Warten Sie erneut oder sehen Sie einfach nach:

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

• Sie haben nur die Zeile Idempotency-Key: gesehen, zum Beispiel weil die Verbindung abbrach, während der Task erstellt wurde. Führen Sie denselben Befehl mit demselben Modell und derselben Eingabe erneut aus und ergänzen Sie diesen Idempotenzschlüssel:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  Die CLI zeigt den Preis und fragt erneut nach. Wurde der erste Versuch aber angenommen, gibt SpicyAPI genau diesen Task zurück, statt einen zweiten zu starten und zu berechnen. Das funktioniert 24 Stunden lang mit demselben API-Schlüssel. Ist der erste Versuch nie angekommen, wird der Task jetzt erstellt, und zwar genau einmal.

• Sie haben keines von beiden. Listen Sie Ihre letzten Tasks auf und finden Sie ihn anhand von Zeitpunkt und Modell:

  spicyapi --json tasks list --limit 10

Einen fehlgeschlagenen Task wiederholen

Finden Sie zuerst heraus, warum er fehlgeschlagen ist:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Lesen Sie dann errorCode. 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. tasks retry sendet dieselbe Eingabe noch einmal und hilft deshalb nur, wenn die Ursache vorübergehend war:

Die vollständige Liste steht unter Fehler.

Ist eine Wiederholung sinnvoll, führen Sie sie aus. Sie erstellt einen neuen Task und berechnet ihn:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Ihren Verbrauch exportieren

Speichern Sie einen Monat Verbrauch des aktuellen Schlüssels in einer Datei:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

Die Datei enthält Summen pro Tag und pro Modell. Für eine Aufstellung Task für Task speichern Sie spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100 auf dieselbe Weise und folgen nextCursor, solange hasMore gleich true ist. Zahlen für das gesamte Konto und Rechnungen finden Sie in der Konsole.

Die CLI aus einem Skript ausführen

In einem Skript kann niemand Continue? [y/N] beantworten; kostenpflichtige Befehle verweigern dort deshalb die Ausführung, solange Sie nicht --yes ergänzen. Wenn Sie das tun:

• holen Sie zuerst eine Kostenschätzung ein und prüfen Sie den Preis im Skript;
• geben Sie jeder Generierung einen eigenen, festen --idempotency-key, etwa poster-2026-09-17-v1, damit ein zweiter Lauf des Skripts nicht doppelt berechnet wird;
• ergänzen Sie --json und lesen Sie state aus dem Ergebnis: Ein Befehl, der mit dem Status 0 endet, hat nicht zwingend einen erfolgreichen Task hervorgebracht;
• legen Sie in der Konsole Ausgabenlimits für den Schlüssel fest.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Kosten, Bestätigung und Sicherheit

Welche Befehle Geld kosten. Nur tasks create und tasks retry. Preise sind in US-Dollar angegeben. Kostenschätzungen einholen, auflisten, prüfen, hochladen, herunterladen und löschen ist kostenlos.

Den Preis vorher sehen. tasks quote ermittelt den Preis einer Anfrage, ohne etwas zu starten. tasks create holt eine eigene Kostenschätzung ein und zeigt Estimated charge und maximum charge, bevor es fragt. Wird der Task angenommen, wird der geschätzte Betrag reserviert (held), und das ist zugleich das Höchste, was Ihnen berechnet werden kann. Ist der Task erfolgreich, zahlen Sie für das, was tatsächlich erzeugt wurde, nie mehr als diesen Betrag, und was übrig bleibt, geht zurück in Ihr Guthaben.

Die Bestätigung. Continue? [y/N] bedeutet: Die Antwort ist nein, solange Sie nicht y tippen. --yes antwortet für Sie; verwenden Sie es also erst, wenn Sie den Preis kennen. Läuft die CLI an einer Stelle, an der sie nicht fragen kann, etwa in einem Skript oder mit per Pipe übergebener Eingabe, und fehlt --yes, verweigert sie die Ausführung, statt ein Ja anzunehmen. tasks purge fragt auf dieselbe Weise, denn Löschen lässt sich nicht rückgängig machen. tasks retry fragt ebenfalls, zeigt vorher aber keinen Preis.

Der Idempotenzschlüssel, einfach erklärt. Er ist eine Kennzeichnung für eine Generierung, ähnlich einer Bestellnummer. Jeder Aufruf von tasks create und tasks retry gibt einen aus. Bricht Ihre Internetverbindung ab und Sie wissen nicht, ob die Generierung gestartet ist, führen Sie denselben Befehl mit --idempotency-key und dem ausgegebenen Wert erneut aus: Sie erhalten den ursprünglichen Task zurück, und es wird nichts doppelt berechnet. Die Kennzeichnung gilt 24 Stunden mit demselben API-Schlüssel. Verwenden Sie sie nicht für eine andere Generierung wieder: Derselbe Idempotenzschlüssel mit einer anderen Eingabe wird abgelehnt.

Kein Abbrechen. Ist ein Task angenommen, lässt er sich nicht abbrechen. Strg + C, das Schließen des Terminals oder das Sperren des Schlüssels beendet nur das Warten; der Task läuft zu Ende und wird normal berechnet.

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.

Laden Sie herunter, was Sie behalten möchten. Ergebnisdateien werden höchstens etwa 14 Tage aufbewahrt, oder kürzer, wenn Ihr Konto oder --retention das vorgibt, und danach endgültig gelöscht. Download-Links gelten etwa 20 Minuten, Sie können aber jederzeit einen neuen anfordern, solange die Datei existiert. Hochgeladene Dateien sind einen Tag lang verwendbar. Prompt-Text wird standardmäßig nach 30 Tagen gelöscht. Abrechnungsdatensätze bleiben erhalten. Siehe Datenaufbewahrung und Löschung.

Ausgabenlimits. Jeder Schlüssel kann ein Tageslimit, ein Monatslimit und ein Gesamtlimit haben, die Sie auf der Seite API-Schlüssel einstellen. Neue Schlüssel haben kein Limit, bis Sie eines setzen. Ein Task, der ein Limit überschreiten würde, wird schon vor dem Start abgelehnt.

Ihr Schlüssel. Die CLI liest den Schlüssel ausschließlich aus SPICY_API_KEY, gibt ihn nie aus und zeigt in Fehlerhinweisen höchstens seine ersten neun Zeichen (sk-spicy-).

Mehr dazu: Abrechnung, Idempotenz, Verbindliche Tasks und Wiederholen.

Fehlerbehebung

Suchen Sie die Meldung, die Sie sehen. Fehler von SpicyAPI enden mit (request req_…); nennen Sie diesen Wert, wenn Sie sich an den Support wenden, schicken Sie aber niemals Ihren Schlüssel mit.

Jeder Fehlercode ist unter Fehler erklärt, Schritte zur Wiederherstellung finden Sie unter Fehlerbehebung und Wiederherstellung.

Quellcode

Das Paket steht unter MIT-Lizenz und wird offen unter github.com/spicyapi-ai/spicy-cli entwickelt. Dort lesen Sie den Code hinter jedem Befehl dieser Seite, melden Verhalten, das von der Beschreibung abweicht, oder schlagen eine Änderung vor.

Nächste Schritte