Blog

Tutoriel

Comment utiliser minimax-h3 via l'API HiAPI : curl, Python et requêtes exécutables

Nov 10, 2026
Image de couverture géométrique minimaliste : sur un fond vert pin profond, quelques grands prismes découpés en aplats de couleur, rehaussés de vert sauge et de vert brumeux.
Sur cette page

À quoi ressemble l'intégration de minimax-h3 de bout en bout

La génération vidéo n'est pas une opération instantanée. minimax-h3 doit accepter une invite ou une image source, planifier une tâche sur un pool de GPU, encoder les images et assembler le fichier de sortie. L'ensemble du processus peut prendre de quelques secondes à plusieurs minutes selon la durée et la résolution. Si le point de terminaison HiAPI bloque jusqu'à ce que le fichier soit prêt, votre client HTTP occupera une connexion ouverte pendant toute la durée — ce qui est fragile en cas de nouvelle tentative, peu adapté aux limites de temps des environnements sans serveur, et impossible à exécuter dans un gestionnaire Web de type requête/réponse.

Par conséquent, l'intégration suit la forme soumettre puis interroger, le modèle standard des API multimédias asynchrones :

  1. Soumettre. Vous POST une charge utile JSON décrivant la tâche (invite, image facultative, durée, rapport d'aspect et tout paramètre spécifique au modèle). Après validation, l'API renvoie immédiatement un identifiant de tâche et un état initial.
  2. Interroger. Vous appelez le point de terminaison d'état de la tâche avec cet identifiant à intervalles courts. L'état passe par en file d'attente, en cours de traitement, puis réussi ou échoué.
  3. Récupérer. Une fois que l'état atteint un état terminal, la réponse porte le résultat — généralement une URL téléchargeable de la vidéo générée.

Ce modèle entraîne trois conséquences qui déterminent tout le reste de ce guide :

  • L'ID de tâche est votre seul handle. Persistez-le. Si vous le perdez, vous ne pouvez pas récupérer la tâche ; vous ne pouvez que soumettre à nouveau et payer à nouveau le travail.
  • Votre code a deux surfaces de défaillance, pas une. La soumission peut échouer (authentification, charge utile mal formée), et l'interrogation peut aussi échouer (délai d'attente, erreur réseau transitoire, tâche terminée en échec). Traitez-les séparément.
  • Le rythme d'interrogation est une décision de conception. Trop agressif gaspille des requêtes ; trop lent fait attendre l'utilisateur pour un état déjà prêt depuis longtemps.

Dans cet article, tous les appels sont adressés à l'API unifiée HiAPI. Vous devez obtenir une clé API depuis votre compte HiAPI et référencer le modèle comme minimax-h3 dans la charge utile. Tout le reste — en-têtes d'authentification, URL de base, point de terminaison d'interrogation — est partagé sur toute la plateforme, de sorte que le modèle que vous apprenez ici se transpose à d'autres modèles sans refonte du client.

Avec ce modèle mental, le moyen le plus rapide de confirmer la configuration est un seul appel curl.

Votre première requête curl exécutable

Avant d'écrire du code applicatif, confirmez que votre clé est valide et que vous pouvez accéder à l'API. Une commande curl ponctuelle est le moyen le moins coûteux de distinguer un problème d'authentification d'un problème de charge utile.

Exportez d'abord votre clé, pour qu'elle ne finisse pas en clair dans l'historique du shell :

export HIAPI_API_KEY="your-api-key-here"

Soumettez ensuite une tâche minimale de génération de vidéo à partir de texte :

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Une réponse réussie renvoie un objet JSON contenant l'identifiant de tâche et l'état. Sa structure ressemble à ceci :

{
  "id": "task_abc123xyz",
  "status": "queued",
  "model": "minimax-h3",
  "created_at": "2024-01-01T00:00:00Z"
}

Notez qu'il n'y a pas encore d'URL de vidéo. C'est attendu — la tâche a seulement été acceptée. Les noms de champs dans votre réponse réelle peuvent différer légèrement de ce qui précède ; lisez le corps de la réponse plutôt que de supposer, et journalisez l'intégralité du contenu pendant le développement.

Ce que fait chaque partie de la requête

  • L'URL pointe vers la ressource de génération vidéo sur la plateforme HiAPI. Tous les appels de modèle partagent cette base, c'est pourquoi changer de modèle consiste seulement à modifier la charge utile plutôt qu'à réécrire le code.
  • Authorization: Bearer transporte votre clé API. C'est la source d'échec la plus courante, donc vérifiez-la en premier quand quelque chose ne va pas.
  • Content-Type: application/json est obligatoire. Sans lui, le serveur peut rejeter ou mal analyser le corps de la requête.
  • model sélectionne explicitement minimax-h3. Ne l'omettez jamais — la plateforme effectue le routage sur cette valeur.
  • prompt est l'instruction créative. Soyez précis sur le sujet, le mouvement de caméra et l'éclairage ; une invite vague produit une vidéo vague.
  • duration et aspect_ratio contraignent la sortie. Maintenez-les dans les plages prises en charge par le modèle ; les valeurs hors plage sont des erreurs de validation de charge utile, pas des pannes de serveur.

Confirmer que la tâche existe

Immédiatement après la soumission, récupérez une fois la tâche pour prouver que l'ID est valide :

curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Remplacez task_abc123xyz par l'ID de la réponse de soumission. Si cela renvoie un état, alors votre clé, votre point de terminaison et votre handle de tâche sont tous corrects — vous pouvez passer à Python.

Deux habitudes valent la peine d'être prises dès maintenant : exécutez curl avec -sS pour faire remonter les erreurs plutôt que de les avaler silencieusement, et entourez toujours les URL de guillemets. L'expansion shell inattendue dans une charge utile JSON est un piège de débogage qui coûte beaucoup plus de temps que les guillemets eux-mêmes.

Construire la même requête en Python

L'appel curl a prouvé le contrat ; Python est l'endroit où vous construisez du réutilisable. Ne sautez pas directement à la boucle d'interrogation — commencez par une petite classe de client qui traite la soumission et la récupération de résultat comme deux méthodes claires. Cette séparation garde la logique asynchrone hors de votre couche de transport.

Utilisez requests (ou httpx si vous préférez l'asynchrone) ; la forme est identique dans les deux cas.

import os
import time
import requests

BASE_URL = "https://api.hiapi.ai/v1"

class MiniMaxH3Client:
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ["HIAPI_API_KEY"]
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        })

    def submit(self, prompt: str, duration: int = 5,
               aspect_ratio: str = "16:9", **extra) -> str:
        payload = {
            "model": "minimax-h3",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            **extra,
        }
        resp = self.session.post(
            f"{BASE_URL}/video/generations",
            json=payload,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        return data["id"]

Plusieurs choix délibérés méritent d'être signalés ici.

Utilisez une session, pas des requêtes nues. Réutiliser requests.Session maintient la connexion active entre les appels de soumission et d'interrogation, ce qui compte lorsque vous interrogez le même hôte de manière répétée. Cela centralise aussi les en-têtes, de sorte que l'en-tête d'authentification n'est défini qu'une seule fois.

Définissez un délai d'attente strict lors de la soumission. Trente secondes sont généreuses pour une requête qui devrait presque revenir immédiatement. Sans délai d'attente, une gigue réseau ferait pendre votre processus indéfiniment. Ne faites jamais d'appel d'API distant sans définir de timeout.

Appelez raise_for_status() avant l'analyse. Le corps de réponse d'une réponse non 2xx a souvent une forme différente de celle d'une réponse réussie. Vérifier d'abord le code d'état signifie que votre gestion d'erreur lit un message d'erreur bien formé plutôt que de planter sur une clé id manquante.

Transmission de **extra. Les options propres au modèle évoluent. Transmettre des arguments nommés supplémentaires vous permet d'expérimenter de nouveaux paramètres sans modifier la signature de la méthode à chaque fois.

Utilisation

client = MiniMaxH3Client()
task_id = client.submit(
    "A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")

C'est tout le chemin de soumission. Le client renvoie une chaîne — le handle de tâche — rien d'autre. Résistez à l'envie de faire attendre aussi le résultat à submit. Mélanger soumission et attente dans une seule méthode rend les nouvelles tentatives ambiguës : en cas d'échec, vous ne pouvez pas savoir si la tâche a été créée, avec donc un risque de génération en double. Gardez-les séparées et laissez l'appelant décider de la stratégie.

Interroger le résultat sans bombarder l'API

L'interrogation est la partie la plus facile à mal écrire. Une boucle naïve while True sans délai enverra des centaines de requêtes pour une tâche qui prend deux minutes, et continuera même après que la tâche a déjà échoué.

Une boucle d'interrogation correcte a quatre responsabilités : vérifier l'état, attendre, s'arrêter sur un état terminal, et finalement abandonner.

TERMINAL = {"succeeded", "failed", "cancelled"}

def wait_for(self, task_id: str, interval: float = 3.0,
             max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status", "unknown")
        if status in TERMINAL:
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")

Choisir l'intervalle

Pour la génération vidéo, quelques secondes fixes constituent une valeur par défaut raisonnable. Les tâches ne se terminent pas dans les premières secondes — le chargement du modèle et l'encodage des images prennent un temps réel — donc interroger toutes les 200 ms n'apporte rien d'autre que de la charge. Si vous voulez être à la fois courtois et efficace, utilisez un backoff exponentiel plafonné : commencez à une ou deux secondes, multipliez par environ 1,5 à chaque tour jusqu'à atteindre cinq ou dix secondes, puis restez-y. Les premières interrogations capturent rapidement les échecs rapides ; les interrogations tardives restent peu coûteuses pendant les longs rendus.

S'arrêter correctement

Traitez tout état non reconnu comme non terminal et continuez d'attendre — mais seulement jusqu'à une certaine limite. Deux conditions d'arrêt comptent :

  • L'état terminal. Renvoyez immédiatement en cas de succès. En cas d'échec, faites remonter le message d'erreur de la réponse plutôt que de renvoyer un résultat vide ; la cause compte pour vos journaux.
  • Le budget de temps réel. Utilisez une horloge monotone, pas l'heure murale, pour que les ajustements de l'horloge système ne fassent pas sortir votre boucle trop tôt ou tourner indéfiniment. Choisissez une limite confortablement supérieure à la tâche réaliste la plus longue pour la durée et la résolution choisies, et traitez son atteinte comme une erreur opérationnelle à signaler.

Renvoyer le résultat

Lorsque l'état est un succès terminal, la réponse porte l'URL de la vidéo générée. Téléchargez-la rapidement — les URL de résultat ont généralement une expiration — et stockez-la dans votre propre stockage objet si vous avez besoin d'un accès persistant. Ne transmettez pas l'URL du fournisseur directement à l'utilisateur final en supposant qu'elle existera pour toujours.

Un autre conseil pratique : journalisez au niveau debug l'ID de tâche, l'état et le temps écoulé à chaque interrogation, et le résultat terminal au niveau info. Lorsqu'une tâche prend plus de temps que prévu, cette chronologie fait la différence entre cinq minutes de diagnostic et une heure de conjectures.

Formes de requête pour la génération de vidéo à partir de texte et à partir d'image

Les deux modes de génération partagent la majeure partie de la charge utile. La différence réside dans l'entrée créative, et cette différence a des conséquences en aval sur le type d'échec à attendre.

Génération de vidéo à partir de texte

C'est la forme montrée dans les sections précédentes : une invite plus des contraintes de sortie. Le modèle invente tout — composition, mouvement, éclairage et détails du sujet. Votre charge utile porte :

  • model : minimax-h3
  • prompt : la description de la scène
  • duration, aspect_ratio et tout autre contrôle de sortie

Comme il n'y a aucun ancrage, la qualité de l'invite domine le résultat. Décrivez le comportement de la caméra (« lent travelling avant », « plan fixe sur trépied ») et l'éclairage (« contre-jour à l'heure dorée »), plutôt que d'empiler des adjectifs sur la qualité. Les adjectifs vagues du type « de qualité supérieure » ont peu d'effet ; les descriptions physiques concrètes en ont beaucoup.

Génération de vidéo à partir d'image

La variante image-vers-vidéo ajoute une référence d'image source à la même requête. Généralement, vous fournissez une URL d'image ou un identifiant de ressource téléversée dans un champ d'image à côté de l'invite, et le modèle anime à partir de cette image de départ.

client.submit(
    "Gentle wind moves the hair, subtle camera push forward",
    duration=5,
    image_url="https://example.com/portraits/source.jpg",
)

L'invite joue maintenant un rôle différent : elle guide le mouvement et la caméra, pas le contenu, car le contenu visuel est déjà fixé par l'image. Écrire une description complète de scène est souvent contre-productif — le modèle ne peut pas ajouter de détails qui ne sont pas présents dans l'image. Gardez l'invite de mouvement courte et spécifique.

Consultez la référence de requête pour connaître les noms de champs exacts et les formats d'image acceptés dans le mode image, ainsi que les plages valides de durée et de rapport d'aspect dans les deux modes. Ce sont précisément ces contraintes qui déclenchent les erreurs de validation de charge utile, donc les lire une fois vous épargne une série de débogages ultérieurs.

Une règle empirique utile

Choisissez la génération texte-vers-vidéo lorsque vous avez besoin de scènes inédites — B-roll, clips d'ambiance, visualisation de concepts. Choisissez image-vers-vidéo lorsque la cohérence compte : animer des photos de produits, donner vie à des portraits de personnages, ou transformer des images de storyboard en plans animés. Le mode est une différence de charge utile, pas une différence d'intégration, donc une seule classe de client peut servir les deux en acceptant simplement un paramètre d'image facultatif.

Déboguer les erreurs courantes

Quand un appel à minimax-h3 échoue, la cause se trouve presque toujours à l'un de quatre endroits. Diagnostiquez dans cet ordre.

1. Authentification

Symptôme : réponse 401 ou 403, ou un corps d'erreur déclarant des identifiants invalides.

  • Confirmez que l'en-tête Authorization est présent et au format Bearer <key>, avec un espace entre les deux.
  • Vérifiez que la variable d'environnement contient bien une valeur — un saut de ligne final collé dans une variable d'environnement corrompt l'en-tête de manière invisible dans les journaux.
  • Vérifiez que la clé appartient au même projet HiAPI que celui attendu et n'a pas été renouvelée.

Le test le plus rapide : relancez le curl brut précédent. Si curl fonctionne et Python non, le bug est dans votre client, pas dans votre compte.

2. Charge utile mal formée

Symptôme : réponse 400 ou 422, ou message de validation sur un paramètre nommé.

  • Confirmez Content-Type: application/json et que le corps est un JSON valide — une virgule finale superflue est le coupable classique.
  • Vérifiez que model vaut exactement minimax-h3.
  • Confirmez que duration et aspect_ratio sont dans les plages prises en charge par le modèle.
  • En mode image, confirmez que la référence d'image est accessible et dans un format accepté.

Lisez littéralement le message d'erreur. Les erreurs de validation nomment généralement le champ en infraction ; les développeurs les survolent souvent et commencent à réécrire des parties non liées de la charge utile.

3. L'interrogation ne se termine jamais

Symptôme : l'état reste en file d'attente ou en cours après une durée raisonnable, ou boucle indéfiniment.

  • Journalisez la réponse d'état complète — la valeur d'état peut ne pas être celle supposée par votre code.
  • Vérifiez le champ que vous lisez. Si votre ensemble terminal vérifie "completed" alors que l'API renvoie "succeeded", votre boucle tournera pour toujours. Imprimez une réponse brute tôt pendant le développement.
  • Confirmez que l'ID de tâche a été copié exactement, sans troncature ni espace.
  • Ajoutez une échéance en temps réel ; une boucle bloquée sans limite est un bug de votre code, pas de l'API.

4. Délais d'attente et erreurs réseau transitoires

Symptôme : erreurs de connexion, délais de lecture, ou réponses 5xx lors de la soumission ou de l'interrogation.

  • Assurez-vous qu'un timeout explicite est passé à chaque appel — la valeur par défaut de nombreux clients est aucune, ce qui signifie qu'un socket suspendu peut bloquer pour toujours.
  • Distinguez le délai de connexion du délai de lecture ; une soumission dont la lecture expire peut en fait avoir créé la tâche. Si un ID de requête est renvoyé, journalisez-le depuis les en-têtes de réponse et vérifiez si une tâche est apparue avant de resoumettre aveuglément.
  • Pour les 5xx d'interrogation, réessayez — la tâche peut aller bien. Pour les 5xx de soumission, vérifiez qu'aucune tâche n'a été créée afin d'éviter une génération en double.

Une habitude de tri rapide : gardez un fichier curl de brouillon à côté de votre projet, avec les commandes de soumission et d'interrogation préremplies depuis les variables d'environnement. Reproduire n'importe quel bug en dehors du code applicatif prend quelques secondes et vous dit immédiatement si le problème est de transport ou de logique.

Le rendre prêt pour la production

Un script exécutable n'est pas un service exploitable. Les tâches vidéo sont suffisamment lentes pour que le trafic de production se chevauche, réessaie et échoue parfois d'une manière qu'une exécution manuelle unique ne révélera jamais. Quatre modèles portent l'essentiel du poids.

Nouvelles tentatives avec backoff — mais seulement là où c'est sûr

La stratégie de nouvelle tentative dépend de l'appel qui échoue :

  • L'interrogation peut être réessayée sans risque par nature. Une vérification d'état échouée n'a pas d'effet secondaire, donc réessayez avec un backoff exponentiel avec gigue, limité à quelques essais.
  • La soumission ne peut pas être réessayée aveuglément. Un délai d'attente ne signifie pas que la tâche n'a pas été créée. Avant de resoumettre, vérifiez si une tâche pour cette requête existe déjà (en utilisant l'ID de requête des en-têtes de réponse si disponible, ou une courte fenêtre de réconciliation). Alternativement, rendez vos propres soumissions idempotentes en mettant en cache les ID de tâche par hachage de charge utile, de sorte qu'une requête réessayée renvoie la tâche existante plutôt que de lancer un nouveau rendu.
  • Les échecs au niveau du modèle — l'état terminal failed — ne doivent généralement pas être réessayés automatiquement avec la même charge utile. Les mêmes entrées ont tendance à échouer de la même manière. Journalisez, alertez, et laissez un humain ou une invite modifiée prendre le relais.

Ajoutez de la gigue à chaque sommeil de backoff. Sans elle, une vague de workers qui réessaient en synchronie produit des pics synchrones, ce qui aggrave une mauvaise situation.

Journaliser l'ID de tâche partout

L'ID de tâche est le seul lien durable entre votre système et la vidéo générée. Au moment où la soumission réussit, écrivez-le dans les journaux avec des champs structurés — task_id, modèle, durée, horodatage de soumission. Quand un utilisateur signale une vidéo perdue, une recherche par ID de tâche retrouve l'historique complet en quelques secondes. Journalisez aussi l'état terminal et le temps écoulé, pour pouvoir répondre avec des données plutôt qu'avec votre mémoire à la question « combien de temps cela prend-il habituellement ».

Définir un budget de délais d'attente explicite

Pensez en termes de budget total pour l'opération entière, pas seulement de délai d'attente par requête. Une tâche a trois phases — soumission, attente, téléchargement — et chacune a besoin de limites. Une structure raisonnable :

  • Délais d'attente courts pour les requêtes de soumission et d'interrogation, afin de détecter rapidement les connexions mortes.
  • Une limite totale en temps réel pour l'interrogation, fixée selon la durée et la résolution les plus longues que vous prenez en charge, avec une marge.
  • Un téléchargement borné avec écriture en flux, pour que les gros fichiers n'épuisent pas la mémoire ni ne bloquent le worker.

Quand le budget est épuisé, faites échouer proprement la tâche, libérez le slot de concurrence et signalez une erreur claire. Un échec prévisible vaut mieux qu'une requête qui reste suspendue jusqu'à ce que la plateforme redémarre le conteneur.

Séparer la soumission de la consommation

La conception soumettre-puis-interroger se transpose naturellement à une architecture de file d'attente : votre gestionnaire Web soumet et renvoie un ID de tâche, un worker en arrière-plan interroge et stocke le résultat, et le client interroge votre point de terminaison d'état. Cela découple la latence perçue par l'utilisateur du temps de rendu, rend les limites de concurrence faciles à appliquer, et signifie qu'un pic de soumissions n'épuisera pas le pool de threads de votre couche Web.

Bien maîtriser ces quatre points, et la nature asynchrone de minimax-h3 travaillera avec vous plutôt que contre vous : les tâches sont suivies, les nouvelles tentatives sont sûres, les échecs sont visibles, et rien ne reste suspendu indéfiniment.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API