Guía de la API de MiniMax H3: texto a vídeo y entradas de referencia
Las solicitudes a MiniMax H3 son fáciles de configurar mal cuando un cliente trata todas las variantes del modelo como si fueran intercambiables. El ID de modelo que elijas afecta la validación de la duración y de la resolución, mientras que el modo de medios decide qué campos de imagen, vídeo y audio puedes enviar juntos.
Esta guía describe el contrato de solicitud tal como está implementado en el frontend de ToAPIs a 22 de octubre de 2026. Es una guía de integración, no un informe sobre el rendimiento del proveedor upstream ni sobre el precio actual de tu cuenta. Confirma que tu cuenta tiene acceso al modelo que vas a usar antes de enviar trabajos de producción.
Inicio rápido
El endpoint de generación que usan los ejemplos de la API de ToAPIs es POST /v1/videos/generations. Autentícate con una clave de API de ToAPIs y envía un prompt, un ID de modelo habilitado, la duración y la relación de aspecto. Por ejemplo:
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": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9"
}'
Trata la respuesta como el envío de una tarea asíncrona. Lee el identificador de tarea que devuelve la respuesta de la API de tu cuenta y consulta su estado con el endpoint de estado documentado. No des por hecho un formato de respuesta fijo salvo que la referencia de la API de tu cuenta lo especifique.
import os
import time
import requests
BASE_URL = "https://api.toapis.com/v1"
API_KEY = os.environ["TOAPIS_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json={
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9",
},
timeout=30,
)
response.raise_for_status()
submission = response.json()
print("Submission response:", submission)
El ejemplo imprime la respuesta a propósito, en lugar de suponer dónde aparecen el ID de la tarea o la URL del vídeo. Ajusta el código de lectura y de consulta al esquema de respuesta documentado para tu cuenta. Así evitas tratar en silencio un formato modificado como si fuera una tarea correcta.
Elige el ID de modelo exacto
El frontend reconoce minimax-h3 y minimax-h3-global como ID de la familia base, además de los ID que contienen minimax-h3-max. Por ejemplo, el ID del modelo Turbo que se usa en el producto es minimax-h3-max-turbo. Usa el identificador canónico que aparece en el catálogo de modelos disponibles y evita inventar alias o acortar el ID.
En este momento el frontend aplica estos límites de capacidad:
| Familia / ID de modelo | Duración aceptada por el frontend | Opciones de resolución representadas en el frontend |
|---|---|---|
minimax-h3 y minimax-h3-global | De 4 a 15 segundos, entero | 2K, 768p |
minimax-h3-max-turbo y otras variantes Max | De 5 a 15 segundos, entero | 480P, 768P |
minimax-h3-max canónico | De 5 a 15 segundos, entero | Opciones Max más 1080P |
Son restricciones de validación del frontend, no una garantía de que todas las cuentas o rutas upstream tengan la misma disponibilidad. En particular, la opción extra de 1080P solo está asociada al ID canónico exacto minimax-h3-max en el cliente actual. No supongas que Turbo, un alias -global o cualquier modelo H3 admite 1080P.
Elige un solo modo de medios
El formulario de H3 admite dos flujos de trabajo mutuamente excluyentes:
- Modo de fotogramas: envía como máximo un
first_frame_imagey como máximo unlast_frame_image. El cliente selecciona una relación de aspecto adaptativa cuando hay entradas de fotograma. - Modo de referencia: envía imágenes, vídeos y/o audios de referencia sin entradas de primer ni último fotograma. El cliente usa la relación de aspecto seleccionada para esas referencias.
Ejemplo de solicitud con primer fotograma:
{
"model": "minimax-h3",
"prompt": "The subject turns toward the camera as the camera gently moves forward",
"duration": 5,
"ratio": "16:9",
"first_frame_image": ["https://example.com/starting-frame.jpg"]
}
Ejemplo de solicitud con material de referencia:
{
"model": "minimax-h3",
"prompt": "Use the supplied references to guide the scene and motion",
"duration": 5,
"ratio": "16:9",
"media_mode": "reference",
"reference_images": ["https://example.com/character-reference.jpg"],
"reference_videos": ["https://example.com/motion-reference.mp4"]
}
El formato exacto de los valores para el material que subes depende del flujo de carga de medios de la pasarela. Estos ejemplos muestran los campos de la solicitud, no afirman que cualquier URL pública sea aceptada por todas las rutas. Usa las URL o los identificadores de recursos que devuelve el flujo de carga documentado.
El frontend aplica estos límites de referencia:
- Hasta 9 imágenes de referencia.
- Hasta 3 vídeos de referencia.
- Hasta 3 audios de referencia.
- Como máximo 12 recursos de referencia en total.
- Cada vídeo de referencia debe durar entre 2 y 15 segundos, y la duración total de las referencias enviadas no puede superar los 15 segundos.
- Las referencias de audio requieren al menos una referencia visual.
- Las solicitudes Turbo no pueden incluir material de referencia.
Respeta estas restricciones antes de enviar. Una solicitud que mezcla modos de entrada, supera un recuento u omite el contexto visual necesario se rechaza localmente en el frontend, en lugar de enviarse como una solicitud válida de generación H3.
Opciones de prompt y de generación
El prompt es obligatorio y el frontend actual lo limita a 7.000 caracteres Unicode. Describe la escena, el sujeto, el movimiento y la intención visual en lenguaje natural. Trata las etiquetas de cámara entre corchetes y cualquier otra sintaxis especial como texto normal del prompt, salvo que la documentación del modelo upstream las defina de forma explícita. La evidencia disponible en el contrato del frontend no confirma que cadenas como [Pan Left] sean comandos nativos de H3.
El generador de solicitudes pasa controles opcionales admitidos, como prompt_optimizer, watermark y seed, según la ruta del modelo elegido. No des por hecho que todas las rutas upstream aceptan esos campos opcionales de la misma manera. Si los expones en tu propia interfaz, valídalos contra el catálogo específico del modelo y elimina los campos obsoletos cuando el usuario cambie de variante.
Para la relación de aspecto, el frontend acepta adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 y 9:16. Las entradas de fotograma fuerzan adaptive. En texto a vídeo, una selección adaptativa se normaliza a 16:9; el modo de referencia mantiene la relación admitida que se haya solicitado.
Crea prompts que se puedan probar
Escribir prompts no es un parámetro de la API, pero influye en cuán útil resulta una integración técnica para la persona que la usa. Pide a los usuarios que describan una escena y una acción principal antes de añadir dirección de cámara, ilusión o estilo. Un prompt compacto puede especificar el sujeto, la acción, el entorno y el comportamiento de la cámara en ese orden. Mantén esas piezas estables durante una comparación de modelos; de lo contrario, un cambio de redacción puede explicar un resultado distinto.
No prometas que una frase concreta garantiza un movimiento de cámara, la coincidencia de identidad, una tasa de fotogramas o un estilo visual. El contrato del frontend valida el prompt como texto y aplica un límite de caracteres. No define una gramática de comandos estándar para las etiquetas de cámara. Si tu aplicación ofrece controles de prompt predefinidos, etiquétalos como ayudas de prompt y no como controles garantizados del modelo, salvo que la documentación upstream confirme ese comportamiento.
Para flujos de generación repetidos, guarda la versión de la plantilla de prompt junto al registro de la tarea. Así puedes distinguir un cambio de modelo de un cambio de prompt cuando los usuarios informan resultados distintos. Evita incluir claves de API, identificadores privados o datos personales en los prompts. Revisa el contenido del prompt contra las políticas de contenido y privacidad de tu producto antes de permitir envíos por lotes sin supervisión.
Normaliza la relación de aspecto y la resolución con criterio
La relación de aspecto y la resolución responden a preguntas diferentes: la relación describe la forma de la salida, mientras que la resolución elige un tamaño de salida admitido por la ruta del modelo. Que una relación se acepte no implica que cualquier resolución pueda combinarse con ella. Mantén ambos campos en la interfaz y valídalos contra el modelo seleccionado en ese momento.
Si el usuario elige el modo de primer fotograma o de primer y último fotograma, el frontend fuerza una relación adaptativa para que los fotogramas de entrada guíen la forma del lienzo. No muestres una relación personalizada contradictoria como si fuera a respetarse. En el modo de texto a vídeo, la opción adaptativa se resuelve al comportamiento predeterminado de 16:9 en el generador actual. Si haces visible esa normalización, muestra el valor realmente enviado en un paso de revisión para que los usuarios entiendan qué recibe la pasarela.
Las etiquetas de resolución también difieren en mayúsculas entre variantes (768p frente a 768P). Normalízalas solo si el contrato de la API del modelo seleccionado lo permite de forma explícita. Evita convertir los valores del modelo de forma global, porque un valor aceptado por una ruta puede ser rechazado por otra.
Consulta de estado y errores
La generación de vídeo es asíncrona. Después de enviar la solicitud, guarda el identificador de la tarea y consulta el endpoint de estado documentado para tu cuenta de API. Usa retroceso exponencial acotado con fluctuación aleatoria en lugar de un bucle ajustado, fija una fecha límite global y trata el fallo definitivo por separado del tiempo de espera agotado. Un tiempo de espera agotado no demuestra que la tarea upstream haya fallado; comprueba el estado de la tarea antes de reintentar una generación facturable.
Como mínimo, tu cliente debería:
- Llamar a
raise_for_status()o su equivalente en las respuestas HTTP. - Leer la respuesta de acuerdo con el esquema de API publicado.
- Dejar de consultar cuando llegue a un estado final de éxito o de fallo documentado.
- Limitar el número de reintentos y el tiempo total transcurrido.
- Evitar enviar una generación duplicada solo porque una solicitud del lado del cliente agotó el tiempo de espera.
- Registrar un identificador de solicitud o de tarea, pero nunca la clave de API ni las URL de medios privados.
Las categorías genéricas de error que aparecen 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, la resolución, la relación y los recuentos de entrada. |
401 | Clave de API ausente o inválida | Revisa la clave en tu gestor de secretos y las cabeceras de la solicitud. |
429 | Límite de frecuencia o de concurrencia | Retrocede con fluctuación aleatoria y 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. |
Precios y garantías de servicio
Los precios, el tiempo de actividad, el comportamiento de los reembolsos y los acuerdos de nivel de servicio pueden variar según el modelo, la ruta y la cuenta. Esta guía no cita a propósito un precio por segundo ni promete un SLA de disponibilidad. Consulta el catálogo actual de modelos de ToAPIs y el precio de tu cuenta antes de estimar los costes de un proyecto. No uses un precio de borrador de planificación como cotización de producción.
Un flujo de trabajo más seguro para construir solicitudes
Mantén la selección y la validación del modelo en un solo lugar de tu aplicación. Cuando el usuario cambie de modelo, vuelve a construir las opciones permitidas en lugar de arrastrar todos los campos de la selección anterior a la siguiente solicitud. Esto importa al pasar de H3 base a Max o Turbo: una resolución, una lista de medios de referencia o un valor de duración pueden ser válidos para un modelo e inválidos para otro.
Una secuencia fiable del lado del cliente es esta:
- Lee el ID del modelo seleccionado en ese momento desde el catálogo de modelos.
- Carga las opciones de duración y de resolución de ese modelo.
- Pide al usuario que elija el modo de fotogramas o el modo de referencia.
- Valida los recuentos de campos y la compatibilidad antes de subir medios.
- Sube los medios elegidos mediante el endpoint de recursos documentado.
- Construye un objeto de solicitud nuevo a partir de los valores validados.
- Envía una sola vez, guarda el identificador de tarea devuelto y muestra el estado de la tarea al usuario.
Evita modificar in situ un objeto de solicitud antiguo. Un objeto nuevo reduce la probabilidad de que un campo como reference_videos se filtre a una solicitud Turbo después de cambiar de modelo. El contrato del frontend de ToAPIs también hace explícito el modo: media_mode puede ser frame o reference, y las entradas mezcladas se rechazan.
Para una integración propia, replica estas comprobaciones antes de la llamada de red:
def validate_h3_request(model, duration, resolution, frame_images, refs):
is_max_family = "minimax-h3-max" in model
is_turbo = "turbo" in model
min_duration = 5 if is_max_family else 4
if not isinstance(duration, int) or not min_duration <= duration <= 15:
raise ValueError("Duration is outside this model's supported range")
if len(frame_images) > 2:
raise ValueError("Use at most one first frame and one last frame")
if frame_images and refs:
raise ValueError("Frame inputs and reference media are separate modes")
if is_turbo and refs:
raise ValueError("This Turbo route does not accept reference media")
if len(refs.get("images", [])) > 9:
raise ValueError("Too many reference images")
if len(refs.get("videos", [])) > 3:
raise ValueError("Too many reference videos")
Esta es una protección ilustrativa del lado del cliente, no un sustituto de la validación en el servidor. El código de producción debería además validar cada tipo de medio, calcular el recuento total de referencias y la duración de los vídeos, aplicar la lista de resoluciones específica del modelo y usar los identificadores reales que devuelve el flujo de carga.
Consideraciones sobre carga y privacidad
Trata el material de referencia como datos del usuario. Sube solo archivos que el usuario esté autorizado a usar y asegúrate de que tus reglas de retención y de acceso cubren las imágenes, los audios y los vídeos de origen. No publiques medios de origen privados en URL públicas solo para simplificar una demostración. Si la API devuelve una URL temporal de recurso, evita escribirla en herramientas de analítica o en registros de larga duración.
Valida los archivos antes de subirlos: rechaza extensiones y tipos MIME no admitidos, aplica los límites documentados de tamaño y de cantidad, y muestra un error claro antes de dedicar tiempo a una solicitud de generación. Mantén el identificador de carga asociado al registro de la tarea, pero no expongas rutas de almacenamiento internas en una página pública. Si una carga falla, detente antes de crear una tarea de generación en lugar de enviar una solicitud incompleta.
Para los reintentos, distingue las lecturas idempotentes de los envíos de generación facturables. Reintentar una comprobación de estado con GET suele ser distinto de repetir un POST que ya puede haber creado una tarea. Si el cliente pierde la respuesta del envío, usa primero cualquier identificador de solicitud o mecanismo de recuperación documentado para la cuenta. Si no existe ninguno, muestra un estado incierto al operador en lugar de crear en silencio un duplicado.
Lista de verificación para el despliegue
Antes de publicar una integración de H3, prueba al menos una solicitud válida por cada ID de modelo habilitado para tu cuenta. Añade pruebas negativas con una duración fraccionaria, una resolución no admitida, demasiadas referencias, entradas de fotograma y referencia combinadas, y referencias en Turbo. Verifica que la interfaz borra los valores incompatibles después de un cambio de modelo.
En el entorno de pruebas, registra los campos de la solicitud después de la validación y compáralos con el esquema documentado de la pasarela. No captures claves de API ni datos de medios privados en los registros. Confirma la URL de consulta de estado, los estados de la tarea y el campo de resultado con un fixture que no sea de producción o con una cuenta de prueba aprobada. Este artículo no llama a un endpoint en vivo ni valida el comportamiento del servicio remoto.
Por último, comprueba el precio de la cuenta del usuario y el catálogo de modelos justo antes del lanzamiento. La disponibilidad y el precio de los modelos son información propia de cada cuenta; los valores copiados en un artículo antiguo pueden quedar obsoletos aunque los campos de la solicitud no cambien.
Modelos relacionados y siguientes pasos
- Explora los modelos de vídeo
- Abre el Playground con MiniMax H3
- Abre el Playground con MiniMax H3 Max Turbo
Antes de desplegar, verifica el ID de modelo exacto, la disponibilidad actual de la ruta, el formato de carga, el esquema de respuesta y el precio de la cuenta en la documentación de la API que tengas disponible.







