Documentation d’intégration de l’API de requête de tâches Maestro

La fonction principale de l’API de requête de tâches Maestro consiste à utiliser l’ID de tâche renvoyé par l’API de génération de vidéos Maestro (POST /maestro/videos) pour interroger l’état d’exécution et le résultat final de cette tâche. Ce document présentera en détail la documentation d’intégration de l’API de requête de tâches Maestro. La génération de vidéos étant une tâche asynchrone, après la soumission, vous devez utiliser cette interface pour interroger régulièrement la progression et la vidéo finale, les interrogations régulières sont gratuites et ne consomment 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, rendez-vous d’abord sur la console Ace Data Cloud afin d’obtenir votre API Token, à conserver pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion afin de vous inviter à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement sur la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin de faire une demande distincte pour chaque service. Lors de votre première demande, un quota gratuit vous sera offert afin de pouvoir essayer le service gratuitement ; lorsque le quota est insuffisant, vous pouvez recharger votre solde universel 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 de l’API de génération de vidéos Maestro. Nous prendrons comme exemple l’un des ID de tâche qu’elle renvoie : f57e99c4f60f4373a15517742ce2357d, afin de 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, à renseigner ici avec 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, à renseigner ici avec application/json.

Les Request Body incluent :

Champ	Type	Obligatoire lors de	Description
`id`	string	l’interrogation d’une tâche unique	Le `task_id` renvoyé par `POST /maestro/videos`
`action`	string	Non	`retrieve` (par défaut, interroge une tâche unique) ; fixé à `retrieve_batch` lors de l’interrogation de la liste d’historique

Exemple de code

Le code CURL correspondant est le suivant :

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

Le code Python correspondant est le suivant :

import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Exemple de réponse

Une fois la requête réussie, l’API renverra l’état et le résultat de cette tâche vidéo. L’exemple de retour lorsque la tâche est terminée est le suivant (chaque langue correspond à un variant) :

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

Les champs du résultat renvoyé sont présentés comme suit :

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, avec les valeurs pending → planning → producing → succeeded (ou failed). La fin de la tâche est déterminée par ce status de niveau supérieur.
elapsed : le temps écoulé de la tâche (secondes).
progress : l’objet de progression de niveau supérieur ; percent (0–100) sera complété à 100 après la réussite de la tâche ; stage et message reflètent le dernier événement de progression du réalisateur IA (ainsi, après la réussite, stage peut encore correspondre à la dernière étape d’exécution telle que producing), et peuvent être directement utilisés pour afficher une barre de progression.
request : le corps de la requête lors du lancement de la tâche.
response : les informations de retour de la tâche.
- success : indique si la tâche a réussi.
- data.variants : chaque langue correspond à un objet de vidéo finale, comprenant notamment lang, aspect, title, output_url (adresse de téléchargement de la vidéo finale).
- data.project : les livrables de l’ensemble du projet, comprenant tarball_url (package du projet) et outputs (tous les liens des vidéos finales).
- data.progress : un tableau d’événements de progression ajoutés par étape (journal append-only), qui peut être utilisé pour afficher la progression détaillée en temps réel.
created_at : l’heure de création de la tâche, horodatage Unix (secondes).
started_at : l’heure de début d’exécution de la tâche, horodatage Unix (secondes). Elle est null lorsque la tâche n’a pas encore commencé.
finished_at : l’heure de fin de la tâche, horodatage Unix (secondes). Elle est null lorsque la tâche n’est pas terminée.

Interroger la liste d’historique

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

Champ	Type	Obligatoire	Description
`action`	string	Oui	Fixé à `retrieve_batch`
`limit`	int	Non	Nombre d’éléments retournés, 20 par défaut ; la plage valide est de 1 à 100
`created_at_max`	int	Non	Retourne uniquement les tâches strictement antérieures à cet horodatage Unix (valeur limite non incluse, pour la pagination)
`created_at_min`	int	Non	Retourne uniquement les tâches strictement postérieures à cet horodatage Unix (valeur limite non incluse)

Exemple de code

Le code CURL correspondant est le suivant :

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

Exemple de réponse

Une fois la requête réussie, l’API renverra la liste des tâches historiques de l’utilisateur actuel :

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

Les champs du résultat retourné sont présentés ci-dessous :

count : le nombre total de tâches visibles par l’exécutant actuellement connecté, non affecté par les conditions temporelles ou limit.
items : le tableau de tâches filtrées selon les conditions temporelles et limit, triées 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 vidéo prend du temps, status passera par pending → planning → producing → succeeded (ou failed). Il est recommandé d’effectuer un sondage toutes les 5 à 10 secondes, jusqu’à ce que status devienne succeeded ou failed. Vous pouvez utiliser progress.percent au 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 survient, l’API renverra le code et le message d’erreur correspondants. 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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Grâce à ce document, vous savez désormais comment utiliser l’API de consultation des tâches Maestro pour consulter le statut et les résultats 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. Pour toute question, veuillez contacter notre équipe de support technique à tout moment.

Interfaces connexes

Instructions d’intégration de l’API de génération vidéo Maestro : utilisez une phrase d’invite en langage naturel pour produire automatiquement une vidéo finale avec sous-titres ; après soumission, un task_id est renvoyé, puis utilisez cette interface pour sonder le résultat.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Documentation d’intégration de l’API de requête de tâches Maestro

Processus de demande

Interroger une tâche unique

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

Exemple de code

Exemple de réponse

Interroger la liste d’historique

Exemple de code

Exemple de réponse

Recommandations de sondage

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

Interfaces connexes

​Processus de demande

​Interroger une tâche unique

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

​Exemple de code

​Exemple de réponse

​Interroger la liste d’historique

​Exemple de code

​Exemple de réponse

​Recommandations de sondage

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

​Interfaces connexes

Processus de demande

Interroger une tâche unique

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

Exemple de code

Exemple de réponse

Interroger la liste d’historique

Exemple de code

Exemple de réponse

Recommandations de sondage

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

Interfaces connexes