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 renseignezapplication/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 renseignezapplication/json.
Exemple de code
Le code CURL 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 tableauvariants contient une vidéo finale) :
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 sontpending → planning → producing → succeeded(oufailed). Pour savoir si la tâche est terminée, référez-vous au champstatusde 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 ;stageetmessagereflètent l’événement de progression le plus récent du réalisateur IA (par conséquent, après une réussite,stagepeut encore correspondre à la dernière étape d’exécution, telle queproducing) 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, incluantlang,aspect,title,output_url(URL de téléchargement de la vidéo finale), etc.data.project: artefacts de l’ensemble du projet, incluanttarball_url(package du projet) etoutputs(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
Transmettezaction: 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 :count: le nombre total de tâches visibles pour l’exécuteur actuellement connecté, non affecté par les conditions temporelles oulimit.items: le tableau de tâches filtré selon les conditions temporelles etlimit, 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, lestatus 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, letask_idfourni 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
- Instructions d’intégration de l’API de génération de vidéos Maestro : produisez automatiquement une vidéo finale avec sous-titres à l’aide d’une invite en langage naturel, récupérez le
task_idaprès soumission, puis utilisez cette interface pour sonder le résultat.

