Comment utiliser l'API MiniMax H3 Max ? Générer une vidéo à partir d'un texte ou d'une image

Sur HiAPI, MiniMax H3 Max est proposé sous deux noms de modèles : texte-vers-vidéo minimax-h3-max/text-to-video et image-vers-vidéo minimax-h3-max/image-to-video. Il génère des vidéos de 0,92 à 15 secondes, à $0.072 par seconde en 480P, $0.115 par seconde en 768P et $0.229 par seconde en 1080P, facturées selon le nombre de secondes demandé. Commencez par générer un court métrage paysage de 5 secondes avec le prompt du bateau en papier ci-dessous : le budget en 768P est de $0.575. Pour l'intégration à l'API, soumettez une tâche, puis récupérez la vidéo grâce au taskId renvoyé.

MiniMax H3 Max est disponible sur HiAPI, générez avec ce prompt →. Le prompt est rempli automatiquement ; sélectionnez ensuite manuellement 5 secondes, 768P et 16:9.

Première vidéo : un bateau en papier après la pluie

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

générez avec ce prompt →

Ce prompt sépare l'action et le mouvement de caméra : le bateau en papier dérive au fil de l'eau, une caméra basse le suit en douceur, et le chant lointain des oiseaux donne l'ambiance sonore. Pour remplacer le bateau en papier par votre propre sujet, conservez d'abord une action et un mouvement de caméra : il sera plus facile de voir ce qu'il faut ajuster.

Essai en ligne ou intégration API : que choisir ?

Pour d'abord voir le rendu, ouvrez la page du modèle texte-vers-vidéo, copiez le prompt, choisissez la durée et la résolution, puis lancez la génération ; si vous avez déjà une image de départ, passez à la page du modèle image-vers-vidéo pour téléverser l'image de première frame. Pour intégrer l'API dans une application, commencez par récupérer une clé sur la page des clés API, créez la tâche via une requête côté serveur, conservez le taskId, puis, une fois la tâche réussie, lisez l'URL de la vidéo.

Il est conseillé d'indiquer explicitement la résolution : 5 secondes en 480P coûtent $0.36, en 768P $0.575 et en 1080P $1.145. Confirmez d'abord l'action en basse résolution, puis choisissez le palier selon vos besoins de livraison ; le budget complet figure dans le tableau des tarifs H3 et H3 Max.

cURL : créer une tâche, puis consulter le résultat

Après avoir défini la clé API dans la variable d'environnement locale HIAPI_API_KEY, exécutez cette requête :

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

En cas de délai dépassé sur le POST, d'interruption de connexion ou de réponse impossible à interpréter quant au résultat de la création, l'état de soumission est inconnu : consultez d'abord l'historique des tâches et ne relancez pas directement le POST. Après avoir vérifié que la réponse contient code=200, que data est un objet et que data.taskId n'est pas vide, conservez l'ID et remplacez YOUR_TASK_ID dans l'URL de consultation :

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Pour une tâche en attente, continuez d'interroger le même ID. Lorsque data.status vaut success, lisez le champ url de l'entrée vidéo dans data.output ; s'il vaut fail, consultez le message d'erreur de la tâche ; en cas d'erreur d'entrée ou d'authentification, corrigez d'abord le problème correspondant, puis, comme l'ID de tâche existe déjà, continuez d'interroger cette tâche.

Python : soumettre une fois, attendre la même tâche

L'exemple ci-dessous utilise la bibliothèque standard Python. Un seul POST est effectué, et sa réponse est validée ; si le résultat de la soumission est inconnu, le script s'arrête et invite à consulter l'historique des tâches. En cas d'échec temporaire d'une requête de consultation, l'ID de tâche est conservé et les GET continuent ; 600 secondes est la limite d'attente de cet exemple.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Utiliser une image pour contrôler la première ou la dernière frame

Pour que la vidéo commence par l'image de votre propre produit, remplacez le nom du modèle par minimax-h3-max/image-to-video et ajoutez first_frame_image dans input ; pour imposer la fin, ajoutez last_frame_image. Vous pouvez transmettre uniquement la dernière frame, ou les deux frames à la fois ; le modèle image-vers-vidéo n'a pas de champ aspect_ratio, le format suit celui de l'image.

Champ	Usage
prompt	Obligatoire, 50000 caractères maximum, décrit l'action, le mouvement de caméra et le son
duration	0,92 à 15 secondes, décimales autorisées, 5 secondes par défaut
resolution	480P, 768P ou 1080P, 768P par défaut
aspect_ratio	Uniquement pour le texte-vers-vidéo : 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, 16:9 par défaut
first_frame_image	Image-vers-vidéo : URL publique de l'image de première frame
last_frame_image	Image-vers-vidéo : URL publique de l'image de dernière frame
target_audio_url	Facultatif, remplace la piste audio par la vôtre, au moins 2 secondes
prompt_expansion_mode	Facultatif, disabled / balanced (par défaut) / quality

Voici le corps de requête complet avec les deux frames ; les URL d'image sont des exemples à remplacer par vos propres adresses accessibles publiquement ; les images définissent la composition de départ et de fin :

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Si vous ne voulez contrôler que la dernière frame, supprimez first_frame_image et conservez last_frame_image. Ne décrivez dans le prompt que le mouvement de caméra ; les images se chargent du sujet et de la composition initiale. Pour plusieurs plans, précisez chaque transition dans le prompt ; les champs de requête restent ceux de ce tableau, n'ajoutez pas camera_angle, mode ou watermark.

Pour un court métrage vertical, indiquez directement "aspect_ratio": "9:16" en texte-vers-vidéo ; en image-vers-vidéo, utilisez une image de première frame au format portrait, le format suivra l'image.

Dans une application : placez le callback au niveau racine de la requête

Ajoutez un callback facultatif au niveau racine de la requête de création, aux côtés de model et input :

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Intégrez ce bloc dans la requête complète. Le récepteur déduplique selon taskId, traite séparément les succès et les échecs, et récupère les notifications manquantes via la consultation de tâche. Une fois l'ID de tâche obtenu, ne soumettez pas à nouveau ; en cas d'erreur HTTP, lisez d'abord le contenu de la réponse pour distinguer un problème d'authentification d'un problème de paramètres.

Quatre vérifications après l'intégration

1. Conservez un data.taskId non vide et continuez à l'utiliser après une erreur de consultation.
2. Vérifiez que l'état final est success ou fail, sans confondre la limite d'attente avec le temps de traitement du modèle.
3. Dans data.output d'une tâche réussie, recherchez l'URL de vidéo avec type=video.
4. Téléchargez le résultat et vérifiez que les dimensions, la durée et l'image réelles correspondent aux exigences de livraison.

Questions fréquentes

H3 Max peut-il utiliser une vidéo ou un audio de référence ? H3 Max remplace la piste audio avec target_audio_url et n'accepte pas de vidéo de référence ; si vous avez besoin de références multimodales image, vidéo et audio, choisissez MiniMax H3.

Max est-il plus cher que H3 ? H3 2K coûte $0.1189 par seconde, Max coûte $0.115 par seconde en 768P et $0.229 par seconde en 1080P. Choisissez d'abord le modèle selon la résolution et les médias de référence nécessaires, puis calculez le budget à partir de la durée.

Comment commencer un court métrage vertical ? En texte-vers-vidéo, indiquez "aspect_ratio": "9:16" ; en image-vers-vidéo, préparez une image de première frame au format portrait, le format suivra l'image.

Copiez le prompt du bateau en papier, générez avec ce prompt →, et réalisez d'abord un court métrage de 5 secondes. Pour plus d'exemples d'actions et de mouvements de caméra, voir 4 vraies vidéos et leurs prompts complets ; pour la liste complète des champs, voir la documentation des paramètres texte-vers-vidéo et la documentation des paramètres image-vers-vidéo.