Tâches asynchrones

Cette page décrit les tâches asynchrones de génération de médias. Le solde est réservé à la création, réglé selon l’usage réel en cas de succès et intégralement libéré pour failed ou expired. Les anciens enregistrements canceled suivent la même règle, mais une nouvelle tâche acceptée ne peut pas être annulée.

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

Historique de la clé actuelle

GET /api/v1/jobs consulte uniquement les tâches de la clé API qui authentifie la requête. Il ne permet pas de choisir une autre clé, même sur le même compte. La réponse contient seulement des métadonnées, sans input ni output. Pour récupérer le résultat du taskId choisi, utilisez GET /api/v1/jobs/recordInfo.

from et to sont des dates UTC qui délimitent [from, to). La période couvre 7 jours par défaut et 92 au maximum. Les filtres sont state et une référence model exacte ; limit vaut 20 par défaut, avec un maximum de 100. Si hasMore vaut true, transmettez nextCursor comme cursor suivant sans changer from, to ni les autres filtres. Le tri utilise createdAt décroissant, puis id décroissant à horodatage égal, pour distinguer les tâches créées au même instant. Chaque page lit les états actuels : ni les états ni les résultats du filtrage ne constituent un instantané figé.

Quatre échéances distinctes

deadlineAt est l’échéance réelle de la tâche renvoyée par le serveur. timeoutMs dans le SDK limite uniquement l’attente du client et n’annule pas une tâche acceptée. L’URL du résultat expire généralement après 20 minutes, selon expiresAt ; les médias générés sont conservés 14 jours. Une URL expirée ne signifie ni un échec de la tâche ni la suppression du fichier.

Créer une tâche

Envoyez model, input, et éventuellement callBackUrl à POST /api/v1/jobs/createTask. Utilisez un Idempotency-Key par requête logique et réutilisez-le lors des tentatives réseau.

Interpréter les états

Pour les nouvelles tâches, queued et running ne sont pas terminaux ; succeeded, failed et expired le sont. L’ancien état canceled reste lisible uniquement par compatibilité et ne correspond pas à une action disponible. Un HTTP réussi ou code: 200 indique seulement que la consultation a réussi. Le résultat de génération se lit dans data.state.

Si output.assets[].pending vaut true, attendez puis relisez la tâche. unavailable impose une nouvelle génération.

Webhook et polling

En production, le webhook est le canal principal. Le polling avec backoff exponentiel et jitter sert de secours. recordInfo et webhook partagent la même enveloppe {code,msg,data,request_id}, donc le même parseur.

Consultez le contrat OpenAPI 3.1 pour la définition complète des champs.