Passer au contenu principal
La fonction principale de l’API de requête de tâches Maestro est d’interroger l’état d’exécution et le résultat final d’une tâche à l’aide de l’ID de tâche renvoyé par l’API de génération de vidéos Maestro (POST /maestro/videos). Ce document présentera en détail la documentation d’intégration de l’API de requête de tâches Maestro. Étant donné que la génération de vidéos est une tâche asynchrone, après la soumission, cette interface doit être utilisée pour interroger la progression et la vidéo finale, l’interrogation est gratuite et ne consomme pas de crédits. POST https://api.acedata.cloud/maestro/tasks

Processus de demande

Pour utiliser l’API de requête de tâches Maestro, commencez par obtenir votre API Token dans la console Ace Data Cloud, afin de le conserver pour une utilisation ultérieure. Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement à la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans nécessiter une demande distincte pour chaque service. La première demande offre un quota gratuit pour une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde commun dans la console.
📘 Documentation complète : API de requête de tâches Maestro →

Interroger une tâche unique

Pour savoir comment créer une tâche vidéo, veuillez consulter la documentation API de génération de vidéos Maestro. Nous prenons comme exemple l’un des ID de tâche qu’elle renvoie : f57e99c4f60f4373a15517742ce2357d, pour démontrer comment interroger son état et son résultat.

Définir les en-têtes et le corps de la requête

Les Request Headers incluent :
  • accept : spécifie la réception de résultats de réponse au format JSON, ici renseignez application/json.
  • authorization : la clé pour appeler l’API, qui peut être directement sélectionnée dans la liste déroulante après la demande.
  • content-type : le format du corps de la requête, ici renseignez application/json.
Le Request Body inclut :

Exemple de code

Le code CURL correspondant est le suivant :
Le code Python correspondant est le suivant :

Exemple de réponse

Une fois la requête réussie, l’API renvoie l’état et le résultat de cette tâche vidéo. Voici un exemple de réponse lorsque la tâche est terminée (le tableau variants contient une vidéo finale) :
Les champs du résultat renvoyé sont décrits ci-dessous :
  • id : l’ID de cette tâche vidéo, utilisé pour identifier de manière unique cette tâche de génération vidéo.
  • status : l’état de la tâche ; les valeurs possibles sont pending → planning → producing → succeeded (ou failed). Pour savoir si la tâche est terminée, référez-vous au champ status de niveau supérieur.
  • elapsed : durée écoulée de la tâche (en secondes).
  • progress : objet de progression de niveau supérieur. percent (0–100) vaut 100 lorsque la tâche réussit ; stage et message reflètent l’événement de progression le plus récent du réalisateur IA (par conséquent, après une réussite, stage peut encore correspondre à la dernière étape d’exécution, telle que producing) et peuvent être utilisés directement pour afficher une barre de progression.
  • request : corps de la requête lors du lancement de la tâche.
  • response : informations de retour de la tâche.
    • success : indique si la tâche a réussi.
    • data.variants : contient un objet de vidéo finale dans la langue sélectionnée, incluant lang, aspect, title, output_url (URL de téléchargement de la vidéo finale), etc.
    • data.project : artefacts de l’ensemble du projet, incluant tarball_url (package du projet) et outputs (lien vers la vidéo finale).
    • data.progress : tableau d’événements de progression ajoutés par étape (journal en ajout uniquement), utilisable pour afficher une progression détaillée en temps réel.
  • created_at : heure de création de la tâche, horodatage Unix (secondes).
  • started_at : heure de début d’exécution de la tâche, horodatage Unix (secondes). La valeur est null si la tâche n’a pas encore commencé.
  • finished_at : heure de fin de la tâche, horodatage Unix (secondes). La valeur est null si la tâche n’est pas terminée.

Interroger la liste de l’historique

Transmettez action: retrieve_batch pour obtenir les tâches récentes de l’exécutant actuellement connecté (par ordre décroissant de création), ce qui peut être utilisé pour la page de liste « Mes vidéos ». La liste de l’historique est isolée selon l’identité de connexion. Le Request Body inclut :

Exemple de code

Le code CURL correspondant est le suivant :

Exemple de réponse

Après une requête réussie, l’API renverra la liste des tâches historiques de l’utilisateur actuel :
Les champs du résultat retourné sont décrits comme suit :
  • count : le nombre total de tâches visibles pour l’exécuteur actuellement connecté, non affecté par les conditions temporelles ou limit.
  • items : le tableau de tâches filtré selon les conditions temporelles et limit, trié par ordre décroissant de date de création ; le format de chaque élément est identique au résultat retourné par « Consulter une tâche unique ».

Recommandations de sondage

Comme la production de vidéos prend relativement longtemps, le status passera par pending → planning → producing → succeeded (ou failed). Il est recommandé d’effectuer un sondage toutes les 5 à 10 secondes, jusqu’à ce que le status devienne succeeded ou failed. Vous pouvez utiliser le progress.percent de niveau supérieur pour afficher une barre de progression en temps réel. Le sondage de cette interface est gratuit et ne consomme pas de crédits.

Gestion des erreurs

Lors de l’appel de l’API, si une erreur se produit, l’API renverra le code d’erreur et les informations correspondantes. Par exemple :
  • 401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
  • 404 not_found : Tâche introuvable, le task_id fourni n’existe pas.
  • 429 too_many_requests : Trop de requêtes, vous avez dépassé la limite de débit.
  • 500 api_error : Erreur interne du serveur, un problème est survenu sur le serveur.

Exemple de réponse d’erreur

Conclusion

Grâce à ce document, vous avez appris à utiliser l’API de consultation des tâches Maestro pour consulter l’état et le résultat d’une tâche unique, ainsi que pour récupérer la liste des tâches historiques de l’utilisateur actuel. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, veuillez contacter notre équipe d’assistance technique à tout moment.

Interfaces associées