Impegno dell'attività e nuovo tentativo

Una volta accettata da createTask, l'attività di generazione è impegnata e non può essere annullata. La regola si applica sia quando è queued sia quando è running: la generazione non può essere fermata in modo affidabile una volta avviata, perciò SpicyAPI non espone mai un'azione locale che possa dichiarare l'annullamento mentre il lavoro, e il suo costo, proseguono.

Riprovare un'attività in stato finale

Un nuovo tentativo esegue di nuovo un'attività conclusa senza successo: crea una nuova attività con lo stesso modello, input e URL di callback, così non devi reinviare il corpo della richiesta originale. La nuova attività viene fatturata come qualsiasi altra: il costo stimato viene bloccato quando è accettata e viene addebitato soltanto se riesce.

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

Sostituisci il taskId di esempio con l'ID dell'attività fallita. Invia sempre un Idempotency-Key con retry (per esempio retry-<sourceTaskId>-1): senza, un doppio clic o una ripetizione dovuta alla rete crea due attività fatturabili.

Dovresti riprovare soltanto le attività failed ed expired. Le registrazioni storiche canceled restano leggibili e possono anch'esse essere riprovate per compatibilità con il passato, ma le nuove attività non possono entrare in quello stato attraverso un'azione dell'utente. Un nuovo tentativo riuscito crea una nuova attività in coda e restituisce HTTP 200 (non 202 come createTask), con 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"
}

Interroga o attendi il nuovo taskId, non quello sorgente; consulta Attività asincrone.

• L'attività sorgente resta nello stato finale e non cambia.
• Il sourceTaskId della nuova attività punta alla sorgente, mantenendo la relazione fra i tentativi.
• Vengono eseguiti di nuovo i controlli attuali su schema, prezzo, permessi e saldo. Un nuovo tentativo è una nuova attività: rientra in coda e viene elaborato indipendentemente dalla sorgente.
• La nuova attività invia il callback allo stesso callBackUrl dell'attività sorgente e mantiene il suo periodo di conservazione; un header X-Spicy-Retention su retry viene ignorato.
• Il nuovo tentativo riutilizza esattamente l'input dell'attività sorgente. I file di riferimento caricati su SpicyAPI, incluse le piccole immagini Base64 conservate come caricamenti, durano un giorno. Dopo, il nuovo tentativo restituisce 400: carica nuovamente il file e crea una nuova attività con createTask.
• Idempotency-Key è limitato all'attività sorgente e all'azione di nuovo tentativo. Ripetere la stessa chiave per la stessa sorgente restituisce la medesima nuova attività anziché crearne un'altra.

Quando il nuovo tentativo viene rifiutato

Non viene bloccato né addebitato nulla quando retry restituisce un errore.

Matrice degli stati e dei nuovi tentativi

Prima di riprovare, guarda errorCode. Per rate_limited, upstream_unavailable e upstream_failed vale la pena riprovare; timeout e generation_failed potrebbero fallire di nuovo nello stesso modo. Con invalid_request, unsupported_combination e content_rejected, lo stesso input fallirà di nuovo; con invalid_asset occorre caricare nuovamente il file di riferimento: cambia l'input e usa invece createTask. Consulta Codici di errore delle attività.