Tareas aceptadas y reintentos

Una vez aceptada por createTask, la tarea de generación queda comprometida y no puede cancelarse. Esta regla se aplica tanto en estado queued como en estado running: no es posible detener de forma fiable una generación una vez iniciada, por lo que SpicyAPI no ofrece una acción local que pudiera indicar una cancelación mientras el trabajo —y su costo— continúan.

Reintentar una tarea finalizada

Un reintento vuelve a ejecutar una tarea que terminó sin éxito: crea una tarea nueva con el mismo modelo, input y URL de callback, de modo que no necesitas volver a enviar el cuerpo original de la solicitud. La nueva tarea se factura como cualquier otra: su cargo estimado se retiene cuando se acepta y solo se cobra si termina correctamente.

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

Sustituye el taskId del ejemplo por el ID de tu tarea fallida. Envía siempre un Idempotency-Key con retry (por ejemplo, retry-<sourceTaskId>-1): sin esa clave, un doble clic o un reintento de red crea dos tareas facturables.

Solo deben reintentarse las tareas failed y expired. Los registros históricos canceled siguen siendo legibles y también pueden reintentarse por compatibilidad, pero las tareas nuevas no pueden pasar a ese estado mediante una acción del usuario. Una solicitud correcta crea una tarea nueva en cola y devuelve HTTP 200 (no 202, como hace 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"
}

Consulta el nuevo taskId o espera su resultado, no el de la tarea de origen; consulta Tareas asíncronas.

• La tarea de origen conserva su estado final y no cambia.
• El sourceTaskId de la nueva tarea apunta a la original, conservando la relación entre los reintentos.
• Se vuelven a comprobar el esquema actual, el precio, los permisos y el saldo. Un reintento es una tarea nueva: vuelve a entrar en cola y se procesa de forma independiente de la original.
• La nueva tarea envía su callback al mismo callBackUrl que la original y mantiene su período de conservación; un encabezado X-Spicy-Retention enviado a retry se ignora.
• Un reintento reutiliza exactamente el input de la tarea original. Los archivos de referencia subidos a SpicyAPI —incluidas las imágenes Base64 pequeñas, que se almacenan como archivos subidos— duran un día. Después, el reintento devuelve 400: vuelve a subir el archivo y crea una tarea nueva con createTask.
• El alcance de Idempotency-Key se limita a la tarea de origen y a la acción de reintento. Repetir la misma clave para la misma tarea original devuelve la misma tarea nueva en lugar de crear otra.

Cuándo se rechaza el reintento

Si retry devuelve un error, no se retienen fondos ni se realiza ningún cargo.

Matriz de estados y reintentos

Antes de reintentar, consulta errorCode. Puede ser útil reintentar rate_limited, upstream_unavailable y upstream_failed; timeout y generation_failed podrían volver a fallar de la misma manera. Con invalid_request, unsupported_combination y content_rejected, la misma entrada volverá a fallar; con invalid_asset, debes subir de nuevo el archivo de referencia. En esos casos, modifica la entrada y utiliza createTask. Consulta Códigos de fallo de tareas.