Guía de prompts de MiniMax H3: cómo crear movimientos de cámara cinematográficos vía API
Modelo objetivo:
minimax-h3
Endpoint de inferencia:https://api.toapis.com/v1/videos/generations
Relacionado: Guía de la API de MiniMax H3 · Elección entre H3 y Turbo · Pipeline R2V automatizado
1. Resumen y panorama del rendimiento
- Trabajo: convertir una lista de planos en prompts repetibles de MiniMax H3 (sujeto, acción, trayectoria de cámara, óptica e iluminación) y enviarlos al endpoint de generaciones de ToAPIs.
- Arte del prompt: empieza por la intención de cámara y luego el sujeto. Combina una frase direccional con una distancia focal (por ejemplo 35 mm frente a 85 mm) y una indicación de iluminación.
- Contrato:
minimax-h3base acepta clips de 4–15 s enteros. Usaratio(16:9,9:16y las demás relaciones que se listan abajo). Es el contrato de solicitud del frontend, no una comparativa de latencia ni de calidad. - Cuidado con la sintaxis: las etiquetas entre corchetes son ayudas de prompt. No trates
[Pan Left]como un comando nativo documentado salvo que la documentación del modelo upstream lo indique. - Protocolo: REST con Bearer. Envía una sola vez, guarda el identificador de la tarea y consulta el endpoint de estado documentado con un plazo acotado.
2. Patrones de prompt para movimientos de cámara
Un prompt útil para H3 describe una escena y una acción principal antes de añadir dirección de cámara, óptica o estilo. Mantén esas piezas estables cuando hagas una prueba A/B de modelo o de duración; de lo contrario, un cambio de redacción puede explicar una toma distinta.
Las etiquetas de la tabla siguiente son ayudas de prompt, no una gramática de comandos garantizada. El contrato del frontend de ToAPIs valida el prompt como texto (hasta 7.000 caracteres Unicode). No confirma que cadenas como [Pan Left] sean comandos nativos de H3. Úsalas como un vocabulario consistente en tus plantillas y luego revisa la salida.
| Ayuda de prompt | Trayectoria visual | Uso típico |
|---|---|---|
[Pan Left] / [Pan Right] | Rotación horizontal sobre un eje fijo | Revelaciones de paisaje, barridos de horizonte urbano |
[Tilt Up] / [Tilt Down] | Inclinación vertical desde una posición fija | Torres, sujetos altos, revelaciones de cielo |
[Dolly In] / [Dolly Out] | La cámara se acerca o se aleja del sujeto | Acentuar el énfasis emocional |
[Truck Left] / [Truck Right] | Movimiento de seguimiento lateral | Acompañar un vehículo o a alguien que camina |
[Crane Shot] / [Pedestal Up] | Elevación vertical de la cámara | Planos generales en ángulo alto |
[Orbit 180] / [Arc Shot] | Movimiento semicircular alrededor del sujeto | Giros de producto, revelaciones de héroe |
[Hitchcock Zoom] | Dolly in mientras se hace zoom out (o al revés) | Impacto psicológico, revelación súbita |

Figura 1: trata el paneo, la inclinación, el dolly y la órbita como trayectorias dentro del espacio del prompt alrededor de un sujeto, y luego envía una única solicitud de generación a través de la pasarela de ToAPIs.
Una plantilla compacta que sigue siendo comprobable:
[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES
Ejemplo: [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.
Para trabajos de primer fotograma (R2V), el mismo lenguaje de prompt describe cómo debería moverse la cámara alrededor de la imagen ancla o alejándose de ella. Consulta el tutorial del pipeline R2V para ver los campos de la solicitud. Las entradas de fotograma y el material de referencia siguen siendo modos mutuamente excluyentes.
Los valores de ratio admitidos en el frontend actual son adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 y 9:16. Las entradas de fotograma fuerzan adaptive. No envíes aspect_ratio; el campo del contrato es ratio.
3. Implementación en producción: cURL y Python
Paso 1: envío con 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"
}'
Paso 2: ayuda de prompt y sondeo en Python
Ajusta los nombres de campo y el formato de respuesta a la referencia de la API de tu cuenta. El fragmento de abajo usa la ruta de estado de tarea que también aparece en otras guías de vídeo de ToAPIs; confirma task_id, status y video_url contra ese esquema antes de publicar.
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))
Guarda la versión de la plantilla de prompt junto al registro de la tarea para poder distinguir un cambio de modelo de un cambio de redacción. Un tiempo de espera agotado del lado del cliente no demuestra que la tarea upstream haya fallado: comprueba el estado antes de enviar un segundo trabajo facturable.
La duración de H3 base es un entero de 4 a 15 segundos. Los ID de la familia Max empiezan en 5 segundos y tienen sus propias listas de resolución; Turbo no acepta material de referencia. Consulta la guía de la API antes de cambiar de ID.
4. Gestión de errores y matriz de estados
Las categorías de abajo son puntos de partida para el diagnóstico, no una garantía de los códigos de error exactos de ToAPIs.
| Estado HTTP | Categoría habitual | Acción recomendada |
|---|---|---|
400 | Campo inválido, valor no admitido o conflicto de modo de medios | Revisa el ID de modelo, la duración, ratio, la resolución y que las entradas de fotograma no se mezclen con material de referencia |
401 | Clave de API ausente o inválida | Rota la clave en el panel de ToAPIs y confirma la cabecera Authorization |
429 | Límite de frecuencia o de concurrencia | Retrocede con fluctuación aleatoria; reintenta solo cuando sea seguro |
5xx o tiempo de espera agotado en la red | Problema temporal de la pasarela o del upstream | Comprueba el estado de la tarea antes de reenviar; usa una política de reintentos acotada |
5. Precios y retorno de FinOps
- No reutilices precios unitarios de borradores de planificación. Las tarifas por segundo, las unidades de facturación y el tratamiento de las tareas fallidas varían según el modelo, la ruta y la cuenta. Lee el catálogo actual de ToAPIs y la cotización de tu cuenta antes de prever una lista de planos.
- Los contratos oficiales de los proveedores suelen añadir compromisos anuales, cuotas por usuario y mínimos de prepago. La facturación de ToAPIs suele ser pago por uso: confirma las condiciones activas en tu cuenta.
- Controla el gasto en la capa de prompt: mantén una plantilla versionada, cambia una variable cada vez y evita reenviar tras un tiempo de espera agotado del cliente hasta comprobar el estado de la tarea.
- Para sopesar variantes (H3 base, Max canónico, Turbo), usa la guía de elección en lugar de una puntuación de velocidad o de calidad no verificada.
6. Preguntas frecuentes
Consulta el bloque de preguntas frecuentes del frontmatter. En resumen: pon la intención de cámara al inicio del prompt; el lenguaje de cámara compuesto es texto de prompt, no una gramática garantizada; la misma redacción se aplica en el modo de primer fotograma; las etiquetas entre corchetes no son parámetros oficiales de la API.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Haz una prueba rápida del fragmento de cURL con
minimax-h3,ratio: "16:9"y una duración de 6 segundos. - Adopta la ayuda de prompt, guarda las versiones de la plantilla y consulta con un plazo de 180 s.
- Siguiente paso: el contrato de solicitud de la API de H3 y el pipeline R2V automatizado.







