Guide des prompts MiniMax H3 : composer des mouvements de caméra cinématographiques via l'API
Modèle cible :
minimax-h3
Point de terminaison d'inférence :https://api.toapis.com/v1/videos/generations
Articles liés : Guide de l'API MiniMax H3 · Choisir entre H3 et Turbo · Pipeline R2V automatisé
1. Résumé et vue d'ensemble des performances
- Travail : transformer une liste de plans en prompts MiniMax H3 répétables — sujet, action, trajet de caméra, objectif et éclairage — puis les soumettre au point de terminaison de générations ToAPIs.
- Art du prompt : commencez par l'intention caméra, puis le sujet. Associez une formulation directionnelle à une focale (par exemple 35 mm contre 85 mm) et à une indication d'éclairage.
- Contrat : le
minimax-h3de base accepte des clips entiers de 4–15 s. Utilisezratio(16:9,9:16et les autres ratios listés ci-dessous). C'est le contrat de requête du frontend, pas un benchmark de latence ou de qualité. - Prudence sur la syntaxe : les balises entre crochets sont des aides au prompt. Ne traitez pas
[Pan Left]comme une commande native documentée, sauf si la documentation du modèle en amont l'indique. - Protocole : REST avec Bearer. Soumettez une seule fois, conservez l'identifiant de tâche et interrogez le point de terminaison de statut documenté avec une échéance bornée.
2. Schémas de prompt pour les mouvements de caméra
Un prompt H3 utile décrit une scène et une action principale avant d'ajouter la direction caméra, l'objectif ou le style. Gardez ces éléments stables lors d'un test A/B de modèle ou de durée ; sinon, une reformulation peut expliquer une prise différente.
Les balises du tableau ci-dessous sont des aides au prompt, pas une grammaire de commandes garantie. Le contrat du frontend ToAPIs valide le prompt comme du texte (jusqu'à 7 000 caractères Unicode). Il n'établit pas que des chaînes comme [Pan Left] soient des commandes H3 natives. Utilisez-les comme vocabulaire cohérent dans vos modèles, puis examinez la sortie.
| Aide au prompt | Trajectoire visuelle | Usage typique |
|---|---|---|
[Pan Left] / [Pan Right] | Rotation horizontale sur un axe fixe | Révélations de paysage, balayages de ligne d'horizon urbaine |
[Tilt Up] / [Tilt Down] | Inclinaison verticale depuis une position fixe | Tours, sujets hauts, révélations de ciel |
[Dolly In] / [Dolly Out] | La caméra se rapproche ou s'éloigne du sujet | Renforcer l'accent émotionnel |
[Truck Left] / [Truck Right] | Mouvement de suivi latéral | Accompagner un véhicule ou une personne qui marche |
[Crane Shot] / [Pedestal Up] | Élévation verticale de la caméra | Plans d'ensemble en angle élevé |
[Orbit 180] / [Arc Shot] | Mouvement semi-circulaire autour du sujet | Rotations de produit, révélations de héros |
[Hitchcock Zoom] | Dolly in avec zoom out simultané (ou l'inverse) | Choc psychologique, réalisation soudaine |

Figure 1 : traitez le panoramique, l'inclinaison, le dolly et l'orbite comme des trajectoires dans l'espace du prompt autour d'un sujet, puis soumettez une seule requête de génération via la gateway ToAPIs.
Un modèle compact qui reste testable :
[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES
Exemple : [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.
Pour les tâches avec première image (R2V), le même langage de prompt décrit comment la caméra doit se déplacer autour de l'image d'ancrage ou s'en éloigner. Consultez le tutoriel du pipeline R2V pour les champs de requête. Les entrées d'image et le média de référence restent des modes mutuellement exclusifs.
Les valeurs ratio prises en charge dans le frontend actuel sont adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 et 9:16. Les entrées d'image forcent adaptive. N'envoyez pas aspect_ratio ; le champ du contrat est ratio.
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-h3",
"prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
"duration": 6,
"ratio": "16:9"
}'
Étape 2 : aide au prompt et interrogation en Python
Faites correspondre les noms de champs et le format de réponse à la référence API de votre compte. L'extrait utilise le chemin de statut de tâche également présenté dans d'autres guides vidéo ToAPIs ; confirmez task_id, status et video_url par rapport à ce schéma avant de livrer.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
ENDPOINT = "https://api.toapis.com/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def build_cinematic_prompt(
subject: str,
camera_move: str,
lighting: str,
lens: str = "35mm anamorphic",
) -> str:
return (
f"[{camera_move}] {subject}, {lighting}, "
f"shot on {lens}, photorealistic, cinematic motion blur."
)
def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"ratio": ratio,
}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
interval = 3.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status in {"succeeded", "success"}:
return data["video_url"]
if status in {"failed", "error"}:
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = build_cinematic_prompt(
subject="Matte black mechanical wristwatch resting on volcanic stone",
camera_move="Orbit 180 + Slow Dolly In",
lighting="Moody low-key rim lighting, subtle steam haze",
lens="85mm macro lens",
)
task_id = dispatch_camera_shot(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. Une expiration de délai côté client ne prouve pas que la tâche en amont a échoué : vérifiez l'état avant de soumettre une seconde tâche facturable.
La durée du H3 de base est un entier de 4 à 15 secondes. Les ID de la famille Max commencent à 5 secondes et ont leurs propres listes de résolution ; Turbo n'accepte pas de média de référence. Consultez le guide de l'API avant de changer d'ID.
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.
| Statut HTTP | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide, valeur non prise en charge ou conflit de mode de média | Vérifiez l'ID de modèle, la durée, ratio, la résolution et que les entrées d'image ne sont pas mélangées avec un média de référence |
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 | 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, les unités de facturation et le traitement des tâches en échec varient selon le modèle, la route et le compte. Lisez le catalogue ToAPIs actuel et le devis de votre compte avant de prévoir une liste de plans.
- 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.
- Contrôlez les dépenses au niveau du prompt : conservez un modèle versionné, ne changez qu'une variable à la fois et évitez de resoumettre après une expiration de délai côté client tant que l'état de la tâche n'est pas vérifié.
- Pour arbitrer entre variantes (H3 de base, Max canonique, Turbo), utilisez le guide de sélection plutôt qu'un score de vitesse ou de qualité non vérifié.
6. Questions fréquentes
Voir le bloc FAQ du frontmatter. En résumé : placez l'intention caméra en tête du prompt ; le langage caméra composé est du texte de prompt, pas une grammaire garantie ; la même formulation s'applique en mode première image ; les balises entre crochets ne sont pas des paramètres officiels de l'API.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Testez rapidement l'extrait cURL avec
minimax-h3,ratio: "16:9"et une durée de 6 secondes. - Adoptez l'aide au prompt, conservez les versions du modèle et interrogez avec une échéance de 180 s.
- Étape suivante : le contrat de requête de l'API H3 et le pipeline R2V automatisé.







