Engagement des tâches et relance

Une fois createTask accepté, la tâche de génération est engagée et ne peut plus être annulée. Cette règle s’applique en queued comme en running : une génération commencée ne peut pas être arrêtée de façon fiable. SpicyAPI ne propose donc jamais une action locale qui annoncerait une annulation alors que le travail, et son coût, continuent.

Relancer une tâche terminée

Une relance exécute de nouveau une tâche terminée sans succès : elle crée une nouvelle tâche avec le même modèle, la même valeur input et la même URL de callback, sans vous obliger à renvoyer le corps de la requête originale. La nouvelle tâche est facturée comme toute autre : son montant estimé est réservé à l’acceptation et elle n’est facturée que si elle réussit.

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"}'

Remplacez le taskId d’exemple par l’ID de votre tâche échouée. Envoyez toujours un Idempotency-Key avec retry, par exemple retry-<sourceTaskId>-1 : sans cette clé, un double clic ou une nouvelle tentative réseau crée deux tâches facturables.

Seules les tâches failed et expired doivent être relancées. Les anciennes traces canceled restent lisibles et peuvent aussi être relancées par rétrocompatibilité, mais aucune nouvelle tâche ne peut atteindre cet état par une action utilisateur. En cas de succès, l’opération crée une nouvelle tâche en attente et renvoie HTTP 200, et non 202 comme createTask, avec 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"
}

Interrogez le nouveau taskId ou attendez son résultat, pas celui de la source ; voir Tâches asynchrones.

• La tâche source reste terminée et inchangée.
• Le sourceTaskId de la nouvelle tâche pointe vers la source pour conserver l’historique des relances.
• Le schéma, le tarif, les permissions et le solde actuels sont vérifiés de nouveau. Une relance est une nouvelle tâche : elle revient en file d’attente et est traitée indépendamment de sa source.
• La nouvelle tâche envoie son callback à la même callBackUrl que la source et garde la durée de conservation de celle-ci ; un en-tête X-Spicy-Retention envoyé à retry est ignoré.
• Une relance réutilise exactement l’input de la source. Les fichiers de référence envoyés à SpicyAPI, y compris les petites images Base64 stockées comme fichiers envoyés, durent un jour. Ensuite, une relance renvoie 400 : envoyez de nouveau le fichier et créez une tâche avec createTask.
• Idempotency-Key est limité à la tâche source et à l’action de relance. Répéter la même clé pour la même source renvoie la même nouvelle tâche au lieu d’en créer une autre.

Quand une relance est refusée

Aucun montant n’est réservé ni facturé lorsque retry renvoie une erreur.

États et possibilités de relance

Avant une relance, examinez errorCode. rate_limited, upstream_unavailable et upstream_failed justifient une nouvelle tentative ; timeout et generation_failed peuvent échouer à nouveau de la même façon. Pour invalid_request, unsupported_combination et content_rejected, la même entrée échouera à nouveau. Pour invalid_asset, le fichier de référence doit être renvoyé : modifiez l’entrée et utilisez plutôt createTask. Voir Codes d’échec des tâches.