Tâches

Chaque génération est une tâche. Vous la créez en un appel, elle tourne d’elle-même, et vous récupérez le résultat quand il est prêt — en le demandant, en attendant dès le premier appel, ou en recevant un webhook.

Créer une tâche

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "alibaba/wan-3.0/image-to-video",
    "input": {
      "image_url": "https://media.popnow.ai/movie/lighthouse.webp",
      "prompt": "Waves roll in slowly, the camera drifts toward the lighthouse",
      "resolution": "480p",
      "duration_seconds": 5
    },
    "callBackUrl": "https://your-app.example.com/hooks/popnow"
  }'

Corps

En-têtes

Réponse

Une nouvelle tâche revient en HTTP 202 :

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01JH8Z4Q5W2N7R3K9M6P1C0VXD",
    "state": "queued",
    "estimatedCredits": 34,
    "estimatedCost": "0.34",
    "deadlineAt": "2026-10-16T09:40:00Z"
  },
  "request_id": "req_…"
}

202 signifie acceptée, pas terminée. estimatedCredits est le montant réservé sur votre solde — le maximum que cette tâche peut coûter (estimatedCost donne le même montant en dollars US). Si la création échoue, rien n’est créé ni réservé ; le code vous dit pourquoi (Erreurs).

États

Considérez tout état inconnu comme « pas encore terminé » et continuez à interroger.

Éviter le polling avec wait

Ajoutez ?wait=<secondes> (60 au maximum) à createTask : la connexion reste ouverte jusqu’à la fin de la tâche ou l’épuisement du délai.

• Terminée à temps → HTTP 200 avec l’enregistrement complet de la tâche, au même format que recordInfo. Vérifiez data.state : final ne veut pas toujours dire réussi.
• Pas terminée → le 202 habituel, et vous continuez à interroger ou attendez le webhook.

Idéal pour les images et les audios courts ; une vidéo dépasse presque toujours 60 secondes. Couper la connexion plus tôt n’arrête ni n’annule la tâche.

Lire une tâche

curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=job_01JH8Z4Q5W2N7R3K9M6P1C0VXD" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Trois échéances différentes

• deadlineAt — la durée pendant laquelle la tâche peut tourner. Au-delà, elle passe en expired et la réservation est libérée.
• output.assets[].expiresAt — la durée de validité de ce lien signé, une vingtaine de minutes. Relisez la tâche pour un nouveau lien ; le fichier, lui, est toujours là.
• retention.outputsExpireAt — le moment où le fichier stocké est supprimé. Téléchargez avant ce qui doit être conservé, ou enregistrez-le dans votre bibliothèque de ressources.

Ce que contient output

La plupart des tâches renvoient un seul fichier. Certaines en renvoient davantage : plusieurs images quand le modèle produit des variantes, le clip assemblé puis le nouveau segment pour une extension vidéo (role: "video" puis role: "segment"), ou une image de base plus des calques transparents pour la séparation en calques (chacun avec un objet layer). La transcription audio arrive dans output.text.

Les liens des fichiers sont des liens au porteur : quiconque possède l’URL peut télécharger le fichier jusqu’à son expiration. N’envoyez pas votre clé API en les récupérant.

Les webhooks d’abord, le polling en secours

Le polling fonctionne, mais un webhook coûte moins cher aux deux parties : vous apprenez le résultat dès qu’il existe et ne dépensez aucune requête entre-temps. Une intégration solide combine les deux — les webhooks pour le cas normal, et de temps en temps un passage recordInfo pour les tâches dont le webhook n’est pas arrivé.

Si vous interrogez, espacez : toutes les 2 à 3 secondes pour les images, toutes les 10 à 15 secondes pour la vidéo, et arrêtez à deadlineAt.

La liste des tâches

GET /api/v1/jobs renvoie les tâches créées par cette clé, les plus récentes d’abord, sans entrées ni résultats :

curl "https://api.popnow.ai/api/v1/jobs?state=failed&from=2026-10-01&limit=50" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Filtres : from et to (dates UTC, 92 jours d’écart au maximum ; par défaut les sept derniers jours), state, model, limit (100 au maximum). Quand hasMore vaut true, renvoyez nextCursor dans cursor avec les mêmes filtres.

Relancer une tâche en échec

POST /api/v1/jobs/retry avec { "taskId": "…" } crée une nouvelle tâche à partir d’une tâche failed ou expired, avec son entrée d’origine et au prix du jour. La tâche d’origine n’est jamais modifiée. La réponse est 409 tant que la tâche source n’est pas finale ; une tâche réussie ne peut pas être relancée — créez-en une nouvelle.

Supprimer le contenu d’une tâche

POST /api/v1/jobs/purge avec { "taskId": "…" } supprime les fichiers, le résultat et le prompt enregistré de la tâche. L’enregistrement de facturation reste : le montant, le modèle, l’état et les horodatages demeurent, et la réponse le confirme avec billingRetained: true. Seules les tâches terminées peuvent être purgées, et répéter l’appel est sans risque.

Et ensuite

• Webhooks — recevoir les résultats au lieu d’interroger.
• Médias — envoyer vos propres fichiers de référence.
• Erreurs — chaque code, et s’il faut réessayer.