Skip to main content
La génération vidéo et la génération d’images par lots dépassent généralement la durée d’attente raisonnable d’une connexion HTTP. Pendant une génération de texte longue, si le client se déconnecte, la réponse déjà produite ne peut plus être récupérée. Les tâches asynchrones (Async Tasks) réunissent ces trois scénarios autour d’un même objet tâche : les images et les vidéos créent une tâche via l’interface de génération et renvoient immédiatement un task_id ; les requêtes LLM interrompues côté client sont menées à leur terme par la plateforme, qui enregistre la réponse finale. Les trois partagent les mêmes statuts de tâche, la même interface d’interrogation et le même processus de téléchargement des résultats.
Utilisez la même clé API que celle ayant servi à créer la tâche pour interroger celle-ci et télécharger les résultats. Les tâches sont isolées par clé API : même si deux clés appartiennent au même compte, elles ne peuvent pas lire les tâches l’une de l’autre.

Activer les tâches asynchrones dans la console

Avant de créer une image ou une vidéo asynchrone, activez la fonctionnalité de tâches asynchrones pour le compte courant. Si l’entrée correspondante n’apparaît pas encore dans la console, contactez le support technique AIHubMix.
Lorsque la fonctionnalité de tâches asynchrones n’est pas activée, les requêtes de création de tâche média renvoient 403 async_not_enabled. Les requêtes LLM ne renvoient pas d’erreur pour autant, mais la réponse finale ne peut pas être récupérée après une interruption du client.

1. Démarrage rapide

Le processus complet d’une tâche asynchrone d’image ou de vidéo comporte trois étapes :

2. Comparaison entre appel synchrone et tâche asynchrone

Un appel synchrone renvoie le résultat dans une seule réponse HTTP, et le résultat ne peut plus être récupéré après une coupure de connexion. Une tâche asynchrone conserve le résultat côté plateforme : le task_id permet de l’interroger et de le télécharger à nouveau avec la même clé API avant expiration du résultat. Ce mode convient aux requêtes de génération longues, ainsi qu’aux sorties de texte longues dont la réponse finale doit rester récupérable après une interruption.

3. Vue d’ensemble des interfaces

Base URL : https://aihubmix.com, avec une authentification par Bearer Token :
/ai/v1/tasks est un point d’entrée d’interrogation unifié en lecture seule ; POST /ai/v1/tasks n’est pas proposé. Les images et les vidéos se créent via leur interface de génération respective. Les requêtes qui remplissent les conditions de la reprise après interruption LLM sont automatiquement enregistrées comme tâches llm après une interruption du client.

4. Modèles pris en charge

Les tâches asynchrones définissent leur périmètre de prise en charge par type de tâche, sans paramètre supplémentaire à l’appel.

4.1 Image asynchrone

4.2 Vidéo asynchrone

4.3 Reprise après interruption LLM

La liste des modèles pris en charge continue de s’étendre, et ce tableau est mis à jour en conséquence.

5. Comment créer une tâche asynchrone

5.1 Image asynchrone

L’interface d’images renvoie le résultat de façon synchrone par défaut. Lorsque async vaut true, l’interface renvoie immédiatement l’objet tâche et la génération se poursuit en arrière-plan.
async doit être un booléen. S’il est absent ou défini à false, l’interface d’images conserve son comportement synchrone.

5.2 Vidéo asynchrone

L’interface vidéo est toujours asynchrone. Après une création réussie, elle renvoie le statut pending ou in_progress ; le passage en attente synchrone via Prefer: wait n’est pas pris en charge.

5.3 Paramètres communs

Dans les exemples, model, prompt, n, seconds et size sont des paramètres de modèle courants. Les champs et valeurs pris en charge dépendent de chaque modèle et font foi dans sa documentation API ; pour les modèles vidéo, voir la documentation de génération vidéo. Le tableau ci-dessous décrit uniquement les paramètres communs à toutes les tâches asynchrones.
Les tâches d’image ne peuvent utiliser un Webhook que si async: true. Si webhook_events_filter est omis, la plateforme notifie les trois statuts finaux completed, failed et cancelled. Lorsqu’il est fourni, il doit être utilisé avec webhook_url, et il ne peut être ni vide ni contenir de doublons.

6. Comment fonctionne la reprise après interruption LLM

La reprise après interruption LLM sert à récupérer la réponse finale après la déconnexion du client. Cette capacité réutilise le mode d’appel LLM existant : le comportement en streaming et le format de réponse restent inchangés, aucune interface de création supplémentaire n’est nécessaire et aucun task_id n’est renvoyé à l’avance.

6.1 Conditions d’activation

Les conditions suivantes doivent être remplies simultanément : Interfaces prises en charge :
Aucun champ supplémentaire n’est à passer lors de l’appel. La liste des modèles pris en charge figure en 4.3 Reprise après interruption LLM. Pour un modèle absent de ce tableau, validez la reprise après interruption avec une requête à faible coût avant la mise en production ; cette requête de validation reste facturée normalement. Si l’une des conditions n’est pas remplie, la requête s’exécute quand même normalement et aucune tâche llm n’est créée après l’interruption du client.

6.2 Déroulement après une interruption

Les requêtes LLM qui se terminent normalement et dont la réponse est bien remise au client ne créent aucune tâche et n’apparaissent pas dans la liste des tâches. Une requête interrompue apparaît dans la liste une fois la réponse finale enregistrée ; elle peut donc rester temporairement introuvable pendant le traitement.

6.3 Retrouver la requête interrompue correspondante

Les réponses LLM renvoient l’en-tête X-Aihubmix-Request-Id. Le client doit enregistrer cette valeur dès la réception des en-têtes. Après une interruption, cet identifiant de requête permet de retrouver la tâche correspondante dans la liste des tâches asynchrones de la console AIHubMix. L’API publique des tâches ne permet pas actuellement de filtrer par identifiant de requête. Si l’identifiant n’a pas été enregistré, la recherche s’effectue par modèle et date de création, avec la même clé API que celle utilisée pour créer la requête :
Lorsqu’une même clé API envoie plusieurs requêtes concurrentes vers le même modèle, le modèle et la date de création ne suffisent pas à garantir une correspondance exacte. Pour une reprise fiable, enregistrez X-Aihubmix-Request-Id et effectuez la recherche depuis la console. Si les en-têtes de réponse n’ont pas été obtenus, évitez de considérer directement la tâche la plus récente de la liste comme celle de la requête concernée.
Les tâches de reprise après interruption LLM n’envoient pas de Webhook pour le moment ; consultez le résultat via la liste des tâches. Une interruption du client n’arrête pas le traitement de la requête par la plateforme, et cet appel reste facturé selon les règles de l’interface LLM d’origine.

7. Objet tâche et statuts

Toutes les tâches utilisent une structure de réponse unifiée :
Champs des résultats contenus dans output :

7.1 Description des statuts

Il est recommandé d’interroger toutes les 15 secondes, jusqu’à ce que le statut passe à completed, failed ou cancelled.
Une tâche failed ou cancelled peut également contenir des résultats partiels déjà générés. Pour savoir s’il existe un résultat, vérifiez aussi si output est vide, en plus du statut.

8. Comment interroger les tâches

8.1 Consulter le détail d’une tâche

Cette interface renvoie les informations de tâche les plus récentes au moment de l’interrogation. L’interrogation ne modifie pas la tâche ; le statut est mis à jour automatiquement par la plateforme.

8.2 Lister les tâches

Si la réponse de création a été perdue, ou pour consulter par lot l’historique des tâches, l’interface de liste permet de retrouver le task_id :
Exemple de réponse :
Requête de la page suivante :

9. Comment récupérer les résultats d’une tâche

9.1 Tâche à un seul fichier produit

Lorsque output ne contient qu’un seul fichier, l’accès est direct :
Il est également possible d’utiliser directement output[0].content_url. Le Content-Type de la réponse de téléchargement correspond à output[0].content_type.

9.2 Tâche à plusieurs fichiers produits

Lorsque output contient plusieurs fichiers, le result_id correspondant doit être précisé :
Si le result_id n’est pas précisé pour une tâche à plusieurs fichiers produits, l’interface renvoie 400 result_id_required.

9.3 Tâche de réponse LLM

Lorsque les conditions de la reprise après interruption LLM sont remplies et que la réponse a été enregistrée, l’object de la tâche vaut llm et le type de l’élément d’output vaut response. Le type de contenu peut être :
  • application/json : réponse JSON standard
  • text/event-stream : réponse en streaming SSE enregistrée
L’indicateur de troncature se trouve dans output[0].truncated du détail de la tâche. La valeur true signifie que la réponse enregistrée a été tronquée en raison de la limite de taille. GET /ai/v1/tasks/{task_id}/content renvoie le contenu JSON ou SSE d’origine, sans champ truncated ajouté autour du contenu ; il convient donc de consulter d’abord le détail de la tâche, puis de lire le contenu.
Les résultats peuvent expirer, et un nombre maximal de téléchargements peut s’appliquer. Enregistrez-les à temps avant expires_at. Un résultat expiré renvoie 410 artifact_expired ; le dépassement de la limite de téléchargements renvoie 429 too_many_downloads.

10. Comment utiliser les Webhooks

Un Webhook au niveau de la tâche peut actuellement être fourni lors de la création d’une tâche asynchrone. Pour être notifié par AIHubMix une fois la tâche terminée, passez webhook_url et éventuellement webhook_events_filter dans le corps de la requête d’image ou de vidéo asynchrone :
L’adresse de rappel doit utiliser HTTPS et ne peut pas pointer vers la machine locale, un réseau privé ou une autre adresse restreinte.

10.1 Requête de rappel

AIHubMix envoie une requête POST à l’adresse de rappel :
Les URL de results requièrent toujours la clé API ayant créé la tâche pour y accéder.

10.2 Nouvelles tentatives et déduplication

La plateforme tente au moins une livraison du rappel, un même événement peut donc être envoyé plusieurs fois :
  • HTTP 2xx indique une réception réussie.
  • HTTP 5xx, une erreur réseau ou un dépassement de délai déclenchent une nouvelle tentative.
  • HTTP 3xx et 4xx ne déclenchent pas de nouvelle tentative.
  • 6 livraisons au maximum, avec des intervalles successifs de 1, 4, 16, 64 et 256 secondes.
Le destinataire doit enregistrer event_id. À la réception d’un event_id déjà connu, ignorez le traitement métier et renvoyez directement 2xx.
Le Webhook au niveau de la tâche ne fournit pas actuellement d’identifiant de signature dédié et configurable. Après réception d’une notification, appelez GET /ai/v1/tasks/{task_id} avec la clé API ayant créé la tâche et considérez le résultat de cette interrogation comme faisant foi.

11. Réponses d’erreur et codes d’erreur

Les réponses d’erreur utilisent une structure unifiée :

12. Exemple complet

Processus complet de création d’une tâche vidéo, d’interrogation par polling et de téléchargement de tous les résultats :

Questions fréquentes

À quelle fréquence interroger le statut d’une tâche ? Il est recommandé d’interroger toutes les 15 secondes, afin d’éviter un polling à haute fréquence. Même avec un Webhook, conservez une interrogation à basse fréquence en secours. Comment retrouver une tâche après la perte de la réponse de création ? Appelez GET /ai/v1/tasks avec la même clé API que celle ayant créé la tâche. Les filtres object, model et status permettent de restreindre la recherche. Pourquoi une autre clé API du même compte ne trouve-t-elle pas la tâche ? Les tâches sont isolées par clé API. Les requêtes d’interrogation, de téléchargement et de liste doivent toutes utiliser la clé ayant servi à créer la tâche. Pourquoi output n’est-il pas un tableau vide alors que la tâche a échoué ? Certains modèles peuvent avoir généré des résultats exploitables avant l’échec ou l’annulation globale de la tâche. Dès qu’output contient content_url ou b64_json, le résultat peut être récupéré par la méthode correspondante. Que faire si le Webhook n’est pas reçu ? Vérifiez que l’adresse de rappel est accessible publiquement, qu’elle utilise HTTPS et qu’elle renvoie 2xx en moins de 10 secondes. Avec ou sans Webhook, le statut final reste consultable via GET /ai/v1/tasks/{task_id}. La reprise après interruption LLM impose-t-elle de modifier le code existant ? Non. Le mode d’appel, le comportement en streaming et le format de réponse restent inchangés. Il est recommandé d’enregistrer l’en-tête de réponse X-Aihubmix-Request-Id, afin de localiser précisément la tâche correspondante dans la console après une interruption.
Date de mise à jour : 2026-07-28