Verbindliche Tasks und Wiederholung

Sobald createTask angenommen wurde, ist der Generierungsauftrag verbindlich und kann nicht abgebrochen werden. Das gilt sowohl für queued als auch für running: Eine begonnene Generierung lässt sich nicht zuverlässig stoppen. Deshalb bietet SpicyAPI keine lokale Aktion, die einen Abbruch melden könnte, während die Arbeit – und ihre Kosten – weiterlaufen.

Einen abgeschlossenen Task wiederholen

Ein Retry führt einen abgeschlossenen erfolglosen Task erneut aus: Er erstellt einen neuen Task mit demselben Modell, input und derselben Callback-URL. Sie müssen den ursprünglichen Anfrageinhalt nicht erneut senden. Der neue Task wird wie jeder andere abgerechnet: Bei Annahme werden die geschätzten Kosten reserviert; nur bei Erfolg erfolgt eine Belastung.

POST /api/v1/jobs/retry

curl -X POST https://api.spicyapi.ai/api/v1/jobs/retry \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retry-order-8814-1" \
  -d '{"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3"}'

Ersetzen Sie die Beispiel-taskId durch die ID Ihres fehlgeschlagenen Tasks. Senden Sie bei retry immer einen Idempotency-Key, etwa retry-<sourceTaskId>-1: Ohne ihn erzeugen Doppelklick oder Netzwerkwiederholung zwei kostenpflichtige Tasks.

Wiederholen Sie nur Tasks mit failed oder expired. Historische canceled-Datensätze bleiben lesbar und können aus Kompatibilitätsgründen ebenfalls wiederholt werden; neue Tasks können diesen Zustand jedoch nicht durch Nutzeraktionen erreichen. Bei Erfolg entsteht ein neuer eingereihter Task. Die Antwort ist HTTP 200, nicht 202 wie bei createTask, mit code: 200:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3mnewtask",
    "sourceTaskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.08",
    "deadlineAt": "2026-08-28T10:12:04Z"
  },
  "request_id": "req_01k3mretry"
}

Fragen Sie die neue taskId ab oder warten Sie darauf, nicht auf die ursprüngliche. Siehe Asynchrone Tasks.

• Der ursprüngliche Task bleibt abgeschlossen und unverändert.
• Die sourceTaskId des neuen Tasks verweist auf den ursprünglichen und bewahrt die Wiederholungskette.
• Aktuelles Schema, Preis, Berechtigung und Guthaben werden erneut geprüft. Ein Retry ist ein neuer Task: Er wird erneut eingereiht und unabhängig verarbeitet.
• Der neue Task sendet seinen Callback an dieselbe callBackUrl und übernimmt die Aufbewahrungsdauer des ursprünglichen Tasks. Ein X-Spicy-Retention-Header bei retry wird ignoriert.
• Ein Retry verwendet den ursprünglichen input exakt wieder. Zu SpicyAPI hochgeladene Referenzdateien – auch kleine Base64-Bilder, die als Uploads gespeichert werden – halten einen Tag. Danach antwortet ein Retry mit 400: Laden Sie die Datei erneut hoch und erstellen einen neuen Task mit createTask.
• Idempotency-Key gilt für ursprünglichen Task und Wiederholungsaktion. Derselbe Schlüssel für denselben Ursprung liefert denselben neuen Task, statt einen weiteren zu erzeugen.

Wenn eine Wiederholung abgelehnt wird

Bei einer Fehlerantwort von retry wird nichts reserviert oder berechnet.

Zustands- und Wiederholungsmatrix

Prüfen Sie vor der Wiederholung errorCode. Bei rate_limited, upstream_unavailable und upstream_failed lohnt sich ein Retry; timeout und generation_failed können genauso erneut scheitern. Bei invalid_request, unsupported_combination und content_rejected scheitert dieselbe Eingabe wieder. Bei invalid_asset muss die Referenz erneut hochgeladen werden. Ändern Sie die Eingabe und verwenden stattdessen createTask. Siehe Taskfehlercodes.