Tutoriel
Comment utiliser minimax-h3-max-turbo/image-to-video via l'API HiAPI : curl, Python et exemples de requêtes fonctionnelles
Sur cette page
Ce que fait cet endpoint et quand l'utiliser
minimax-h3-max-turbo/image-to-video prend une image source et un prompt textuel, puis renvoie une courte vidéo qui part de cette image. L'image sert de première frame (ou d'ancrage visuel), de sorte que la sortie hérite de sa composition, de sa palette et de l'identité de son sujet. Le prompt décrit ensuite ce qui doit se produire — mouvement de caméra, action du sujet, ambiance.
Quand le préférer au text-to-video
Le text-to-video est l'outil approprié lorsque vous n'avez pas de référence visuelle et souhaitez que le modèle crée tout de zéro. L'image-to-video est le bon choix lorsque la première frame est l'essentiel : vous disposez déjà d'une photo produit validée, d'une image clé de storyboard, d'un design de personnage ou d'une photo envoyée par un utilisateur, et vous voulez l'animer tout en la gardant reconnaissable. Concrètement, les équipes utilisent cet endpoint lorsque :
- La première frame est une exigence contractuelle. L'équipe marketing a besoin d'ouvrir sur l'image principale exacte, pas sur une image similaire.
- La cohérence entre segments compte. Réutiliser la même image source maintient un personnage ou un produit stable sur une série de clips.
- Vous animez du contenu utilisateur. Une photo envoyée par un utilisateur final doit être animée, pas réinventée.
- Vous voulez un prompt plus ciblé. Décrire un mouvement est plus simple que décrire toute une scène depuis zéro, ce qui garde le prompt court et prévisible.
Cet endpoint est asynchrone : vous soumettez une tâche, puis récupérez la vidéo rendue. Cette forme convient bien à un backend piloté par file d'attente, comme détaillé ci-dessous. Pour la surface complète des paramètres, consultez la page du modèle.
Prérequis et structure de la requête
Avant d'appeler l'endpoint, vérifiez que vous disposez de quatre éléments :
- Une clé API. Créez-la dans votre compte HiAPI et envoyez-la comme bearer token. Traitez-la comme un secret — ne l'intégrez jamais dans du code client.
- Une URL de base. Toutes les requêtes vont vers l'hôte d'API unifié HiAPI ; le chemin de l'endpoint correspond à l'identifiant du modèle.
- Une image source, accessible ou encodable — soit une URL HTTPS publique, soit une charge base64, selon ce que le schéma de requête accepte.
- Un client HTTP —
curlpour un test rapide, et n'importe quelle bibliothèque standard ourequestsen Python pour une intégration réelle.
Les composants d'une requête
Quel que soit le langage, chaque soumission de tâche contient les mêmes éléments conceptuels :
- Modèle / endpoint —
minimax-h3-max-turbo/image-to-video, présent dans le chemin de la requête et répété dans le corps pour plus de clarté. - Image source — la première frame. C'est le champ qui distingue l'image-to-video du text-to-video, et celui qui provoque le plus facilement des erreurs de validation.
- Prompt — la description du mouvement et de la scène. Décrivez uniquement ce qui change, pas ce qui est déjà présent dans l'image.
- Indications de génération optionnelles — contrôles de durée et de style de résolution, si l'endpoint les propose. N'envoyez que les paramètres documentés dans le schéma ; les clés inconnues sont une source fréquente de réponses 4xx.
La soumission renvoie un identifiant de tâche et un statut. La vidéo elle-même arrive plus tard via une seconde requête — c'est pourquoi la section de polling ci-dessous est aussi importante que l'appel de soumission.
Une requête curl fonctionnelle
La commande suivante soumet une tâche image-to-video. Avant de l'exécuter, remplacez les espaces réservés — les marqueurs en majuscules entre chevrons — par vos propres valeurs.
curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": "Léger travelling avant sur le produit, lumière de studio douce glissant sur la surface, faible profondeur de champ."
}'
Quelques remarques pratiques sur cette commande :
- Lisez la clé depuis une variable d'environnement.
$HIAPI_API_KEYévite que la clé entre dans l'historique du shell, à condition de l'exporter plutôt que de la coller en ligne. - Pour le premier test, utilisez une URL d'image publique. Cela élimine le facteur d'encodage base64 tout en confirmant que l'authentification et la connexion fonctionnent.
- Gardez le corps JSON compact. La charge de
-dconstitue toute la requête ; une virgule manquante ici produit un 400 déroutant plutôt qu'une erreur de schéma claire. - Mettez le prompt entre guillemets. Un prompt contenant de la ponctuation casse une chaîne shell non protégée.
La réponse est un objet tâche, pas une vidéo. Récupérez-en l'ID de tâche — vous l'utiliserez pour la requête de polling. Si l'appel échoue immédiatement, passez à la section de dépannage ; les erreurs d'authentification et de charge utile se manifestent à cette étape, pas plus tard.
La même requête en Python
Voici l'appel de soumission Python équivalent avec requests. Il suppose que HIAPI_API_KEY est définie dans les variables d'environnement.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"
payload = {
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": (
"Léger travelling avant sur le produit, lumière de studio douce "
"glissant sur la surface, faible profondeur de champ."
),
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))
Points à conserver lors de l'adaptation de cet extrait :
- Le timeout n'est pas optionnel. La soumission est rapide, mais un socket bloqué dans un gestionnaire de requête web finit par bloquer aussi votre worker.
- Appelez
raise_for_status()avant de parser. Cela transforme un 401 silencieux en exception que vous pouvez réellement journaliser. - Renvoyez l'ID de tâche, pas la réponse. Dans un service, la fonction de soumission doit renvoyer l'identifiant pour qu'un poller séparé — ou une tâche en arrière-plan — prenne en charge l'attente.
- Conservez la charge utile dans une variable. Une fois l'appel réussi, remplacer l'URL de l'image par une URL d'upload signée ou une chaîne base64 ne demande qu'une ligne.
L'usage délibéré d'un client HTTP ordinaire plutôt que d'une bibliothèque wrapper est voulu : la forme de la requête est le contrat, et vous devez pouvoir la reproduire dans n'importe quel langage utilisé par votre stack.
Préparer l'image et la première frame
La plupart des tâches image-to-video échouées le font à cause de l'image, pas du prompt. Quelques habitudes permettent de l'éviter.
Format et diffusion
Utilisez un format raster standard et largement pris en charge — JPEG ou PNG — et assurez-vous que l'URL est accessible publiquement, sans cookie, sans redirection vers une page de connexion et sans dépendre d'une signature expirée générée après la soumission. Si votre ressource se trouve dans un bucket privé, générez une URL signée dont la durée de vie dépasse nettement la durée d'exécution prévue de la tâche. Pour les charges base64, supprimez le préfixe data-URI si le schéma attend des octets encodés bruts, et vérifiez que la taille encodée reste bien en deçà des limites documentées.
Dimensions et composition
Le modèle rend la vidéo à une taille de sortie fixe, donc l'image source est adaptée. Deux conséquences :
- Respectez le ratio d'image souhaité. Envoyer un portrait vertical dans un rendu paysage entraîne un recadrage ou des bandes noires, et le sujet peut se retrouver décentré.
- Laissez de la marge pour le mouvement. Si le prompt décrit un zoom avant ou un sujet qui monte, laissez de l'espace dans cette direction dans l'image source.
Préserver la première frame
La frame d'ouverture repose principalement sur l'image elle-même. Rédigez le prompt comme une instruction sur ce qui se passe après la première frame : décrivez le comportement de la caméra, l'action du sujet et l'évolution de la lumière. Évitez de redécrire la scène — lorsque l'image montre déjà « une chaise rouge sur un sol blanc », la répéter tend à ajouter de la dérive plutôt que de la fidélité. Si le résultat s'écarte de l'image source, raccourcissez d'abord le prompt avant d'envisager de changer l'image.
Ne présumez pas de l'existence de paramètres non documentés. Si un contrôle que vous souhaitez n'est pas dans le schéma, obtenez-le via le prompt ou la préparation de l'image.
Gérer le cycle de vie des tâches asynchrones
Les tâches image-to-video ne sont pas synchrones. Le schéma est soumettre → interroger → récupérer, et une intégration de production doit implémenter explicitement ces trois étapes.
1. Soumettre et persister
Envoyez la requête de soumission et stockez immédiatement l'ID de tâche renvoyé, idéalement avec votre propre ID de corrélation, un hash de la charge utile et un horodatage. Si le processus meurt entre la soumission et le stockage, vous avez payé pour une tâche impossible à récupérer.
2. Interroger avec backoff
Interrogez l'endpoint de statut de la tâche avec l'ID stocké. Le rendu vidéo prend nettement plus de temps que la génération d'image, donc :
- Commencez avec un intervalle modéré — quelques secondes — et augmentez-le à mesure que la tâche dure, plutôt que de marteler l'endpoint à débit fixe.
- Plafonnez le temps d'attente total à une limite adaptée à la tâche, puis considérez la tâche comme expirée et décidez s'il faut réessayer.
- Traitez un état terminal comme définitif : dès que la tâche signale un succès ou un échec, arrêtez l'interrogation.
import time
def wait_for_job(poll_fn, job_id, max_wait=600):
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
job = poll_fn(job_id)
if job["status"] in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
3. Récupérer et stocker la sortie
En cas de succès, l'objet tâche porte l'emplacement du résultat. Téléchargez la vidéo rapidement et copiez-la dans votre propre stockage — l'URL de sortie doit être considérée comme une ressource temporaire, pas comme votre bibliothèque d'actifs permanente. Enregistrez l'ID de tâche à côté du fichier stocké, afin que le support puisse relier n'importe quel clip à sa requête d'origine.
Pour les nouvelles tentatives, interrogez uniquement les tâches dont vous avez stocké l'ID ; ne soumettez jamais à nouveau aveuglément, sous peine de rendus et de facturations en double.
Dépannage des erreurs courantes
Échecs d'authentification (401 / 403)
Vérifiez d'abord l'en-tête Authorization : le mot Bearer, une espace, puis la clé, sans retour à la ligne parasite issu du copier-coller. Confirmez que la clé est active et appartient au compte attendu. Si curl fonctionne mais pas Python, affichez la longueur de l'en-tête — une variable d'environnement vide produit un token qui semble valide mais ne l'est pas.
Charge utile d'image malformée ou non prise en charge (400 / 422)
L'échec le plus fréquent hors authentification. Vérifiez dans l'ordre :
- L'URL de l'image se résout et ne redirige pas vers une page de connexion HTML.
- Le format est JPEG ou PNG, et non WebP, HEIC ou une vignette PDF.
- La taille après encodage ou téléchargement respecte les limites documentées.
- La charge base64 n'a pas de préfixe
data:ni d'espaces issus de retours à la ligne. - L'image n'est pas corrompue — récupérez-la et ouvrez-la vous-même avant d'accuser l'API.
Paramètres inconnus ou invalides
Un nom de champ mal orthographié, ou un paramètre non exposé par l'endpoint, renvoie généralement une erreur de validation qui désigne le champ. Supprimez les paramètres spéculatifs et reconstruisez à partir du minimum défini par la documentation.
Limitation de débit (429)
Appliquez un backoff exponentiel et respectez toute indication de réessai présente dans la réponse. Ne réessayez pas en boucle serrée ; cela aggrave la limitation. Si vous en rencontrez souvent, soumettez par lots via une file d'attente plutôt que de déclencher en ligne depuis une requête utilisateur.
Expiration de tâche et interrogation bloquée
Si une tâche n'atteint jamais un état terminal dans votre budget, journalisez l'ID de tâche et l'historique des statuts, puis arrêtez l'interrogation. Les expirations persistantes indiquent souvent une image trop volumineuse ou anormale à la soumission ; revoyez donc la section de préparation de l'image. Ne soumettez pas automatiquement à nouveau sans plafond de tentatives.
Checklist de production avant mise en ligne
Avant que cet endpoint n'approche du trafic réel, vérifiez chacun des points suivants :
- Des timeouts partout. Une soumission avec timeout court, un plafond d'attente total pour l'interrogation, une limite stricte pour les tentatives. Aucune boucle
while Truenon bornée. - Nouvelles tentatives avec backoff. Réessayez les 429 et les 5xx transitoires ; ne réessayez jamais les erreurs de validation — elles échoueront de la même manière.
- IDs de tâche dans les logs. Journalisez l'ID de tâche, votre ID de corrélation et l'état final pour chaque requête. C'est l'artefact de débogage le plus utile que vous puissiez conserver.
- Sorties stockées dans votre propre stockage. Copiez les vidéos terminées depuis l'URL de retour vers un stockage persistant, et conservez la référence de l'image source pour la reproductibilité.
- Validation d'image en amont. Rejetez les formats incorrects et les uploads surdimensionnés avant l'appel API, pour que les utilisateurs reçoivent immédiatement une erreur claire plutôt qu'un échec asynchrone plusieurs minutes plus tard.
- Conscience des coûts. La génération est facturée par sortie vidéo rendue, donc suivez le volume et la durée des tâches par utilisateur ou fonctionnalité. Consultez le panneau de tarification actuel plutôt que de coder en dur des hypothèses dans le code ou la documentation.
- Prompt canari. Conservez un ensemble d'images et de prompts connus comme bons dans votre suite de tests et exécutez-le après tout changement d'intégration pour confirmer que le contrat de requête tient toujours.
Une fois le cycle de vie asynchrone correctement géré — soumettre, persister, interroger, stocker — l'endpoint est simple. Récupérez le schéma exact sur la page du modèle, puis branchez-vous sur les schémas de soumission et de polling décrits ci-dessus.
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