Guide de l'API MiniMax H3 : texte vers vidéo et entrées de référence
Les requêtes MiniMax H3 sont faciles à mal configurer lorsqu'un client traite toutes les variantes du modèle comme interchangeables. L'ID de modèle choisi influe sur la validation de la durée et de la résolution, tandis que le mode de média détermine quels champs image, vidéo et audio peuvent être envoyés ensemble.
Ce guide décrit le contrat de requête tel qu'il est représenté dans le frontend ToAPIs au 22 octobre 2026. Il s'agit d'un guide d'intégration, et non d'un rapport sur les performances du fournisseur en amont ni sur le prix actuel de votre compte. Vérifiez que votre compte a bien accès au modèle demandé avant d'envoyer des tâches de production.
Démarrage rapide
Le point de terminaison de génération utilisé dans les exemples de l'API ToAPIs est POST /v1/videos/generations. Authentifiez-vous avec une clé API ToAPIs et fournissez un prompt, un ID de modèle autorisé, la durée et le ratio. Par exemple :
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9"
}'
Considérez la réponse comme la soumission d'une tâche asynchrone. Lisez l'identifiant de tâche renvoyé par la réponse de l'API de votre compte et interrogez son état via le point de terminaison de statut documenté. Ne supposez pas un format de réponse figé, sauf s'il est précisé dans la référence API de votre compte.
import os
import time
import requests
BASE_URL = "https://api.toapis.com/v1"
API_KEY = os.environ["TOAPIS_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json={
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9",
},
timeout=30,
)
response.raise_for_status()
submission = response.json()
print("Submission response:", submission)
L'exemple affiche volontairement la réponse au lieu de supposer où se trouvent l'ID de tâche ou l'URL de la vidéo. Adaptez le code de lecture et d'interrogation au schéma de réponse documenté pour votre compte. Vous éviterez ainsi de traiter silencieusement un format modifié comme une tâche réussie.
Choisir l'ID de modèle exact
Le frontend reconnaît minimax-h3 et minimax-h3-global comme ID de la famille de base, ainsi que les ID de modèle contenant minimax-h3-max. Par exemple, l'ID du modèle Turbo utilisé dans le produit est minimax-h3-max-turbo. Utilisez l'identifiant canonique affiché dans le catalogue de modèles disponible ; évitez d'inventer des alias ou de raccourcir l'ID.
Le frontend applique actuellement ces limites de capacités :
| Famille / ID de modèle | Durée acceptée par le frontend | Choix de résolution représentés dans le frontend |
|---|---|---|
minimax-h3 et minimax-h3-global | 4 à 15 secondes, entier | 2K, 768p |
minimax-h3-max-turbo et autres variantes Max | 5 à 15 secondes, entier | 480P, 768P |
minimax-h3-max canonique | 5 à 15 secondes, entier | Choix Max plus 1080P |
Ce sont des contraintes de validation du frontend, et non la garantie que chaque compte ou chaque route en amont dispose de la même disponibilité. En particulier, l'option supplémentaire 1080P n'est associée qu'à l'ID canonique exact minimax-h3-max dans le client actuel. Ne déduisez pas que Turbo, un alias -global ou n'importe quel modèle H3 prend en charge le 1080P.
Choisir un seul mode de média
Le formulaire H3 prend en charge deux workflows mutuellement exclusifs :
- Mode image : fournissez au plus un
first_frame_imageet au plus unlast_frame_image. Le client sélectionne un ratio adaptatif lorsque des entrées d'image sont présentes. - Mode référence : fournissez des images, vidéos et/ou audios de référence sans entrée de première ou de dernière image. Le client utilise le ratio sélectionné pour ces références.
Exemple de requête avec première image :
{
"model": "minimax-h3",
"prompt": "The subject turns toward the camera as the camera gently moves forward",
"duration": 5,
"ratio": "16:9",
"first_frame_image": ["https://example.com/starting-frame.jpg"]
}
Exemple de requête avec média de référence :
{
"model": "minimax-h3",
"prompt": "Use the supplied references to guide the scene and motion",
"duration": 5,
"ratio": "16:9",
"media_mode": "reference",
"reference_images": ["https://example.com/character-reference.jpg"],
"reference_videos": ["https://example.com/motion-reference.mp4"]
}
Le format exact des valeurs pour les médias téléversés dépend du flux de téléversement du gateway. Ces exemples montrent les champs de la requête ; ils n'affirment pas que n'importe quelle URL publique est acceptée par toutes les routes. Utilisez les URL ou les identifiants d'actifs renvoyés par le flux de téléversement documenté.
Le frontend applique ces limites de référence :
- Jusqu'à 9 images de référence.
- Jusqu'à 3 vidéos de référence.
- Jusqu'à 3 audios de référence.
- Pas plus de 12 actifs de référence au total.
- Chaque vidéo de référence doit durer de 2 à 15 secondes, et la durée cumulée des références soumises ne peut pas dépasser 15 secondes.
- Les références audio exigent au moins une référence visuelle.
- Les requêtes Turbo ne peuvent pas inclure de média de référence.
Respectez ces contraintes avant d'envoyer. Une requête qui mélange les modes d'entrée, dépasse un quota ou omet le contexte visuel requis est rejetée localement par le frontend au lieu d'être envoyée comme une requête de génération H3 valide.
Options de prompt et de génération
Le prompt est obligatoire et limité à 7 000 caractères Unicode par le frontend actuel. Décrivez la scène, le sujet, le mouvement et l'intention visuelle en langage simple. Traitez les balises caméra entre crochets et toute autre syntaxe spéciale comme du texte de prompt ordinaire, sauf si la documentation du modèle en amont les définit explicitement. Les éléments disponibles dans le contrat du frontend ne démontrent pas que des chaînes comme [Pan Left] sont des commandes H3 natives.
Le générateur de requêtes transmet les contrôles optionnels pris en charge tels que prompt_optimizer, watermark et seed selon la route de modèle choisie. Ne supposez pas que les champs optionnels sont acceptés de manière identique par chaque canal en amont. Si vous les exposez dans votre propre interface, validez-les par rapport au catalogue spécifique du modèle et supprimez les champs obsolètes lorsque l'utilisateur change de variante.
Pour le ratio, le frontend accepte adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 et 9:16. Les entrées d'image forcent adaptive. En texte vers vidéo, une sélection adaptative est normalisée en 16:9 ; le mode référence conserve le ratio pris en charge demandé.
Écrire des prompts testables
La rédaction des prompts n'est pas un paramètre de l'API, mais elle conditionne l'utilité d'une intégration technique pour la personne qui l'utilise. Demandez aux utilisateurs de décrire une scène et une action principale avant d'ajouter une direction de caméra, un éclairage ou un style. Un prompt compact peut préciser le sujet, l'action, le décor et le comportement de la caméra dans cet ordre. Gardez ces éléments stables lors d'une comparaison de modèles ; sinon, un changement de formulation peut expliquer un résultat différent.
Ne promettez pas qu'une formulation donnée garantit un mouvement de caméra, une correspondance d'identité, une cadence d'images ou un style visuel. Le contrat du frontend valide le prompt comme du texte et applique une limite de caractères. Il ne définit pas de grammaire de commandes standard pour les balises caméra. Si votre application propose des contrôles de prompt prédéfinis, présentez-les comme des aides au prompt et non comme des contrôles garantis du modèle, sauf si la documentation en amont confirme ce comportement.
Pour les workflows de génération répétés, conservez la version du modèle de prompt avec l'enregistrement de la tâche. Cela permet de distinguer un changement de modèle d'un changement de prompt lorsque les utilisateurs signalent des résultats différents. Évitez d'intégrer des clés API, des identifiants privés ou des données personnelles dans les prompts. Vérifiez le contenu du prompt au regard des politiques de contenu et de confidentialité de votre produit avant d'autoriser une soumission par lots sans supervision.
Normaliser ratio et résolution de manière explicite
Le ratio et la résolution répondent à des questions différentes : le ratio décrit la forme de la sortie, la résolution sélectionne une taille de sortie prise en charge par la route du modèle. Un ratio accepté n'implique pas que toutes les résolutions peuvent lui être associées. Conservez les deux champs dans l'interface et validez-les par rapport au modèle actuellement sélectionné.
Si l'utilisateur choisit le mode première image ou première et dernière image, le frontend force un ratio adaptatif afin que les images d'entrée guident la forme du canevas. N'affichez pas un ratio personnalisé contradictoire comme s'il allait être respecté. En mode texte vers vidéo, la sélection adaptative se résout en comportement 16:9 par défaut dans le générateur actuel. Si vous rendez cette normalisation visible, affichez la valeur réellement soumise lors d'une étape de vérification, pour que les utilisateurs comprennent ce que le gateway reçoit.
Les libellés de résolution diffèrent aussi par leur casse entre les variantes (768p contre 768P). Ne les normalisez que si le contrat API du modèle sélectionné l'autorise explicitement. Évitez de convertir globalement les valeurs de modèle, car une valeur acceptée par une route peut être refusée par une autre.
Interrogation du statut et erreurs
La génération vidéo est asynchrone. Après la soumission, conservez l'identifiant de tâche et interrogez le point de terminaison de statut documenté pour votre compte API. Utilisez un backoff exponentiel borné avec jitter plutôt qu'une boucle serrée, fixez une échéance globale et traitez l'échec définitif séparément de l'expiration du délai. Une expiration de délai ne prouve pas que la tâche en amont a échoué ; vérifiez l'état de la tâche avant de relancer une génération facturable.
Au minimum, votre client devrait :
- Appeler
raise_for_status()ou un équivalent sur les réponses HTTP. - Lire la réponse conformément au schéma d'API publié.
- Arrêter l'interrogation sur un état final documenté de succès ou d'échec.
- Plafonner le nombre de tentatives et le temps total écoulé.
- Éviter de soumettre une génération en double simplement parce qu'une requête côté client a expiré.
- Journaliser un identifiant de requête ou de tâche, mais jamais la clé API ni les URL de médias privés.
Les catégories d'erreur génériques ci-dessous sont des points de départ pour le diagnostic, et non une garantie des codes d'erreur exacts de ToAPIs :
| Statut HTTP | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide, valeur non prise en charge ou conflit de mode de média | Vérifiez l'ID de modèle, la durée, la résolution, le ratio et le nombre d'entrées. |
401 | Clé API absente ou invalide | Vérifiez la clé dans votre gestionnaire de secrets et les en-têtes de la requête. |
429 | Limite de débit ou de concurrence | Reculez avec du jitter et ne réessayez que lorsque c'est sûr. |
5xx ou expiration réseau | Problème temporaire du gateway ou de l'amont | Vérifiez l'état de la tâche avant de resoumettre ; appliquez une politique de nouvelle tentative bornée. |
Prix et garanties de service
Les prix, la disponibilité, le comportement des remboursements et les accords de niveau de service peuvent varier selon le modèle, la route et le compte. Ce guide ne cite volontairement aucun prix à la seconde et ne revendique aucun SLA de disponibilité. Consultez le catalogue de modèles ToAPIs actuel et les prix de votre compte avant d'estimer les coûts d'un projet. N'utilisez pas un prix issu d'un brouillon de planification comme devis de production.
Un workflow plus sûr pour construire les requêtes
Regroupez la sélection et la validation du modèle à un seul endroit de votre application. Lorsqu'un utilisateur change de modèle, reconstruisez les options autorisées au lieu de reporter tous les champs de la sélection précédente dans la requête suivante. Cela compte lors du passage de H3 de base à Max ou Turbo : une résolution, une liste de médias de référence ou une durée peuvent être valides pour un modèle et invalides pour un autre.
Une séquence fiable côté client ressemble à ceci :
- Lisez l'ID du modèle actuellement sélectionné dans le catalogue de modèles.
- Chargez les choix de durée et de résolution de ce modèle.
- Demandez à l'utilisateur de choisir le mode image ou le mode référence.
- Validez le nombre de champs et la compatibilité avant de téléverser des médias.
- Téléversez les médias choisis via le point de terminaison d'actifs documenté.
- Construisez un nouvel objet de requête à partir des valeurs validées.
- Soumettez une seule fois, enregistrez l'identifiant de tâche renvoyé et exposez l'état de la tâche à l'utilisateur.
Évitez de modifier sur place un ancien objet de requête. Un objet neuf réduit le risque qu'un champ comme reference_videos fuie dans une requête Turbo après un changement de modèle. Le contrat du frontend ToAPIs rend aussi le mode explicite : media_mode peut être frame ou reference, et les entrées mixtes sont rejetées.
Pour une intégration personnalisée, reproduisez ces contrôles avant l'appel réseau :
def validate_h3_request(model, duration, resolution, frame_images, refs):
is_max_family = "minimax-h3-max" in model
is_turbo = "turbo" in model
min_duration = 5 if is_max_family else 4
if not isinstance(duration, int) or not min_duration <= duration <= 15:
raise ValueError("Duration is outside this model's supported range")
if len(frame_images) > 2:
raise ValueError("Use at most one first frame and one last frame")
if frame_images and refs:
raise ValueError("Frame inputs and reference media are separate modes")
if is_turbo and refs:
raise ValueError("This Turbo route does not accept reference media")
if len(refs.get("images", [])) > 9:
raise ValueError("Too many reference images")
if len(refs.get("videos", [])) > 3:
raise ValueError("Too many reference videos")
Il s'agit d'une protection illustrative côté client, et non d'un remplacement de la validation serveur. Le code de production devrait en outre valider chaque type de média, calculer le nombre total de références et la durée des vidéos, appliquer la liste de résolutions propre au modèle et utiliser les identifiants réels renvoyés par le flux de téléversement.
Considérations de téléversement et de confidentialité
Traitez les médias de référence comme des données utilisateur. Ne téléversez que des fichiers que l'utilisateur est autorisé à utiliser et assurez-vous que vos règles de conservation et d'accès couvrent les images, audios et vidéos sources. Ne placez pas de médias sources privés sur des URL publiques uniquement pour simplifier une démonstration. Si l'API renvoie une URL d'actif temporaire, évitez de l'écrire dans des outils d'analyse ou des journaux de longue durée.
Validez les fichiers avant le téléversement : refusez les extensions et types MIME non pris en charge, appliquez les limites documentées de taille et de nombre, et affichez une erreur claire avant de consacrer du temps à une requête de génération. Conservez l'identifiant de téléversement associé à l'enregistrement de la tâche, mais n'exposez pas de chemins de stockage internes sur une page publique. Si un téléversement échoue, arrêtez-vous avant de créer une tâche de génération au lieu de soumettre une requête incomplète.
Pour les nouvelles tentatives, distinguez les lectures idempotentes des soumissions de génération facturables. Réessayer une vérification de statut en GET est généralement différent de répéter un POST qui a peut-être déjà créé une tâche. Si le client perd la réponse de soumission, utilisez d'abord tout identifiant de requête ou mécanisme de récupération documenté pour le compte. S'il n'en existe aucun, signalez un état incertain à l'opérateur au lieu de créer silencieusement un doublon.
Liste de vérification avant déploiement
Avant de livrer une intégration H3, testez au moins une requête valide par ID de modèle autorisé pour votre compte. Ajoutez des tests négatifs pour une durée fractionnaire, une résolution non prise en charge, trop de références, des entrées image et référence combinées, et des références sur Turbo. Vérifiez que l'interface efface les valeurs incompatibles après un changement de modèle.
En préproduction, journalisez les champs de la requête après validation et comparez-les au schéma documenté du gateway. Ne capturez pas de clés API ni de données de médias privés dans les journaux. Confirmez l'URL d'interrogation, les états de tâche et le champ de résultat avec un fixture hors production ou un compte de test approuvé. Cet article n'appelle aucun point de terminaison en direct et ne valide pas le comportement du service distant.
Enfin, vérifiez le prix du compte de l'utilisateur et le catalogue de modèles juste avant la mise en ligne. La disponibilité et les prix des modèles sont des informations propres à chaque compte ; des valeurs copiées dans un ancien article peuvent devenir obsolètes même si les champs de requête restent inchangés.
Modèles associés et étapes suivantes
- Parcourir les modèles vidéo
- Ouvrir le Playground avec MiniMax H3
- Ouvrir le Playground avec MiniMax H3 Max Turbo
Avant de déployer, vérifiez l'ID de modèle exact, la disponibilité actuelle de la route, le format de téléversement, le schéma de réponse et le prix du compte dans la documentation API dont vous disposez.







