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 iciapplication/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 iciapplication/json.
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.
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 :
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.
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)
Lorsquescenario 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 surdrama(courte série avec personnages + dialogues).style: le style visuel, défini ici surcinematic(rendu cinématographique).
- Courte vidéo commentée :
scenario: "narrated". - Sous-titres automatiques :
scenario: "captions", le fichier vidéo source doit être transmis viafile_urls. - Avatar numérique / présentation face caméra :
scenario: "avatar", une image de portrait doit être transmise viafile_urls. - Courte série dramatique :
scenario: "drama"(personnages + dialogues). stylecorrespond à un préréglage de style visuel (par exemplemodern/neon/luxury) ; il ne modifie pas le type, seulement le rendu visuel.voicepermet de spécifier le timbre de la voix off (par exemplewarm-female/deep-male) ; il est indépendant de la langue et utilisable dans toutes les langues.
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)
Transmettezaction 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.
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 renvoietask_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 :
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.
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’unpromptmanquant 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 naturelprompt 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
- Instructions d’intégration de l’API de requête des tâches Maestro : utilisez le
task_idrenvoyé parPOST /maestro/videospour consulter l’état et le résultat d’une tâche, ou récupérer la liste des tâches historiques (interrogation gratuite).

