> ## 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.

# Maestro API de génération vidéo - Instructions d'intégration

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro est une interface de production vidéo **nativement Agent** : vous décrivez le vidéo souhaité avec une phrase en langage naturel `prompt` (avec des `file_urls` en option pour joindre des images / vidéos / audios de référence), un « réalisateur AI » sans tête complétera automatiquement le sujet, écrira le script, générera les images, la voix off, la musique, la composition et le rendu, produisant finalement un produit final sous-titré et le téléchargeant sur le CDN.

Cet article détaillera les instructions d'intégration de l'API de génération vidéo Maestro, vous aidant à vous intégrer rapidement et à tirer pleinement parti des capacités de cette API.

C'est une interface de **tâche asynchrone** : après soumission, un `task_id` sera immédiatement renvoyé, puis vous pourrez interroger les résultats via [l'API de requête de tâche Maestro](/fr/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) (les requêtes de sondage ne sont pas facturées). Pour continuer à itérer sur une vidéo existante, vous pouvez utiliser `action: remix` / `edit` / `extend` avec `ref_task_id`.

## Processus de demande

Pour utiliser l'API de génération vidéo Maestro, commencez par obtenir votre API Token sur [le tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour le garder en réserve.

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

Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion vous invitant à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle.

**Un seul API Token suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander séparément pour chaque service.** La première demande vous donnera un quota gratuit, vous permettant de l'essayer gratuitement ; lorsque le quota est insuffisant, vous pouvez recharger le solde général dans [le tableau de bord](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [API de génération vidéo Maestro →](https://platform.acedata.cloud/documents/maestro-videos)

## Utilisation de base

`POST https://api.acedata.cloud/maestro/videos`

L'utilisation de base nécessite simplement de transmettre un `prompt` en langage naturel, le réalisateur AI décidera automatiquement du script, des images, de la voix off et du montage. Ici, nous allons d'abord examiner les en-têtes de requête et le corps de la requête à configurer.

**Request Headers** incluent :

* `accept` : le format de réponse souhaité, ici à remplir avec `application/json`, c'est-à-dire au format JSON.
* `authorization` : la clé d'API pour appeler l'API, que vous pouvez sélectionner directement après la demande.
* `content-type` : le format du corps de la requête, ici à remplir avec `application/json`.

**Request Body** comprend principalement :

* `prompt` : décrire en langage naturel la vidéo à réaliser (thème, ce qui doit être montré, style, public).
* `langs` : tableau des langues de sortie, comme `["zh-cn", "en"]`, par défaut `["zh-cn"]`.
* `aspect` : rapport d'image, `9:16` (par défaut) / `16:9` / `1:1`.
* `duration` : durée cible (secondes), par défaut 30.

Tous les champs du corps de la requête sont présentés dans le tableau ci-dessous :

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `prompt` | string | Oui | Décrire en langage naturel la vidéo à réaliser (thème, ce qui doit être montré, style, public). Le script, les images, la voix off et le montage sont décidés par l'AI |
| `action` | string | Non | `generate` (par défaut, générer une nouvelle vidéo) / `remix` / `edit` / `extend` (itérer sur une vidéo existante, nécessite `ref_task_id`) |
| `ref_task_id` | string | Non | Obligatoire lorsque `action` est remix / edit / extend : `task_id` de la tâche historique à utiliser comme point de départ |
| `file_urls` | string\[] | Non | Médias de référence (URL d'images / vidéos / audios), par exemple des images de produits à montrer, un logo, ou des extraits de matériel à sous-titrer |
| `langs` | string\[] | Non | Langues de sortie, comme `["zh-cn", "en"]`, par défaut `["zh-cn"]`. La première est la langue principale ; chaque langue supplémentaire réutilise les images, ajoute seulement la voix off + le rendu, **chaque langue supplémentaire +6 points** |
| `aspect` | string | Non | `9:16` (par défaut) / `16:9` / `1:1`, sortie unifiée en 1080p/30fps |
| `duration` | int | Non | Durée cible (secondes), par défaut 30, supporte **5–300 secondes**. La facturation se fait selon la durée réelle de la vidéo produite, mais ne dépassera pas la durée demandée |
| `scenario` | string | Non | Type de vidéo : `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` nécessite la vidéo source, `avatar` nécessite un portrait |
| `style` | string | Non | Préréglage de style visuel : `auto` (par défaut) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, accepte également du texte libre comme suggestion douce. Orthogonal à `scenario`, ne change pas le routage |
| `voice` | string | Non | Tonalité de la voix off (indépendante de la langue, utilisable entre langues) : `auto` (par défaut) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` |

Voici un exemple concret pour illustrer. Supposons que nous souhaitons générer une courte vidéo de vulgarisation scientifique en chinois et en anglais, en mode portrait, d'une durée de 20 secondes, le code CURL correspondant est le suivant :

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

Le code Python correspondant est le suivant :

```python theme={null}
import requests

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

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

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

En cliquant sur exécuter, vous pouvez constater que vous obtiendrez immédiatement un résultat, comme suit :

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

La description des champs du résultat retourné est la suivante :

* `success` : Indique si la tâche a été soumise avec succès.
* `task_id` : L'ID de la tâche de génération de vidéo, à utiliser pour interroger les résultats via l'[API de requête de tâches Maestro](/fr/guides/maestro/maestro_tasks).
* `trace_id` : L'ID de suivi de cette requête, à fournir au support technique en cas de problème.

Étant donné que la production vidéo prend du temps, l'interface retourne **immédiatement `task_id`** et n'attend pas que le rendu vidéo soit terminé. Il est ensuite nécessaire d'utiliser `task_id` pour interroger les résultats, voir la section « Obtenir les résultats ».

## Spécifier le type et le style de vidéo (scenario / style)

Si `scenario` n'est pas fourni, l'IA le déterminera automatiquement (équivalent à `auto`) ; si vous souhaitez ancrer la vidéo dans un certain type, spécifiez-le explicitement. Par exemple, pour créer un **court-métrage en mode portrait**, vous pouvez spécifier le contenu suivant :

* `scenario` : Type de vidéo, ici défini comme `drama` (court-métrage avec personnages + dialogues).
* `style` : Style visuel, ici défini comme `cinematic` (qualité cinématographique).

Voici un exemple de code CURL :

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Deux colocataires se disputent à cause d'un chat, se réconcilient, trois actes avec des rebondissements, fin chaleureuse",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Modes de combinaison courants :

* Vidéo explicative : `scenario: "narrated"`, pris en charge par Lite / Standard / Pro.
* Sous-titres automatiques : `scenario: "captions"`, nécessite de transmettre la vidéo source via `file_urls`, pris en charge par Lite / Standard / Pro.
* Personnage numérique / Voix off : `scenario: "avatar"`, nécessite de transmettre une image de portrait via `file_urls`, pris en charge par Standard / Pro.
* Court-métrage : `scenario: "drama"` (personnages + dialogues), uniquement pris en charge par Pro.
* `style` est un préréglage de style visuel (comme `modern` / `neon` / `luxury`), ne change pas le type, affecte seulement l'apparence.
* `voice` est utilisé pour spécifier la tonalité de la voix off (comme `warm-female` / `deep-male`), sans rapport avec la langue, applicable à toutes les langues.

Le résultat retourné est identique à celui de la « utilisation de base », retournant également immédiatement `task_id`.

## Sortie multilingue

En passant plusieurs langues dans `langs`, vous pouvez produire une version multilingue en une seule fois. La première langue est la langue principale, et chaque langue supplémentaire **réutilisera le même ensemble d'images**, nécessitant uniquement un doublage + rendu supplémentaire, donc **chaque langue supplémentaire coûte seulement +6 points**. Exemple :

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Présentation de notre produit de service client intelligent, mettant en avant 3 points clés",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

Une fois la tâche terminée, chaque langue correspondra à un `variant` dans les résultats (voir [API de requête de tâches Maestro](/fr/guides/maestro/maestro_tasks)).

## Itération sur une vidéo existante (remix / edit / extend)

En passant `action` et `ref_task_id` de la tâche précédente, vous pouvez apporter des modifications différentielles à la base du projet original (comme « changer le titre de l'acte 2 », « changer la voix off », « assombrir l'ensemble »). Les petites modifications sont rapides, les grandes modifications nécessiteront un nouveau rendu :

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Changer le titre d'ouverture par une phrase plus percutante, assombrir un peu la palette de couleurs"
}'
```

* `remix` : Réinterpréter la structure de la vidéo originale (conserver le thème, ajuster l'expression).
* `edit` : Apporter des retouches à des parties spécifiques (comme changer le titre, changer la voix off, ajuster les couleurs).
* `extend` : Étendre le contenu sur la base de la vidéo originale.

Le résultat retourné est également un nouveau `task_id`, que vous pouvez utiliser pour interroger et obtenir le produit final itéré.

## Obtenir les résultats

Étant donné que la production vidéo prend du temps, cette interface retourne immédiatement `task_id` après la soumission, vous devez l'utiliser pour interroger les résultats via l'[API de requête de tâches Maestro](/fr/guides/maestro/maestro_tasks) :

```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"
}'
```

Lorsque la tâche est terminée, elle renverra les informations du produit final (chaque langue correspondant à un `variant`). `status` passera par `pending → planning → producing → succeeded` (ou `failed`), **l'interrogation est gratuite, ne consomme pas de points**. Pour le format de réponse complet et la requête de liste historique, veuillez consulter [les instructions d'intégration de l'API de requête de tâches Maestro](/fr/guides/maestro/maestro_tasks).

## Facturation

**La facturation est effectuée après l'achèvement de la tâche, les tâches échouées ne sont pas facturées.** La facturation est basée sur la durée réelle du produit final livré et le nombre de langues, et la durée facturée ne dépassera pas la durée demandée. Si une langue n'est finalement pas produite, il n'y aura pas de frais supplémentaires de +6 pour cette langue. La soumission de la tâche elle-même n'est pas facturée séparément, l'interrogation via `/maestro/tasks` est gratuite.

Les points pour un produit final unique sont calculés comme suit :

```
points = durée du produit final en secondes × 0.60 × multiplicateur de scénario + 6 × max(nombre de langues - 1, 0)
```

Maestro facture uniformément **0.60 points/seconde de produit final réel**, prenant en charge 5 à 300 secondes, jusqu'à 4 langues et une sortie en 1080p / 30fps ; toutes les actions et scénarios sont utilisables.

Multiplicateur de scénario : `drama` 1.35× / `avatar` 1.15× / autres 1×.

| Exemple | Points |
| - | -: |
| Lite 30 secondes | 6 |
| Standard 30 secondes | 18 |
| Standard 60 secondes | 36 |
| Standard 120 secondes | 72 |
| Pro 30 secondes | 36 |
| Pro 300 secondes | 360 |
| Chaque langue supplémentaire livrée | +6 |
| Interrogation `/maestro/tasks` | Gratuite |

## 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 :

* `400 invalid_request` : Mauvaise requête, probablement en raison d'un `prompt` manquant ou de paramètres invalides.
* `401 invalid_token` : Non autorisé, jeton d'autorisation invalide ou manquant.
* `403 forbidden` : Interdit, solde insuffisant ou accès refusé.
* `429 too_many_requests` : Trop de requêtes, vous avez dépassé la limite de taux.
* `500 api_error` : Erreur interne du serveur, quelque chose s'est mal passé sur le serveur.

### Exemple de réponse d'erreur

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "échec de la récupération"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusion

Grâce à ce document, vous avez compris comment utiliser l'API de génération de vidéos Maestro : il vous suffit d'une phrase en langage naturel `prompt` pour automatiser la création de scripts, de matériel, de voix off, de musique, de montage, de sous-titres et de rendu final, tout en prenant en charge la spécification du type de vidéo, du style, du ton, de la sortie multilingue et de l'itération sur des vidéos existantes. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n'hésitez pas à contacter notre équipe de support technique.

## Interfaces connexes

* [Instructions d'intégration de l'API de requête de tâches Maestro](/fr/guides/maestro/maestro_tasks) : utilisez `POST /maestro/videos` pour interroger l'état et les résultats de la tâche avec le `task_id` retourné, ou pour récupérer la liste des tâches historiques (polling gratuit).


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