Tareas asíncronas

Esta página describe las tareas asíncronas de generación de medios. Al crearla se reserva saldo; si tiene éxito se liquida según el uso real y en failed o expired se libera por completo. Los registros canceled históricos reciben el mismo tratamiento, pero una tarea nueva aceptada no se puede cancelar.

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

Historial de la clave actual

GET /api/v1/jobs consulta únicamente las tareas de la clave API que autentica la solicitud. No permite elegir otra clave, aunque pertenezca a la misma cuenta. La respuesta solo incluye metadatos, sin input ni output. Para obtener el resultado del taskId elegido, utiliza GET /api/v1/jobs/recordInfo.

from y to son fechas UTC que delimitan [from, to). El intervalo es de 7 días por defecto y de 92 como máximo. Puedes filtrar por state y una referencia model exacta; limit es 20 por defecto y admite hasta 100. Si hasMore es true, envía nextCursor como el siguiente cursor y conserva from, to y los demás filtros. El orden es createdAt descendente y, a igual fecha y hora, id descendente, para distinguir tareas creadas en el mismo instante. Cada página lee los estados actuales: los estados y los resultados del filtro no forman una instantánea fija.

Cuatro plazos distintos

deadlineAt es el plazo real de la tarea que devuelve el servidor. timeoutMs en el SDK solo limita la espera del cliente; no cancela una tarea aceptada. expiresAt indica la caducidad de la URL del resultado, normalmente a los 20 minutos, mientras que los medios generados se conservan 14 días. Que una URL caduque no significa que la tarea haya fallado ni que el archivo se haya borrado.

Crear una tarea

Envía model, input y, opcionalmente, callBackUrl a POST /api/v1/jobs/createTask. Emite un Idempotency-Key por solicitud lógica y reutilízalo en reintentos de red.

Interpretar el estado

En tareas nuevas, queued y running no son terminales; succeeded, failed y expired sí. El estado canceled histórico solo se conserva para lectura y compatibilidad; no es una acción disponible. Un HTTP correcto o code: 200 solo indica que la consulta funcionó. El resultado se lee en data.state.

Si output.assets[].pending es true, espera y vuelve a consultar. unavailable requiere generar de nuevo.

Webhooks y sondeo

En producción, el webhook es el canal principal. El sondeo con espera exponencial y jitter sirve de respaldo. recordInfo y webhook comparten la envoltura {code,msg,data,request_id}, por lo que pueden usar el mismo analizador.

Consulta el contrato OpenAPI 3.1 para ver la definición completa de los campos.