> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Maestro AI Video Studio API guide - Ace Data Cloud

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](/fr/guides/maestro/maestro_videos) (`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](https://platform.acedata.cloud/console/applications) afin d’obtenir votre API Token, à conserver pour une utilisation ultérieure.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [API de requête de tâches Maestro →](https://platform.acedata.cloud/documents/maestro-tasks)

## 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](/fr/guides/maestro/maestro_videos). 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 :

```bash theme={null}
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 :

```python theme={null}
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`) :

```json theme={null}
{
  "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 :

```bash theme={null}
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 :

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/fr/guides/maestro/maestro_videos) : 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.