Asynchrone Tasks

Diese Seite beschreibt asynchrone Tasks zur Mediengenerierung. Bei der Erstellung wird Guthaben reserviert, bei Erfolg nach tatsächlicher Nutzung abgerechnet und bei failed oder expired vollständig freigegeben. Historische canceled-Datensätze werden ebenso behandelt; neu angenommene Tasks lassen sich nicht abbrechen.

API

GET /api/v1/models?includeSchema=1&includeExamples=1
# choose an item where enabled && available

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "input": { "prompt": "a folded paper lantern, hard side light" }
  }'

Task-Verlauf des aktuellen Schlüssels

GET /api/v1/jobs liest ausschließlich Tasks des API-Schlüssels, der die Anfrage authentifiziert. Auch andere Schlüssel desselben Kontos lassen sich nicht auswählen. Die Antwort enthält nur Metadaten, weder input noch output. Das Ergebnis eines ausgewählten taskId rufen Sie mit GET /api/v1/jobs/recordInfo ab.

from und to sind UTC-Kalenderdaten für das Intervall [from, to). Standardmäßig umfasst es 7 Tage, höchstens 92. Filter sind state und eine genaue model-Referenz; limit beträgt standardmäßig 20, maximal 100. Wenn hasMore true ist, übergeben Sie nextCursor als nächsten cursor und behalten from, to sowie alle übrigen Filter bei. Die Sortierung erfolgt nach createdAt absteigend und bei gleicher Zeit nach id absteigend, damit gleichzeitige Tasks eindeutig paginiert werden. Jede Seite liest den aktuellen Zustand; Status und Filterergebnisse sind kein eingefrorener Snapshot.

Vier unterschiedliche Fristen

deadlineAt ist die vom Server zurückgegebene tatsächliche Task-Frist. timeoutMs im SDK begrenzt nur die Wartezeit des Clients und storniert keinen angenommenen Task. expiresAt für die Ergebnis-URL liegt normalerweise 20 Minuten in der Zukunft; generierte Medien bleiben 14 Tage gespeichert. Eine abgelaufene URL bedeutet weder einen fehlgeschlagenen Task noch eine gelöschte Datei.

Task erstellen

Senden Sie model, input sowie optional callBackUrl an POST /api/v1/jobs/createTask. Verwenden Sie je logischer Anforderung einen Idempotency-Key und bei Netzwerk-Wiederholungen denselben Wert.

Status richtig auswerten

Bei neuen Tasks sind queued und running nicht terminal; succeeded, failed und expired sind terminal. Historisches canceled bleibt nur als lesbarer Kompatibilitätsstatus erhalten und ist keine heute verfügbare Aktion. HTTP-Erfolg oder code: 200 im Envelope bedeuten nur, dass die Abfrage gelang. Das Generierungsergebnis steht in data.state.

Bei output.assets[].pending warten Sie kurz und fragen erneut ab. unavailable bedeutet, dass eine Neugenerierung erforderlich ist.

Webhooks und Polling

Webhooks sind der primäre Produktionsweg. Polling dient mit exponentiellem Backoff und Jitter als Rückfallebene. recordInfo und Webhook verwenden dasselbe {code,msg,data,request_id}-Envelope und können denselben Parser nutzen.

Die vollständigen Felddefinitionen stehen im OpenAPI-3.1-Vertrag.