Tutorial de la API de MiniMax H3 en chino: texto a video, fotogramas inicial y final, y referencias multimodales

MiniMax H3 es el modelo de generación de video multimodal general de MiniMax. Puede comprender materiales de texto, imagen, video y audio, y generar videos cortos con sonido nativo. Al integrarlo a través de HiAPI, el ID del modelo es fijo: minimax-h3; los modelos de imagen, video y audio usan la misma interfaz de tareas asíncronas.

Si solo quieres crear un video corto a partir de una indicación, puedes enviar únicamente prompt. Si la apariencia del producto, las imágenes de marca o el inicio y el final del plano son más importantes, vale más la pena usar los modos de fotogramas inicial y final y de referencias multimodales de H3. El modelo admite actualmente salidas de 4 a 15 segundos, 2K nativo y relaciones de aspecto como 21:9, 16:9, 4:3, 1:1, 3:4 y 9:16. Las opciones disponibles concretas se rigen por la página del modelo MiniMax H3 y la documentación de parámetros de la API.

Qué problemas resuelve MiniMax H3

Es adecuado para tareas de video corto en las que hay que controlar simultáneamente la relación entre imagen, movimiento y sonido. Por ejemplo, crear un video de presentación con movimiento de cámara para una página de producto, mantener el mismo tono visual para materiales de marca, o llevar el ritmo de un video de referencia, el sujeto de una imagen de referencia y un audio de referencia juntos a un nuevo plano.

Para equipos de comercio electrónico, publicidad y productos, el valor de H3 no es solo "hacer que la imagen se mueva". Cuando hay materiales de referencia, la clave es dejar claro lo que no puede cambiar, por ejemplo la forma del producto, la posición del Logo, la identidad del sujeto, el ángulo de cámara y la iluminación; y describir por separado lo que debe cambiar, por ejemplo la acción, el fondo, el avance de cámara o el diálogo. Así, al validar el resultado, sabrás qué parte se desvió.

Un modelo, tres flujos de trabajo habituales

Flujo de trabajo	Escenarios adecuados	Entradas clave
Texto a video	Generar nuevas imágenes a partir de un guion, storyboard o una idea	prompt
Control de fotogramas inicial y final	Controlar el estado del producto o el cambio de escena al inicio y al final del plano	first_frame_image, opcionalmente last_frame_image
Video de referencia multimodal	Referenciar simultáneamente productos, personas, ritmo de plano o materiales de audio	image_urls, video_urls, audio_urls

El control de fotogramas inicial y final y las referencias multimodales son dos modos distintos y no pueden combinarse en una misma solicitud. Al usar el fotograma final, debes proporcionar también el fotograma inicial. En las referencias multimodales se pueden enviar como máximo 5 imágenes, 3 videos y 3 audios; el audio no puede usarse como única entrada, se debe proporcionar al menos una imagen o un video de referencia junto con él. Cada video y audio de referencia dura de 2 a 15 segundos, y en total no superan los 15 segundos.

Primero, ejecuta una tarea mínima con texto a video

A continuación se muestra un ejemplo de plano de producto de 5 segundos en 16:9. La creación correcta de la tarea solo significa que el servidor recibió la solicitud; el data.taskId de la respuesta sirve para consultar el estado posterior.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "input": {
      "prompt": "一只哑光深蓝色咖啡杯放在浅灰石桌上。镜头从中景缓慢推进，晨光从左侧照入，杯身保持不动，背景虚化，无文字。",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9",
      "watermark": false
    }
  }'

Para la depuración local puedes usar GET /v1/tasks/{taskId} para consultar el resultado. En producción es más adecuado establecer callback.url en el nivel superior de la solicitud y hacer que tu propio servicio gestione la idempotencia según taskId. Decide el status cuando la tarea llegue a un estado terminal: en success, descarga output[].url; en fail, corrige la entrada según el mensaje de error, no reenvíes a ciegas la misma solicitud inválida.

Cómo usar los materiales de referencia de forma significativa

Los fotogramas inicial y final son adecuados para tareas en las que "el plano va de A a B". Por ejemplo, un video de lanzamiento de un producto que empieza con una lámpara de mesa apagada y termina con la mesa iluminada por una luz cálida. En este caso, el fotograma inicial fija el punto de partida y el fotograma final fija el punto de llegada; la indicación solo necesita explicar la acción, el movimiento de cámara y los cambios de luz que ocurren en el medio.

Las referencias multimodales son más adecuadas para un control continuo de marca o de personaje. La imagen principal del producto puede ir en image_urls, la referencia del ritmo de plano en video_urls, y la referencia de música o ambiente en audio_urls. La indicación debe especificar el papel de cada tipo de material, por ejemplo: "Mantén la apariencia del bolso y la posición del cierre metálico de la imagen de referencia, sigue el ritmo de avance lateral del video de referencia y genera un video de presentación de producto tranquilo".

No amontones todos los materiales. Cada referencia adicional añade restricciones que el modelo debe comprender. Primero valida la conservación de la apariencia con una imagen del sujeto y luego añade referencias de plano o de audio; así es más fácil localizar problemas.

Qué información debe incluir la indicación

Una indicación de video reutilizable suele incluir cuatro partes: sujeto, acción, cámara y sonido o entorno. El sujeto debe indicar claramente la información visual que no puede cambiar; la acción debe indicar el evento que ocurre; la cámara debe describir la posición y el movimiento; y el sonido debe indicar si hay diálogo, sonido ambiental o ambiente musical.

Por ejemplo, para un anuncio de producto puedes escribir: "Mantén sin cambios el estuche blanco de auriculares, la carcasa naranja y la marca NOMA de la imagen de referencia. La cámara avanza lentamente desde un plano medio de la mesa, el estuche se abre y los dos auriculares permanecen en su sitio. Luz natural junto a la ventana, sonido ambiental tenue, sin voz en off, sin texto adicional". Esto es más fácil de validar que escribir solo "haz un anuncio de auriculares bonito".

Antes de incorporar H3 al flujo de trabajo de producción

Se recomienda hacer primero una validación a pequeña escala con tres casos: un video puramente de texto a video, uno con control de fotogramas inicial y final, y un video de referencia multimodal. Registra por separado los materiales de entrada, la duración de salida, la transición de estados, los mensajes de error, la URL del producto y la factura final. Cuando confirmes que cada modo funciona de forma estable en tu producto, amplía a la generación por lotes.

El precio se calcula según los segundos de salida y el nivel actual; la página no fija un precio unitario. Antes de enviar, consulta el precio actual en la página del modelo MiniMax H3 en tiempo real; una vez en línea, rígete por los registros de tareas y la facturación de la cuenta. Para más información sobre tareas asíncronas, callbacks y resolución de errores, puedes seguir consultando el tutorial de integración de MiniMax H3.

Preguntas frecuentes

¿Qué entradas admite MiniMax H3?

Puede generar video solo con texto, o controlarse con un fotograma inicial, fotogramas inicial y final, o imágenes, videos y audios de referencia. Los campos de fotogramas inicial y final y los de referencias multimodales no pueden mezclarse.

¿MiniMax H3 puede generar sonido?

MiniMax H3 admite la generación de video con sonido nativo y también permite usar materiales de audio en el modo de referencias multimodales. La referencia de audio debe combinarse con una imagen o un video de referencia.

¿Cuánto puede durar como máximo un video?

La duración de salida actual es de 4 a 15 segundos. Los videos largos normalmente deben dividirse en varios planos generados por separado y luego editarse y ensamblarse en tu propio flujo de trabajo.

¿Debo usar sondeo o callback?

Para depuración local y tareas de baja frecuencia se puede usar sondeo. En producción se recomienda usar callback.url para recibir notificaciones de estado terminal y conservar la consulta de detalles de la tarea como mecanismo de compensación si falla el callback.

Ver MiniMax H3, leer la documentación de parámetros de la API, o obtener una API Key.