01content: text
Texto a vídeo (t2va)
Envía el elemento de texto obligatorio para generar el plano completo. En la generación solo con texto, ratio es obligatorio y no puede tener el valor adaptive.
MiniMax H3 APIMiniMax-H3 · API de generación de vídeo · minimaxh3.video
API de MiniMax H3 para generación de vídeo en producción
Crea con la API de MiniMax H3 flujos de texto a vídeo, control del primer y último fotograma y generación con referencias omni. El proceso asíncrono devuelve primero un task_id y, después, una URL para descargar el vídeo.
POST /api/v1/video_generation200 · task_id
curl --request POST \
--url https://minimaxh3.video/api/v1/video_generation \
--header "Authorization: Bearer $MINIMAX_H3_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "Un ciclista cruza una calle urbana iluminada por la lluvia de noche, reflejos de neón en el asfalto mojado, cámara siguiendo junto a la bicicleta."
}
],
"duration": 5,
"resolution": "2K",
"ratio": "16:9"
}'- Endpoint
- POST /api/v1/video_generation
- ID del modelo
- MiniMax-H3
- Flujo de trabajo
- Tarea asíncrona
- Salida
- 2K · 4–15s
- Autenticación
- Clave de API Bearer
- Límite de prompt
- 7.000 caracteres
Interfaz pública
Un endpoint de MiniMax H3, tres modos creativos.
MiniMax-H3 usa un array content multimodal. Los roles que asignes determinan si la solicitud genera vídeo a partir de texto, de un primer y último fotograma o de materiales de referencia.
02content: text + images
Primer / último fotograma (i2va)
Añade elementos image_url con rol first_frame y opcionalmente last_frame para controlar la composición de apertura y cierre.
03content: text + refs
Generación con referencias (r2va)
Guía el personaje, el movimiento, la cámara, el estilo o la voz con imágenes, vídeos y audio de referencia, sin combinarlos con los roles de primer y último fotograma.
Qué ofrece la API
Controla la escena, las referencias y el formato de salida.
MiniMax H3 se documenta como un modelo de vídeo multimodal abierto y de uso general. La API V2 está pensada para backends de producto, no solo para pruebas puntuales.
Entrada multimodal
Texto, imagen, vídeo y audio en una sola solicitud
Cada elemento de content tiene un tipo y puede incluir un rol. Las referencias de audio deben enviarse junto con una imagen o un vídeo.
Rango de salida
2K nativo de 4 a 15 segundos
duration admite valores enteros de 4 a 15 segundos. Se aceptan las relaciones de aspecto habituales; el valor adaptive está disponible cuando el material de entrada define el encuadre.
Presupuesto de prompt
Hasta 7.000 caracteres para las indicaciones
Aprovecha el espacio para definir la estructura del plano, el movimiento, la trayectoria de cámara, la intención del diálogo y la relación entre referencias; no para acumular palabras clave.
Conflictos entre roles
El primer/último fotograma y las referencias son incompatibles
Si usas cualquier rol reference_*, no puedes incluir first_frame ni last_frame. Validar esta regla evita errores 400 innecesarios.
Resultado asíncrono
task_id → status → content.url
Cuando una tarea finaliza correctamente, la consulta de estado devuelve una URL de descarga temporal. Guarda los identificadores y copia el archivo a un almacenamiento permanente si necesitas conservarlo.
Gestión de tareas
Listar, cancelar y respetar los plazos de expiración
V2 documenta cómo listar y cancelar/eliminar tareas, además de un periodo breve para consultar las más recientes. Gestiona cada generación como una tarea, no como una única llamada HTTP de larga duración.
Casos de uso
Qué equipos construyen con la API de MiniMax H3
Usa el mismo flujo asíncrono para activos creativos individuales, herramientas para creadores o pipelines por lotes.
Productos para creadores
Generación de planos dentro de la app
Permite a los usuarios enviar un prompt o primer fotograma, muestra el estado de la cola y entrega un clip en 2K cuando la tarea termine.
Sistemas de marca
Campañas guiadas por referencias
Mantén las referencias de personaje, producto, movimiento o voz entre varios planos cortos sin tener que reconstruir la identidad cada vez.
Herramientas editoriales
Transiciones de primer a último fotograma
Dirige un fotograma de apertura y cierre controlados cuando la continuidad del storyboard importa más que la pura improvisación.
Pipelines sociales
Formatos verticales y cinematográficos
Genera aperturas en 9:16 o planos maestros en 16:9 desde una misma integración y cambia únicamente ratio y duration.
Backends de agentes
Trabajos multimodales en cola
Los agentes pueden crear arrays content, consultar el estado y pasar content.url a los pasos de almacenamiento, moderación o edición.
Estudios de prototipado
Pruebas rápidas de puesta en escena
Explora combinaciones de cámara, interpretación y referencias antes de comprometerte con un pipeline de producción completo.
Flujo de trabajo asíncrono
De la clave de API a un vídeo de MiniMax H3 descargable
La generación no exige mantener abierta una solicitud HTTP. Guarda los identificadores y sigue los pasos documentados para V2.
Crear
Enviar una tarea de generación
Envía mediante POST model MiniMax-H3, un array content, duration, resolution y, cuando sea obligatorio, ratio. La respuesta correcta devuelve task_id.
POST /api/v1/video_generationObservar
Consultar el estado de la tarea
Consulta la tarea hasta que alcance un estado final. queued y running son estados intermedios normales.
GET /api/v1/video_generation/{task_id}Recuperar
Descargar content.url
Cuando el estado es succeeded, la respuesta incluye content.url. La URL es temporal; copia el archivo a un almacenamiento propio si necesitas conservarlo.
content.url · mp4Diseño de la solicitud
Los campos que definen una solicitud fiable para MiniMax-H3
Define la solicitud de forma explícita y valida las combinaciones propias de cada modo antes de enviar una tarea.
Obligatorio
model
Usa el identificador documentado exacto MiniMax-H3. No emplees nombres comerciales alternativos como ID del modelo.
Contenido multimodal obligatorio
content[]
Al menos un elemento type=text. Añade elementos image_url, video_url o audio_url con roles para modos controlados.
4–15 segundos enteros
duration
Elige un único valor entero en segundos. Una duración mayor no siempre mejora el resultado si el plano solo necesita una acción clara.
Salida documentada
resolution
MiniMax H3 está documentado con salida en 2K. Antes de publicar la integración, comprueba los valores enum vigentes en la referencia actual de la API.
Control de geometría
ratio
Es obligatorio para texto a vídeo puro y, en ese modo, no puede tener el valor adaptive. Los flujos guiados por imágenes pueden respetar las proporciones del material original.
Roles de medios opcionales
first_frame · last_frame · reference_*
Los roles determinan el tipo de control creativo. Al subir los archivos, valida las incompatibilidades entre roles y los límites de tamaño de cada recurso.
Estado de la tarea
Trata el estado como una máquina de estados
Los clientes que consultan el estado deben admitir estados intermedios y detenerse únicamente al llegar a uno de los estados finales documentados.
| Estado | Significado | Comportamiento recomendado de la aplicación |
|---|---|---|
| queued | Esperando capacidad | Guarda task_id y aumenta gradualmente el intervalo entre consultas |
| running | Generación en progreso | Mantén el trabajo visible; evita envíos duplicados |
| succeeded | Vídeo listo | Lee content.url y almacena el activo |
| failed | La generación no se completó | Muestra el código y el mensaje de error, y permite reintentar de forma controlada |
| cancelled | La tarea fue cancelada | Cierra la vista de la tarea y conserva un registro de auditoría |
| expired | La tarea ya no está disponible | No consultes indefinidamente; recrea si es necesario |
Solo se pueden consultar las tareas recientes. Comprueba el periodo de retención oficial antes de diseñar flujos de recuperación a largo plazo.
Límites de entrada
Valida los medios antes de que lleguen a MiniMax H3
Los límites documentados pueden validarse durante la subida para evitar fallos innecesarios en la generación.
Imágenes
JPG, JPEG, PNG, WEBP, HEIC, HEIF · ≤ 30 MB
Ancho/alto en [256, 5760]; proporción entre 2:5 y 5:2. Primer fotograma ≤ 1, último fotograma ≤ 1, imágenes de referencia ≤ 9.
Vídeos
MP4/MOV con H.264/H.265 · ≤ 50 MB cada uno
Hasta 3 clips de referencia, cada uno 2–15s, total ≤ 15s. El audio en el vídeo puede ser AAC o MP3.
Audio
WAV o MP3 · ≤ 15 MB cada uno
Hasta 3 clips de 2–15s cada uno y ≤ 15s en total. El audio no puede enviarse solo; acompáñalo de referencias de imagen o vídeo.
Referencias mixtas
Máximo de 12 archivos multimedia por solicitud
El cuerpo de la solicitud debe ser ≤ 64 MB. Para archivos grandes, usa preferentemente URL públicas en lugar de Base64.
Modos incompatibles
No mezcles primer/último fotograma con roles de referencia
Elige el control de composición con first_frame/last_frame o la generación con referencias omni; no combines ambos en un mismo array content.
Prompt
Limita las indicaciones a 7.000 caracteres
Relaciona las referencias en el texto cuando la identidad, la voz o el movimiento deban seguir un recurso concreto.
Los precios están en la página de precios
El coste en créditos y los límites de los planes pueden cambiar. Enlaza a la página de precios actual de MiniMax H3 en lugar de fijar una cifra en la integración.
Arquitecturas adecuadas
Cuándo encaja la generación asíncrona con MiniMax H3
Elige la API V2 cuando tu producto pueda crear una tarea y esperar a que el archivo esté listo.
Ideal para
Servicios backend y herramientas para creadores
Las colas de generación, el almacenamiento permanente y las interfaces de estado encajan de forma natural en flujos con task_id.
Ideal para
Control creativo multimodal
Planos que combinan las indicaciones del prompt con un primer fotograma, un último fotograma o materiales de referencia.
Límite
No es un socket de vídeo en tiempo real
Diseña el sistema en torno a consultas de estado o workers internos, en lugar de mantener abierta una conexión durante la generación.
Límite
Diseña para tareas, no para sockets abiertos
Gestiona las generaciones largas en la cola del backend y muestra su estado en la interfaz del producto.
Preguntas sobre la API
Preguntas sobre la API de MiniMax H3
Respuestas prácticas antes de integrar tu primera solicitud para producción.
¿MiniMax-H3 es el ID del modelo para esta API?
Sí. Al crear una tarea, envía model MiniMax-H3 al endpoint de generación de vídeo de MiniMax H3.
¿A qué endpoint debo llamar?
Crea tareas con POST https://minimaxh3.video/api/v1/video_generation y consulta después su estado con GET https://minimaxh3.video/api/v1/video_generation/{task_id}. Cuando finalicen correctamente, descarga el archivo MP4 desde content.url.
¿En qué se diferencia MiniMax H3 de la integración con Hailuo 2.3?
H3 es el modelo multimodal de uso general actual, con una interfaz content[], salida documentada en 2K, duración de 4–15s y referencias omni. Hailuo 2.3 pertenece a una familia anterior y utiliza formatos de solicitud diferentes.
¿Puedo combinar control de primer fotograma con audio de referencia?
No en la misma solicitud. Los roles first_frame/last_frame y reference_* son incompatibles. Elige el modo que ofrezca el tipo de control que necesitas.
¿Cómo me autentico?
Envía una clave de API Bearer en el header Authorization. Cuando tengas acceso, podrás crear y gestionar las claves desde la configuración de tu cuenta de MiniMax H3.
¿Dónde puedo consultar los precios actuales?
Consulta los planes y créditos en la página de precios. El uso de la API se rige por las mismas condiciones del saldo de créditos publicadas allí.
Prueba el plano. Envía la solicitud a la API.
Define la dirección creativa en el generador y, después, llama con tu clave a la API de MiniMax H3 en minimaxh3.video.