> ## 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. # Guide d’intégration de l’API de génération de vidéos MiniMax H3 > Minimax API guide - Ace Data Cloud Cet article présente l’intégration et l’utilisation de l’API de génération de vidéos MiniMax H3. Cette interface prend en charge la génération de vidéos à partir de texte, le contrôle des première et dernière images, ainsi que la génération de vidéos à partir de références multimodales, en utilisant une structure V2 multimodale `content` unifiée pour créer les tâches. ## Processus de demande Pour utiliser l’API de génération de vidéos MiniMax H3, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour obtenir votre API Token, à conserver 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 qui vous invitera à 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 d’en demander un séparément pour chaque service.** Une première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde général dans la [console](https://platform.acedata.cloud/console/coin). > 📘 Documentation complète : [API de génération de vidéos MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration) Il est recommandé d’enregistrer le Token comme variable d’environnement, sans l’écrire dans le code source ni le soumettre à un dépôt de versions : ```bash theme={null} export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Vue d’ensemble de l’interface * **Base URL** : `https://api.acedata.cloud` * **Endpoint** : `POST /minimax/videos` * **Méthode d’authentification** : transmettre `authorization: Bearer {token}` dans le HTTP Header * **En-têtes de requête** : * `accept: application/json` * `content-type: application/json` * **Modèle (model)** : `MiniMax-H3` * **Structure d’entrée** : transmettre uniformément le texte, les images, les vidéos et l’audio via `content` * **Mode de sortie** : attend par défaut de manière synchrone la fin de la génération et retourne le `task` complet ; en passant `async: true` ou `callback_url`, retourne immédiatement `task_id` et `trace_id` * **Consultation des résultats** : obtenez le statut et la vidéo finale via l’[API de consultation des tâches MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration) * **Rappel asynchrone** : facultatif, recevez le résultat final de la tâche via `callback_url` Vous n’avez pas besoin de transmettre `action` pour choisir le mode de génération, l’interface déterminera automatiquement son utilisation selon le type de média et le `role` dans `content`. ## Scénarios adaptés | Scénario | Combinaison d’entrées | Utilisations courantes | | - | - | - | | Génération de vidéo à partir de texte | Texte | Créations publicitaires, prévisualisation de storyboard, vidéos courtes, plans d’ambiance | | Génération de vidéo à partir de l’image initiale | Texte + image initiale | Animer naturellement des images de produits, affiches, photos de personnes ou illustrations | | Vidéo avec image finale / première et dernière images | Texte + image finale, ou texte + image initiale + image finale | Contrôler le début et la fin, les transitions, les transformations de croissance et les comparaisons avant-après | | Génération de vidéo à partir de références multimodales | Texte + images / vidéos / audio de référence | Maintenir la cohérence des personnages et produits, reproduire les mouvements, mouvements de caméra, timbres ou rythmes de montage | ## Processus d’appel Lorsque `async` n’est pas transmis par défaut, `/minimax/videos` attendra la fin de la génération et retournera directement le `task` complet. Lorsqu’il est nécessaire de libérer immédiatement la connexion, transmettez `async: true` ou `callback_url` : 1. Enregistrez `task_id` et `trace_id` dans la réponse immédiate. 2. En l’absence de rappel configuré, appelez `/minimax/tasks` environ toutes les 10 secondes pour effectuer une consultation. 3. Lorsque `task.status` devient `succeeded`, récupérez la vidéo depuis `task.content.url`. 4. Lorsque le statut est `failed` ou `cancelled`, arrêtez l’interrogation et consultez `task.error`. ## Paramètres de requête de niveau supérieur | Paramètre | Type | Obligatoire | Valeur par défaut | Description | | - | - | - | - | - | | `model` | string | Oui | - | Fixé à `MiniMax-H3` | | `content` | object\[] | Oui | - | Tableau de contenu multimodal, doit contenir un élément `text` non vide | | `resolution` | string | Oui | - | `768P` ou `2K` | | `duration` | integer | Oui | - | Durée générée, entier de 4 à 15 secondes | | `ratio` | string | Obligatoire sous condition | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | | `async` | boolean | Non | `false` | Lorsque `true`, retourne immédiatement l’identifiant de la tâche, obtenez le résultat via l’interface des tâches | | `callback_url` | string | Non | - | URL de rappel publique recevant le résultat final de la tâche ; active automatiquement le mode asynchrone après sa fourniture | Les règles de `ratio` dépendent du flux de travail : * **Génération de vidéo à partir de texte** : obligatoire et ne peut pas être `adaptive`. * **Vidéo avec image initiale, image finale ou première et dernière images** : le format est déterminé par l’image d’entrée, il est recommandé de l’omettre ou de transmettre `adaptive`. * **Génération de vidéo à partir de références multimodales** : peut être omis, la valeur par défaut est `adaptive` ; un ratio fixe peut également être explicitement spécifié. L’interface n’accepte pas les champs hérités ou de compatibilité, tels que `prompt`, `image_urls`, `audio_urls`, `messages` et `first_frame_image`. Lorsque vous recevez des erreurs liées à ce type de paramètres, supprimez les anciens champs et migrez vers `content` ; par exemple, remplacez `"prompt": "一只猫挥手"` par `"content": [{"type": "text", "text": "一只猫挥手"}]`。N’envoyez pas simultanément les deux nouveaux et anciens formats. ## Paramètres des éléments de contenu content Chaque élément de contenu doit avoir un `type`, les autres champs étant déterminés par le type : | `type` | Champ de données | `role` | Description | | - | - | - | - | | `text` | `text` | non transmis | Chaque requête doit contenir un élément textuel non vide, de 7 000 caractères maximum | | `image_url` | `image_url.url` | `first_frame` | Image initiale ; lorsqu’il n’y a qu’une image et que `role` est omis, elle est également traitée comme image initiale | | `image_url` | `image_url.url` | `last_frame` | Image finale ; peut être utilisée seule ou combinée avec `first_frame` pour contrôler le point de départ et le point final | | `image_url` | `image_url.url` | `reference_image` | Référence de sujet, personnage, produit, vêtement, scène ou style | | `video_url` | `video_url.url` | `reference_video` | Référence de mouvement, mouvement de caméra, performance ou structure de montage | | `audio_url` | `audio_url.url` | `reference_audio` | Référence de timbre, dialogue, musique ou rythme | Les adresses média prennent en charge trois formats : * URL HTTPS accessible publiquement, recommandée pour les fichiers volumineux. * `mm_file://{file_id}`, référence à un fichier déjà téléversé ou à un résultat existant. * URI data Base64 du type de média correspondant. Base64 augmente la taille d’environ un tiers, assurez-vous que l’ensemble du corps de la requête ne dépasse pas 64 MB. ## Spécifications des médias et limites de quantité | Ressource | Format | Limite par fichier | Dimensions / durée | Limite de quantité | | - | - | - | - | - | | Image | JPG、JPEG、PNG、WEBP、HEIC、HEIF | Ne dépasse pas 30 MB | Largeur et hauteur comprises entre 256 et 5760 px；rapport largeur/hauteur 0.4-2.5 | 1 image maximum pour la première image, 1 image maximum pour la dernière image, 9 images de référence maximum | | Vidéo | MP4、MOV；H.264/AVC ou H.265/HEVC；piste audio AAC ou MP3 | Ne dépasse pas 50 MB | 2-15 secondes par segment, 15 secondes au total maximum；largeur et hauteur comprises entre 256 et 5760 px；rapport largeur/hauteur 0.4-2.5；23.976-60 fps | 3 vidéos de référence maximum | | Audio | WAV、MP3 | Ne dépasse pas 15 MB | 2-15 secondes par segment, 15 secondes au total maximum | 3 audios de référence maximum | Les images, vidéos et audios dans les scénarios de référence multimodaux totalisent au maximum 12 fichiers. Les scénarios de première et dernière image sont mutuellement exclusifs avec les scénarios de ressources de référence : dès lors que `reference_image`, `reference_video` ou `reference_audio` est utilisé, `first_frame` ou `last_frame` ne peut plus être utilisé, et inversement. ## Présentation des capacités de niveau production Les éléments ci-dessous ne sont pas des maquettes conceptuelles ni des ressources de substitution, mais de véritables entrées de référence et sorties vidéo réelles d’échantillons officiels des capacités de niveau production de MiniMax H3. Les trois groupes de cas couvrent respectivement les films de marque, les récits avec acteurs réels et l’e-commerce de mode, et conviennent pour évaluer les capacités les plus cruciales du modèle dans la production commerciale. | Capacité | Points d’observation clés | | - | - | | Cohérence des personnages et des visages | Stabilité des traits du visage, de la coiffure, du maquillage et du tempérament du personnage après les changements de plans | | Jeu facial | Regard, micro-expressions, tension émotionnelle et mouvements naturels de la tête dans les plans rapprochés | | Préservation de la structure du produit | Contours, matériaux, relation de port et reflets de miroir de produits tels que les lunettes et les sacs à main | | Exécution visuelle de la marque | Cohérence de l’atmosphère de la scène, du grain cinématographique, des couleurs, du logo et du rythme de montage | | Narration cinématographique | Capacité des variations d’échelle de plan, de la direction des personnages, des mouvements de caméra, du rythme et du son à former une séquence complète | Ici, les « capacités faciales » désignent la cohérence de l’apparence des personnages, les détails du visage et le contrôle de l’interprétation dans la génération vidéo ; il ne s’agit pas de reconnaissance d’identité, de comparaison faciale ou d’interface d’échange de visage. ### Film court de marque haut de gamme : unification des personnages, des produits et des actifs de marque **Objectif de production :** Film de marque de mode haut de gamme en 16:9. Établir une atmosphère froide à l’aide d’une route désertique et d’une voiture vintage, préserver l’apparence de l’héroïne et la structure du sac à main noir, et intégrer naturellement le logo de la marque à la fin. Ce cas teste principalement la cohérence des personnages entre les plans, la préservation du produit, la texture cinématographique et la capacité à conclure avec la marque. | Référence d’ambiance et de scène | Référence du personnage | | - | - | | Référence d’ambiance de film de marque avec route désertique et voiture vintage | Référence de l’héroïne du film de marque | | Référence du produit sac à main | Référence du logo de la marque | | - | - | | Référence du produit sac à main noir | Référence du logo de la marque |