Passer au contenu principal
Maestro est une interface de production vidéo native Agent : vous utilisez une phrase en langage naturel prompt pour décrire la vidéo souhaitée (vous pouvez éventuellement joindre des images / vidéos / audios de référence avec file_urls), et un « réalisateur IA » sans interface graphique réalisera automatiquement le choix du sujet, l’écriture du script, la génération des visuels, le doublage, la musique, la composition et le rendu, pour finalement produire une vidéo finale avec sous-titres et la téléverser sur le CDN. Cet article présentera en détail le guide d’intégration de l’API de génération vidéo Maestro, afin de vous aider à l’intégrer rapidement et à exploiter pleinement les capacités de cette API. Il s’agit d’une interface de tâches asynchrones : après la soumission, elle renvoie immédiatement un task_id, puis vous récupérez le résultat par interrogation via l’API de consultation des tâches Maestro (POST /maestro/tasks) (l’interrogation est gratuite et non facturée). 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 dans la console Ace Data Cloud, et conservez-le 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 cette page. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir à en demander un séparément pour chaque service. La première demande offre des crédits gratuits pour une expérience gratuite ; lorsque les crédits sont insuffisants, vous pouvez recharger le solde universel dans la console.
📘 Documentation complète : API de génération vidéo Maestro →

Utilisation de base

POST https://api.acedata.cloud/maestro/videos L’utilisation la plus basique ne nécessite que de transmettre une instruction en langage naturel prompt. Le réalisateur IA décidera automatiquement du script, des visuels, de la voix off et du montage. Voyons d’abord les en-têtes et le corps de requête à configurer. En-têtes de requête :
  • accept : le format de réponse que vous souhaitez recevoir. Indiquez ici application/json, c’est-à-dire le format JSON.
  • authorization : la clé permettant d’appeler l’API ; après l’avoir obtenue, vous pouvez la sélectionner directement dans la liste déroulante.
  • content-type : le format du corps de requête. Indiquez ici application/json.
Corps de la requête comprend principalement :
  • prompt : décrivez en langage naturel la vidéo à créer (thème, éléments à afficher, style, public cible).
  • langs : tableau des langues de la vidéo finale ; transmettez une seule langue à la fois, par exemple ["zh-cn"]. La valeur par défaut est ["zh-cn"].
  • aspect : format d’image, 9:16 (par défaut) / 16:9 / 1:1.
  • duration : durée cible (secondes), 30 par défaut.
Tous les champs du corps de requête sont présentés dans le tableau ci-dessous : Voici une démonstration à l’aide d’un exemple concret. Supposons que nous souhaitions générer une courte vidéo de vulgarisation scientifique en chinois, au format vertical, de 20 secondes. Le code CURL correspondant est le suivant :
Le code Python correspondant est le suivant :
Cliquez sur Exécuter ; vous constaterez qu’un résultat est obtenu immédiatement, comme suit :
Les champs du résultat renvoyé sont décrits ci-dessous :
  • success : indique si cette tâche a été soumise avec succès.
  • task_id : l’ID de cette tâche de génération vidéo. Utilisez-le ensuite pour interroger les résultats via l’API de requête des tâches Maestro.
  • trace_id : l’ID de suivi de cette requête. En cas de problème, vous pouvez le fournir au support technique afin de faciliter le diagnostic.
Comme la production de vidéos prend du temps, l’API renvoie ici immédiatement task_id sans attendre la fin du rendu vidéo. Utilisez ensuite task_id pour interroger le résultat ; consultez la section « Obtenir le résultat » pour plus de détails.

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

Lorsque scenario n’est pas transmis, il est déterminé automatiquement par l’IA (équivaut à auto) ; si vous souhaitez définir la vidéo sur un type spécifique, transmettez-le explicitement. Par exemple, pour créer une courte série dramatique en format vertical, vous pouvez spécifier les éléments suivants :
  • scenario : le type de vidéo, défini ici sur drama (courte série avec personnages + dialogues).
  • style : le style visuel, défini ici sur cinematic (rendu cinématographique).
Voici le code CURL de l’exemple de remplissage :
Associations courantes :
  • Courte vidéo commentée : scenario: "narrated".
  • Sous-titres automatiques : scenario: "captions", le fichier vidéo source doit être transmis via file_urls.
  • Avatar numérique / présentation face caméra : scenario: "avatar", une image de portrait doit être transmise via file_urls.
  • Courte série dramatique : scenario: "drama" (personnages + dialogues).
  • style correspond à un préréglage de style visuel (par exemple modern / neon / luxury) ; il ne modifie pas le type, seulement le rendu visuel.
  • voice permet de spécifier le timbre de la voix off (par exemple warm-female / deep-male) ; il est indépendant de la langue et utilisable dans toutes les langues.
Le résultat renvoyé est identique à celui de « Utilisation de base » : task_id est également renvoyé immédiatement.

Langue de la vidéo finale

Une tâche ne livre qu’une seule vidéo finale dans une seule langue. langs ne peut contenir qu’un seul code langue, tel que ["zh-cn"] ou ["en"] ; transmettre plusieurs langues renverra une erreur 400. Si vous avez besoin de vidéos dans différentes langues, veuillez créer les tâches séparément. Le choix de la langue ne modifie pas le prix par seconde.

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

Transmettez action et le ref_task_id de la tâche précédente pour effectuer des modifications incrémentielles à partir du projet original (par exemple « modifier le titre de la scène 2 », « changer la voix off », « assombrir l’ensemble »). Les petites modifications sont rapides ; les modifications importantes entraînent une nouvelle production :
  • remix : réinterprète la vidéo sur la structure originale (conserve le thème, ajuste la présentation).
  • edit : effectue une retouche précise sur une partie spécifiée (par exemple changer le titre, la voix off ou l’étalonnage).
  • extend : prolonge le contenu à partir de la vidéo originale.
Le résultat renvoyé est également un nouveau task_id immédiatement ; utilisez-le pour interroger et obtenir la vidéo finale après itération.

Récupérer le résultat

Comme la production vidéo prend relativement longtemps, cette interface renvoie task_id immédiatement après la soumission ; vous devez l’utiliser pour interroger le résultat via l’API de requête des tâches Maestro :
Une fois la tâche terminée, les informations d’une vidéo finale sont renvoyées (dans le tableau variants). status passera par pending → planning → producing → succeeded (ou failed), et l’interrogation est gratuite et ne consomme pas de crédits. Pour le format de réponse complet et la requête de l’historique, consultez les instructions d’intégration de l’API de requête des tâches Maestro.

Facturation

Après la réussite de la tâche, la facturation est calculée selon la durée réelle de la vidéo finale livrée ; aucun frais n’est facturé en cas d’échec. La durée facturée est comptabilisée en secondes entières et ne dépasse pas la durée demandée ; lorsqu’il est impossible de lire la durée de la vidéo finale, la durée demandée est utilisée par défaut. La soumission de tâche elle-même n’est pas facturée séparément, et l’interrogation de /maestro/tasks est gratuite.
Tous les scénarios, actions et langues utilisent le même tarif, sans multiplicateur selon le scénario ni supplément selon la langue. Chaque tâche ne livre qu’une seule vidéo finale dans une seule langue. La durée cible demandée prend en charge de 5 à 300 secondes, avec une sortie uniforme en 1080p / 30fps.

Gestion des erreurs

Lors de l’appel de l’API, en cas d’erreur, l’API renvoie le code et les informations d’erreur correspondants. Par exemple :
  • 400 invalid_request : Requête incorrecte, possiblement en raison d’un prompt manquant ou de paramètres non valides.
  • 401 invalid_token : Non autorisé, jeton d’autorisation non valide ou manquant.
  • 403 forbidden : Interdit, solde ou accès insuffisant.
  • 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 côté serveur.

Exemple de réponse d’erreur

Conclusion

Grâce à ce document, vous savez désormais comment utiliser l’API de génération vidéo Maestro : une simple instruction en langage naturel prompt suffit pour réaliser automatiquement le script, les ressources, la voix off, la musique, le montage, les sous-titres et le rendu de la vidéo finale. L’API prend également en charge la spécification du type de vidéo, du style, du timbre de voix, de la langue de la vidéo finale, ainsi que 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 associées