Intégration de l'API MiniMax Hailuo 2.3 : générer des mouvements humains complexes en vidéo IA
Modèle cible :
MiniMax-Hailuo-2.3
Point de terminaison d'inférence :https://api.toapis.com/v1/videos/generations
Articles liés : Guide de l'API MiniMax H3 · Prompts de mouvement de caméra H3 · Pipeline R2V automatisé
1. Résumé et vue d'ensemble des performances
- Travail : soumettre des tâches texte vers vidéo ou image vers vidéo avec première image pour des clips de personnages et de mouvement humain au point de terminaison de générations ToAPIs.
- Contrat :
MiniMax-Hailuo-2.3accepte des durées entières de 6 ou 10 secondes et des résolutions768Pou1080P.1080Pne prend en charge que 6 secondes. La référence API actuelle limite le prompt à 2 000 caractères. - ID : utilisez la chaîne du catalogue
MiniMax-Hailuo-2.3(texte vers vidéo et image vers vidéo).MiniMax-Hailuo-2.3-Fastest uniquement image vers vidéo et exige une URL de première image. Aucun des deux ID n'est interchangeable avecminimax-h3. - Langage caméra : la référence ToAPIs de Hailuo 2.3 documente des directives entre crochets comme
[Push in]et[Pan left, Pedestal up]. Traitez le tableau ci-dessous comme le vocabulaire documenté actuel, puis vérifiez-le dans la documentation en vigueur avant de coder en dur une grammaire de plans. - Protocole : REST avec Bearer. Conservez l'
idde tâche de l'enveloppe de soumission et interrogezGET /v1/videos/generations/{task_id}(ouGET /v1/tasks/{task_id}) avec une échéance bornée. Une expiration côté client ne prouve pas que la tâche en amont a échoué.
2. Schémas de prompt pour le mouvement humain
Le catalogue public ToAPIs décrit MiniMax Hailuo 2.3 comme un modèle vidéo pour le mouvement de personnage, les expressions et le style dans des récits expressifs et des clips de personnages. C'est du positionnement produit, pas un benchmark indépendant de « zéro déformation des membres ». Pour la production, écrivez des prompts qui décrivent un sujet et une action principale dans un langage mécanique clair, puis examinez la prise.
Un prompt de mouvement humain utile nomme la mécanique corporelle avant d'ajouter le style : qui bouge, quel membre mène, comment le poids se déplace, et comment l'action commence et se termine. Gardez ce noyau stable lors d'un test A/B de durée ou de résolution ; sinon, une reformulation peut expliquer une prise différente.
La référence ToAPIs de l'API Hailuo 2.3 documente les directives caméra ci-dessous. Elles figurent dans la chaîne de prompt, pas dans un champ de requête séparé. Le contrat de requête du frontend valide toujours prompt comme du texte. Combinez au plus trois directives dans un même crochet pour un mouvement simultané, ou enchaînez-les dans la phrase pour des mouvements ordonnés.
| Catégorie | Directives documentées |
|---|---|
| Pan | [Pan left], [Pan right] |
| Tilt | [Tilt up], [Tilt down] |
| Push / Pull | [Push in], [Pull out] |
| Pedestal | [Pedestal up], [Pedestal down] |
| Truck | [Truck left], [Truck right] |
| Zoom | [Zoom in], [Zoom out] |
| Autres | [Shake], [Tracking shot], [Static shot] |

Figure 1 : traitez une pose fixe comme entrée de première image, décrivez l'action suivante dans le prompt et soumettez une seule requête de génération via la gateway ToAPIs.
Un modèle compact qui reste testable :
SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES
Exemple : A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.
Pour l'image vers vidéo, envoyez une URL de première image accessible publiquement dans image_urls. L'image est l'image de départ ; le prompt décrit le mouvement qui suit. Les limites d'image documentées actuellement sont JPG, JPEG, PNG ou WebP ; moins de 20 Mo ; petit côté supérieur à 300 px ; et un ratio entre 2:5 et 5:2. Ne placez pas de base64 dans image_urls : téléversez d'abord un fichier local.
MiniMax-Hailuo-2.3-Fast n'accepte pas le texte vers vidéo : une URL de première image est requise. Hailuo 2.3 ne documente pas de champ de dernière image ; l'interpolation première vers dernière image relève de MiniMax-Hailuo-02, pas de cet ID. Ne copiez pas de champs H3 comme ratio ou reference_videos dans une requête Hailuo 2.3.
Les libellés d'options du Playground peuvent afficher 768p / 1080p en minuscules. Les exemples API actuels utilisent 768P et 1080P. Confirmez la valeur acceptée par votre compte avant d'automatiser un lot. La même formulation caméra peut être réutilisée lorsque vous transférez un plan vers MiniMax H3, mais les contrats de durée, de résolution et de mode de média sont différents — ne changez d'ID qu'après avoir relu ce guide.
3. Implémentation en production : cURL et Python
Étape 1 : envoi cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-Hailuo-2.3",
"prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
"duration": 6,
"resolution": "768P"
}'
Étape 2 : aide et interrogation en Python
La documentation officielle mentionne actuellement l'origine publique https://toapis.com (et https://toapis.cn pour la Chine continentale). D'autres guides ToAPIs de cette série utilisent https://api.toapis.com. Choisissez une URL de base et restez cohérent. L'extrait suit le chemin de statut de tâche documenté et les états completed / failed ; confirmez id, result.data[0].url et l'enveloppe par rapport à la référence API de votre compte avant de livrer.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_motion_clip(
prompt: str,
duration: int = 6,
resolution: str = "768P",
image_url: str | None = None,
model: str = "MiniMax-Hailuo-2.3",
) -> str:
if resolution == "1080P" and duration != 6:
raise ValueError("1080P currently supports a 6-second duration only")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"metadata": {"prompt_optimizer": True, "aigc_watermark": False},
}
if image_url:
payload["image_urls"] = [image_url]
elif model == "MiniMax-Hailuo-2.3-Fast":
raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 300) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 5.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = (
"A contemporary dancer in a black practice leotard plants the left foot, "
"then uncoils a slow 360-degree turn with the right arm leading and the "
"torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
"photorealistic, no morphing limbs"
)
task_id = dispatch_motion_clip(prompt)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Conservez la version du modèle de prompt à côté de l'enregistrement de la tâche pour distinguer un changement de modèle d'une reformulation. Si vous avez besoin d'une tâche avec première image, passez image_url= à dispatch_motion_clip. Pour la SKU Fast, cet argument est obligatoire.
La durée du Hailuo 2.3 de base est de 6 ou 10 secondes. N'envoyez pas 1080P avec duration: 10. Si vous avez besoin de clips continus de 4 à 15 secondes, de média de référence ou d'entrées de dernière image, il s'agit d'un autre contrat — consultez le guide de l'API H3 et le tutoriel du pipeline R2V.
4. Gestion des erreurs et matrice des statuts
Les catégories ci-dessous sont des points de départ pour le diagnostic, et non une garantie des codes d'erreur exacts de ToAPIs. Une requête HTTP réussie exige toujours de lire le status de la tâche.
| Statut HTTP | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide, combinaison non prise en charge ou conflit de mode de média | Vérifiez l'ID de modèle exact, que la durée est 6 ou 10, que 1080P n'est associé qu'à 6 secondes et que les tâches Fast incluent image_urls. N'envoyez pas de champ de dernière image sur Hailuo 2.3 |
401 | Clé API absente ou invalide | Faites tourner la clé dans le tableau de bord ToAPIs et confirmez l'en-tête Authorization |
429 | Limite de débit ou de concurrence | Respectez Retry-After lorsqu'il est présent ; reculez avec du jitter ; ne réessayez que lorsque c'est sûr |
5xx ou expiration réseau | Problème temporaire de gateway ou d'amont | Vérifiez l'état de la tâche avant de resoumettre ; appliquez une politique de nouvelle tentative bornée |
5. Tarifs et retour sur investissement FinOps
- Ne réutilisez pas les prix unitaires des brouillons de planification. Les tarifs à la seconde ou par vidéo, les unités de facturation et le traitement des tâches en échec varient selon le modèle, la résolution, la durée, la route et le compte. Les lignes de référence officielles du fournisseur sur la page de tarifs ToAPIs sont purement indicatives et peuvent différer de ce qui est facturé à votre compte. Lisez le catalogue actuel et le devis de votre compte avant de prévoir une liste de plans.
- Fast est une autre SKU, pas un interrupteur de vitesse gratuit sur le même ID.
MiniMax-Hailuo-2.3-Fastest documenté comme image vers vidéo uniquement. Confirmez séparément son prix actuel sur votre compte. - Contrôlez les dépenses au niveau du prompt : travaillez en
768Pet 6 secondes, gardez un modèle versionné, ne changez qu'une variable à la fois et ne resoumettez pas après une expiration côté client tant que l'état de la tâche n'est pas vérifié. - Les contrats officiels des fournisseurs ajoutent souvent des engagements annuels, des quotas par siège et des minimums de prépaiement. La facturation ToAPIs est généralement un paiement à l'usage — confirmez les conditions actives de votre compte.
6. Questions fréquentes
Voir le bloc FAQ du frontmatter. En résumé : la chaîne de modèle de la requête est MiniMax-Hailuo-2.3, pas un slug à tirets et pas un ID H3 ; 1080P est limité à 6 secondes ; Fast exige une URL de première image et ne prend pas en charge le texte vers vidéo ; les directives caméra documentées figurent dans le prompt, pas dans des champs séparés ; Hailuo 2.3 n'a pas d'entrée de dernière image.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Testez rapidement l'extrait cURL avec
MiniMax-Hailuo-2.3,resolution: "768P"et une durée de 6 secondes. - Confirmez si votre compte attend
768Pou768p, puis interrogezGET /v1/videos/generations/{id}avec une échéance bornée. - Étape suivante : le guide des mouvements de caméra H3 si vous avez besoin d'une autre durée ou d'un autre contrat de média, et le guide du modèle Hailuo 2.3 pour l'état du catalogue en production.







