Tutoriel
Comment appeler minimax-h3-max-turbo texte-vers-vidéo via l'API HiAPI
- Modèle
- minimax-h3-max-turbo
Sur cette page
Fonctionnalités et cas d'usage de ce point de terminaison
minimax-h3-max-turbo/text-to-video est le point de terminaison du modèle texte-vers-vidéo exposé via l'API HiAPI. Vous envoyez un prompt textuel décrivant la scène souhaitée, accompagné de quelques paramètres contrôlant la forme de la sortie, et HiAPI renvoie la vidéo générée. Ce modèle est idéal lorsque vous disposez d'une description textuelle sans matériau source : clips marketing, plans de transition pour les réseaux sociaux, aperçus de storyboard, vidéos en boucle en arrière-plan d'application, ou génération de variantes en lot d'un même concept créatif.
Avant d'écrire du code, quelques caractéristiques méritent attention :
- C'est un point de terminaison de génération, pas un template. La sortie n'est prévisible que dans sa structure (vous obtenez une vidéo), pas dans son contenu. Considérez chaque tâche comme un rendu entièrement nouveau et concevez vos prompts en vue de la réutilisabilité.
- C'est asynchrone. L'appel de soumission ne renvoie pas directement les octets de la vidéo finale. Vous obtenez d'abord un identifiant de tâche, puis vous interrogez le résultat. Toute intégration supposant une réponse synchrone échouera au premier dépassement de délai.
- La sortie dépend des paramètres de la requête. La durée et la résolution modifient le coût de rendu et le temps réel, donc les paramètres que vous choisissez sont aussi des décisions de latence et de budget.
- Aucun média source n'est nécessaire. Vous n'avez pas à téléverser de vidéo ou d'image ; le prompt et les paramètres constituent toute la surface d'entrée.
Quand utiliser une autre approche ? Si vous avez déjà du matériau et souhaitez le restyliser ou l'étendre, ce n'est pas le bon point de terminaison. Si vous avez besoin d'un contrôle image par image du mouvement de caméra ou d'une composition précise, un prompt textuel sera trop permissif. Et si vous n'avez besoin que d'une image statique, le point de terminaison texte-vers-image est moins cher et plus rapide. Utilisez minimax-h3-max-turbo/text-to-video lorsque le prompt suffit comme spécification de plan.
Le reste de ce guide couvre dans l'ordre l'authentification, un appel curl exécutable, l'appel Python équivalent, le cycle de vie des tâches, les paramètres clés, les erreurs que vous rencontrerez, et les étapes de durcissement avant mise en production.
Prérequis et authentification
Avant la première requête, trois choses sont nécessaires :
- Une clé API de compte HiAPI. Traitez-la comme un secret : chargez-la depuis une variable d'environnement, ne la commitez jamais dans un dépôt, et révoquez-la immédiatement en cas de fuite.
- L'URL de base HiAPI. Tous les appels de ce guide ciblent le même hôte de base ; le modèle est sélectionné par segment de chemin, et non par domaine distinct par modèle.
- Un client HTTP. curl pour les tests de fumée, n'importe quelle bibliothèque standard ou client HTTP pour le code de service.
Comment transmettre la clé
HiAPI authentifie les requêtes via un token bearer dans l'en-tête Authorization. La forme est toujours identique :
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Deux habitudes épargnent beaucoup de temps de débogage :
- L'orthographe de l'en-tête doit être exacte. Le A de
Authorizationen majuscule,Bearersuivi d'un espace, puis la clé. Un espace manquant est la cause la plus fréquente d'un 401 mystérieux. - Envoyez toujours
Content-Type: application/json. Un serveur attendant du JSON rejettera ou mal interprétera un corps sans cet en-tête, et l'erreur reçue indiquera souvent un champ manquant plutôt que la vraie cause.
Vérifiez avant de développer
Ne commencez pas par le point de terminaison vidéo. Faites d'abord un appel bon marché et rapide pour confirmer que la clé et l'URL de base se résolvent correctement, puis continuez. Si ce contrôle de cohérence échoue, rien en aval ne fonctionnera et vous déboguerez au mauvais niveau. Placez la clé à un seul endroit du code — un petit module client — afin qu'une future rotation ne nécessite qu'une modification d'une ligne.
Requête curl exécutable
L'appel de soumission envoie le prompt et les paramètres sous forme de corps JSON vers le chemin du modèle. Voici l'appel minimal exécutable :
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Au lever du soleil, un lent travelling aérien avant survole une forêt de pins brumeuse, lumière volumétrique douce, rendu cinématographique",
"duration": 5,
"resolution": "720p"
}'
Rôle de chaque partie :
-X POST— les tâches de génération sont créées via POST.- URL — l'hôte de base plus le chemin
minimax-h3-max-turbo/text-to-video. Placez l'hôte de base dans une variable afin que test et production suivent le même chemin de code. Authorization— le token bearer décrit dans la section précédente.Content-Type— déclare le corps JSON.prompt— la seule entrée créative obligatoire. Rédigez-le comme une description de plan : sujet, comportement de caméra, éclairage et ambiance. Une courte phrase nominale produit des résultats ambigus ; une ou deux phrases avec une direction visuelle précise fonctionnent bien mieux.durationetresolution— paramètres contrôlant la forme de la sortie, détaillés dans une section dédiée ci-dessous.
Utilisez -sS pour que curl reste silencieux tout en affichant les erreurs, et un outil de formatage lisible pour la réponse pendant l'exploration. La réponse est un JSON contenant l'identifiant de tâche ; conservez-le, car il servira à interroger la vidéo terminée. Ne vous attendez pas à ce que cette réponse contienne les octets vidéo.
Si vous voulez voir exactement ce qui est envoyé pendant le débogage, ajoutez -v pour la sortie détaillée, mais retirez-la avant de partager des logs, car la sortie détaillée peut inclure les en-têtes.
Requête Python équivalente
La version Python est la même requête, avec la clé chargée depuis l'environnement et la réponse analysée. Voici un petit client réutilisable :
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"Au lever du soleil, un lent travelling aérien avant survole une forêt de pins brumeuse, lumière volumétrique douce, rendu cinématographique"
)
print(job)
Points d'attention lors de l'adaptation :
json=payloaddéfinit à la fois le corps et le type de contenu ; ne sérialisez pas manuellement en plus.timeout=30borne l'appel de soumission. La soumission est rapide, le rendu ne l'est pas : c'est pourquoi le délai est court ici et que l'interrogation prend en charge l'attente.raise_for_status()transforme les réponses non 2xx en exceptions, exposant immédiatement les échecs d'authentification et de validation au lieu de renvoyer silencieusement un corps d'erreur que vous interpréteriez ensuite à tort comme une tâche.- Renvoyez le JSON analysé sous forme de dictionnaire et extrayez l'identifiant de tâche sur le lieu d'appel. La fonction utilitaire reste ainsi générique, et le code d'orchestration décide quoi en faire.
Si vous utilisez une pile asynchrone, la même forme s'applique avec le client HTTP de votre choix : construire les en-têtes une fois, POSTer le corps, vérifier le statut, renvoyer le corps analysé.
Gérer le cycle de vie des tâches asynchrones
La génération prend du temps, c'est pourquoi le point de terminaison se divise en soumission et interrogation. Le cycle est toujours : soumettre, obtenir l'identifiant de tâche, interroger la tâche jusqu'à un état terminal, puis récupérer la sortie.
Soumission
Envoyez le POST décrit plus haut et lisez l'identifiant de tâche dans la réponse. Enregistrez-le immédiatement et associez-le à votre propre ID de requête, afin de pouvoir remonter au prompt d'origine en cas d'échec de l'interrogation.
Interrogation avec temporisation progressive
N'interrogez pas en boucle serrée. Commencez par un intervalle court, puis espacez :
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Trois détails rendent ce code fiable. Premièrement, la date limite : abandonnez toujours finalement en levant un timeout, plutôt que d'interroger indéfiniment. Deuxièmement, la temporisation plafonnée : commencez à quelques secondes, multipliez progressivement, et plafonnez l'intervalle afin de progresser sans marteler l'API. Troisièmement, le traitement des états terminaux : ne considérez que succès et échec comme terminaux, et renvoyez l'objet tâche pour que l'appelant puisse brancher.
Récupérer le résultat
Une fois la tâche signalée comme réussie, la réponse porte l'emplacement de la vidéo finale. Téléchargez-la ou streamez-la dès que possible vers votre propre stockage, et enregistrez l'URL avec l'ID de tâche. Ne supposez pas que le lien est permanent et ne récupérez pas la vidéo à chaque itération d'interrogation. Interrogez l'état de la tâche, puis récupérez une seule fois en cas de succès.
Paramètres de durée et de résolution
Deux paramètres de requête déterminent la sortie, ainsi que le temps de rendu et le coût de l'appel.
duration
La longueur du clip généré. Plus le clip est long, plus le temps de rendu augmente proportionnellement, ce qui implique une fenêtre d'interrogation plus longue et une probabilité accrue de déclencher le timeout côté client. Conseils pratiques :
- Adaptez la durée au cas d'usage. Un plan de transition pour les réseaux sociaux est court ; une boucle d'arrière-plan ne doit être longue que juste assez pour boucler acceptablement. Générer plus long que ce qui sera affiché est un pur gaspillage.
- Commencez petit pour itérer. Ajustez le prompt sur des durées courtes, puis re-rendez le prompt gagnant à sa longueur finale.
- N'oubliez pas que le coût croît avec le volume de sortie. La facturation est basée sur la longueur de sortie : la durée est donc à la fois un levier créatif et un levier budgétaire.
resolution
La qualité spatiale de la sortie. Une résolution plus élevée apporte plus de détails, mais consomme plus de temps de rendu et coûte plus cher. Recommandations :
- Choisissez selon le contexte de diffusion, pas selon une fiche technique. Si la vidéo apparaît dans un fil ou un petit lecteur, générer une résolution supérieure à ce contexte n'apporte aucun bénéfice.
- Itérez en basse résolution, livrez en haute résolution. Prévisualisez en résolution inférieure pendant que vous modifiez le prompt, puis re-soumettez le prompt approuvé à la résolution de livraison.
- Des réglages plus élevés signifient une attente plus longue. Réglez la date limite d'interrogation sur la combinaison maximale que vous autorisez, pas sur la minimale.
Placez ces deux valeurs dans un même objet de configuration, plutôt que dispersées dans le code, afin que le passage de la prévisualisation à la production soit une édition intentionnelle et visible, et non un littéral oublié.
Déboguer les erreurs courantes
La plupart des échecs se classent en quatre catégories. Avant de modifier le code, associez le symptôme à sa catégorie.
Échecs d'authentification
Un 401 signifie que HiAPI n'accepte pas vos identifiants. Vérifiez dans l'ordre : l'en-tête Authorization est présent et correctement orthographié ; il y a exactement un espace après Bearer ; la clé est actuellement valide et ne provient pas d'un autre projet ; la variable d'environnement est réellement chargée (un saut de ligne final lors du collage de la clé est un problème classique). Confirmez en affichant la longueur de la variable plutôt que la clé elle-même.
Échecs de validation
Un 4xx autre que 401 signifie généralement un corps de requête incorrect. Le Content-Type est absent ou n'est pas application/json ; le prompt est absent ou vide ; duration ou resolution sort de l'ensemble autorisé. Lisez littéralement le message d'erreur ; il indique souvent le champ en cause. Reproduisez avec la version curl, car aucune couche de bibliothèque n'y masque le corps.
Timeouts
Il y a deux timeouts distincts. Un timeout de soumission signifie que le POST lui-même ne revient pas, pointant généralement vers le chemin réseau ou un timeout client trop agressif. Un timeout d'interrogation signifie que la tâche n'a pas atteint un état terminal avant votre date limite ; soit le rendu prend vraiment plus longtemps, soit votre date limite est calibrée sur les réglages de prévisualisation plutôt que de production. Corrigez ce dernier en augmentant max_wait pour les grandes durées et résolutions, pas en raccourcissant l'intervalle d'interrogation.
Erreurs d'interrogation
Les plus sournoises. Interroger sans dormir gaspille le quota et provoque des limitations de débit ; interroger à intervalle fixe court a le même effet. Interroger un ID de tâche erroné, souvent parce que vous avez réutilisé une variable entre plusieurs soumissions. Traiter un état intermédiaire comme une erreur. Et récupérer l'URL vidéo à chaque itération au lieu d'une fois en cas de succès. Journalisez l'ID de tâche et chaque état observé ; la séquence vous dira immédiatement laquelle de ces situations s'est produite.
Checklist de production avant mise en ligne
Passer d'un script fonctionnel à un service tournant sans surveillance implique d'ajouter quelques couches autour de la même requête.
- Retries avec jitter. Réessayez les erreurs réseau transitoires et les réponses 5xx avec un backoff exponentiel et de la randomisation. Ne réessayez jamais les erreurs de validation ; elles échoueront de la même manière et consommeront du quota.
- Des timeouts bornés partout. Un timeout court pour la soumission, une date limite plus longue pour l'interrogation (calibrée sur la durée et la résolution maximales que vous autorisez), et un timeout pour le téléchargement de la vidéo.
- Journalisation structurée. Enregistrez votre ID de requête, l'ID de tâche, chaque transition d'état observée et le résultat final, mais pas la clé API ni les en-têtes complets. Quand un problème survient à trois heures du matin, ce journal est votre seule preuve.
- Idempotence au niveau de votre couche. Maintenez une correspondance entre vos propres ID de requête et les ID de tâche, afin qu'un retry client ne produise pas silencieusement un second rendu.
- Maîtrise des coûts. La facturation est basée sur la longueur de sortie : fixez donc des plafonds de durée et de résolution maximaux acceptés par le service, et maintenez les prévisualisations de prompts à des réglages inférieurs avant approbation humaine ou par règle du rendu final.
- Hygiène des clés. Chargez les clés depuis un coffre à secrets, faites-les tourner périodiquement, et utilisez des clés distinctes pour test et production, afin qu'une clé de test compromise ne puisse pas consommer le budget de production.
- Propriété des résultats. Dès qu'une tâche réussit, copiez immédiatement la vidéo finale vers un stockage que vous contrôlez, et traitez l'URL de livraison comme un lien temporaire.
Une fois ces éléments en place, le point de terminaison devient une dépendance prévisible plutôt qu'une source de surprises. Confirmez d'abord les identifiants avec la requête curl ci-dessus, puis intégrez le client Python à votre service et enveloppez-le avec les vérifications de cette checklist.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage