API de vídeo de MiniMax H3: generación y regeneración
Conecta MiniMax H3 con tu BetterToken API Key y elige los campos, recursos y métodos de generación según el Model ID y la operación.
Puedes generar vídeos a partir de texto, fotogramas iniciales y finales o recursos de referencia. También puedes regenerar tus propios vídeos H3 de 768p que cumplan los requisitos a 2k. La regeneración solo acepta el ID de la tarea de origen, sin nuevas URL de recursos.
Prepara tu BetterToken API Key. La Base URL es https://bettertoken.ai/v1 y la autenticación usa Authorization: Bearer YOUR_API_KEY. Copia el Model ID exactamente, respetando mayúsculas y minúsculas.
Cada request.json de esta página sigue el mismo proceso: solicita un presupuesto, confirma la creación, consulta el estado y descarga. El presupuesto no inicia la generación; la creación envía una tarea de pago. Consulta los precios actuales en el model plaza.
Modelos y operaciones
La tabla enumera las opciones de cada operación. Consulta los valores predeterminados, las cantidades de recursos y las restricciones de combinación en cada sección. Los tamaños usan 1 MB = 1048576 bytes.
| Model ID | Operación | Duración (segundos) | Nivel de salida | Relación de aspecto | Audio | Roles de recursos |
|---|---|---|---|---|---|---|
MiniMax-H3 | image_to_video | 4–15, incremento 1 | 768p, 2k | adaptive | provider_default | first_frame, last_frame, reference_image, reference_video, reference_audio |
MiniMax-H3 | reference_to_video | 4–15, incremento 1 | 768p, 2k | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | provider_default | reference_image, reference_video, reference_audio |
MiniMax-H3 | text_to_video | 4–15, incremento 1 | 768p, 2k | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | provider_default | Ninguno |
MiniMax-H3 | video_edit | Heredada de la tarea de origen | 2k | adaptive (heredada) | provider_default | ID de tarea de origen |
provider_default conserva la configuración de audio del modelo, sin un selector on / off. La relación de aspecto, la duración y las entradas de la regeneración dependen de la tarea de origen.
Recursos de ejemplo
Los ejemplos de generación desde imágenes y referencias usan una taza de cerámica azul sobre una mesa blanca. Puedes probar la imagen de ejemplo o sustituirla primero por recursos HTTPS públicos que tengas derecho a usar y que cumplan los límites de esta página.

De texto a vídeo
MiniMax-H3
Usa esta operación para generar un vídeo cuando solo tienes una descripción de texto.
Establece model en el Model ID de esta sección y operation en text_to_video. Usa solo los campos de generación de la tabla siguiente; coloca los recursos en el array media.
| Campo | Tipo | Obligatorio | Opciones o rango | Valor predeterminado |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 4–15, incremento 1 s; solo con duración fija | 4 |
output.aspect_ratio | string | Sí | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Ninguno |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 768p, 2k | 768p |
prompt | string | Sí | Cadena | Ninguno |
watermark | boolean | No | false, true | false |
Requisitos de los recursos
Esta operación no acepta recursos.
Restricciones de combinación
duration.mode="fixed"requiereduration.seconds. Cuando indiquesfixedexplícitamente, incluye también los segundos.
Ejemplo de solicitud
Guarda el JSON siguiente como request.json y sigue el proceso general: solicita un presupuesto y confirma antes de crear la tarea.
{ "model": "MiniMax-H3", "operation": "text_to_video", "prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "768p", "aspect_ratio": "16:9" }}Errores 422 frecuentes
| Código de error 422 | Solución |
|---|---|
enum / range / step | Ajusta los valores y el incremento según la tabla de campos de esta sección. |
unsupported_field | Elimina los campos que no figuran en la tabla de esta operación. |
requires | Completa los segundos, la relación de aspecto, el audio o los recursos según las restricciones de esta sección. |
De imagen a vídeo
MiniMax-H3
Usa esta operación para fijar el primer fotograma o el primero y el último a partir de imágenes.
Establece model en el Model ID de esta sección y operation en image_to_video. Usa solo los campos de generación de la tabla siguiente; coloca los recursos en el array media.
| Campo | Tipo | Obligatorio | Opciones o rango | Valor predeterminado |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 4–15, incremento 1 s; solo con duración fija | 4 |
output.aspect_ratio | string | No | adaptive | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 768p, 2k | 768p |
prompt | string | Sí | Cadena | Ninguno |
watermark | boolean | No | false, true | false |
Requisitos de los recursos
| Rol del recurso | Tipo y cantidad | Formatos | Límites por archivo |
|---|---|---|---|
first_frame | image, opcional, máximo 1 | jpg, jpeg, png, webp, heic, heif | Tamaño máximo: 30 MB; ancho: 256–5760 px; alto: 256–5760 px |
last_frame | image, opcional, máximo 1 | jpg, jpeg, png, webp, heic, heif | Tamaño máximo: 30 MB; ancho: 256–5760 px; alto: 256–5760 px |
reference_image | image, opcional, máximo 9 | jpg, jpeg, png, webp, heic, heif | Tamaño máximo: 30 MB; ancho: 256–5760 px; alto: 256–5760 px |
reference_video | video, opcional, máximo 3 | mp4, mov | Tamaño máximo: 50 MB; ancho: 256–5760 px; alto: 256–5760 px; duración: 2–15 s; velocidad de fotogramas mínima: 23.976 fps; máxima: 60 fps; duración total máxima de este rol: 15 s |
reference_audio | audio, opcional, máximo 3 | wav, mp3 | Tamaño máximo: 15 MB; duración: 2–15 s; duración total máxima de este rol: 15 s |
Los requisitos de recursos también deben cumplir las restricciones de combinación siguientes.
Restricciones de combinación
duration.mode="fixed"requiereduration.seconds. Cuando indiquesfixedexplícitamente, incluye también los segundos.- Proporciona al menos uno de estos roles:
first_frame,last_frame. - No combines fotogramas iniciales o finales con imágenes, vídeos o audio de referencia. Usa la operación de imagen a vídeo para los fotogramas iniciales y finales, y la de generación por referencias para los recursos de referencia.
Ejemplo de solicitud
Guarda el JSON siguiente como request.json y sigue el proceso general: solicita un presupuesto y confirma antes de crear la tarea.
{ "model": "MiniMax-H3", "operation": "image_to_video", "prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "768p", "aspect_ratio": "adaptive" }, "media": [ { "id": "first", "type": "image", "role": "first_frame", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Errores 422 frecuentes
| Código de error 422 | Solución |
|---|---|
enum / range / step | Ajusta los valores y el incremento según la tabla de campos de esta sección. |
unsupported_field | Elimina los campos que no figuran en la tabla de esta operación. |
requires | Completa los segundos, la relación de aspecto, el audio o los recursos según las restricciones de esta sección. |
mutually_exclusive_roles | Usa los fotogramas iniciales y finales por separado de los recursos de referencia. |
count / media_role | Ajusta los roles y las cantidades según la tabla de recursos de esta sección. |
video_input_unsupported | Comprueba la URL HTTPS pública, el Content-Type y el formato del archivo, y solicita otro presupuesto. |
Generación con referencias
MiniMax-H3
Usa esta operación para conservar las características del sujeto o del movimiento mediante recursos de referencia.
Establece model en el Model ID de esta sección y operation en reference_to_video. Usa solo los campos de generación de la tabla siguiente; coloca los recursos en el array media.
| Campo | Tipo | Obligatorio | Opciones o rango | Valor predeterminado |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 4–15, incremento 1 s; solo con duración fija | 4 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 768p, 2k | 768p |
prompt | string | Sí | Cadena | Ninguno |
watermark | boolean | No | false, true | false |
Requisitos de los recursos
| Rol del recurso | Tipo y cantidad | Formatos | Límites por archivo |
|---|---|---|---|
reference_image | image, opcional, máximo 9 | jpg, jpeg, png, webp, heic, heif | Tamaño máximo: 30 MB; ancho: 256–5760 px; alto: 256–5760 px |
reference_video | video, opcional, máximo 3 | mp4, mov | Tamaño máximo: 50 MB; ancho: 256–5760 px; alto: 256–5760 px; duración: 2–15 s; velocidad de fotogramas mínima: 23.976 fps; máxima: 60 fps; duración total máxima de este rol: 15 s |
reference_audio | audio, opcional, máximo 3 | wav, mp3 | Tamaño máximo: 15 MB; duración: 2–15 s; duración total máxima de este rol: 15 s |
Los requisitos de recursos también deben cumplir las restricciones de combinación siguientes.
Restricciones de combinación
duration.mode="fixed"requiereduration.seconds. Cuando indiquesfixedexplícitamente, incluye también los segundos.- Proporciona al menos uno de estos roles:
reference_image,reference_video,reference_audio. - No combines fotogramas iniciales o finales con imágenes, vídeos o audio de referencia. Usa la operación de imagen a vídeo para los fotogramas iniciales y finales, y la de generación por referencias para los recursos de referencia.
Ejemplo de solicitud
Guarda el JSON siguiente como request.json y sigue el proceso general: solicita un presupuesto y confirma antes de crear la tarea.
{ "model": "MiniMax-H3", "operation": "reference_to_video", "prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "768p", "aspect_ratio": "adaptive" }, "media": [ { "id": "reference", "type": "image", "role": "reference_image", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Errores 422 frecuentes
| Código de error 422 | Solución |
|---|---|
enum / range / step | Ajusta los valores y el incremento según la tabla de campos de esta sección. |
unsupported_field | Elimina los campos que no figuran en la tabla de esta operación. |
requires | Completa los segundos, la relación de aspecto, el audio o los recursos según las restricciones de esta sección. |
mutually_exclusive_roles | Usa los fotogramas iniciales y finales por separado de los recursos de referencia. |
count / media_role | Ajusta los roles y las cantidades según la tabla de recursos de esta sección. |
video_input_unsupported | Comprueba la URL HTTPS pública, el Content-Type y el formato del archivo, y solicita otro presupuesto. |
Regenerar un vídeo
MiniMax-H3
Usa esta operación si ya tienes tu propio vídeo H3 de 768p y quieres regenerarlo a 2k conservando el contenido original. No acepta archivos de vídeo arbitrarios.
La tarea de origen debe cumplir todos estos requisitos:
- Pertenece a tu cuenta y su Model ID es
MiniMax-H3. - La generación se completó correctamente y el vídeo sigue disponible para descargar.
- La salida está configurada en
768p. - No han pasado más de 7 días desde la creación de la tarea de origen.
El servidor también comprueba el formato del vídeo de origen y devuelve 422 video_regeneration_source_invalid si no cumple los requisitos. Solicita el presupuesto con el ID de la tarea de origen; no modifiques el archivo de vídeo para sustituir dicha tarea.
| Campo de solicitud | Tipo | Obligatorio | Valor |
|---|---|---|---|
model | string | Sí | MiniMax-H3 |
operation | string | Sí | video_edit |
provider_options.hailuo.source_task_id | string | Sí | ID de tu tarea de origen que cumpla los requisitos |
watermark | boolean | No | false / true, predeterminado: false |
No envíes prompt, duration, output, audio ni media. La regeneración hereda el contenido y las entradas de la tarea de origen y produce 2k, adaptive, MP4.
Sustituye primero REPLACE_WITH_YOUR_H3_TASK_ID por el ID de tu tarea de origen y, después, solicita el presupuesto y crea la tarea. Esto crea una nueva tarea de pago; usa un nuevo archivo de estado.
{ "model": "MiniMax-H3", "operation": "video_edit", "provider_options": { "hailuo": { "source_task_id": "REPLACE_WITH_YOUR_H3_TASK_ID" } }}Si la tarea de origen no cumple los requisitos o no existe, el presupuesto devuelve 422 video_regeneration_source_invalid, con field_path igual a provider_options.hailuo.source_task_id. El siguiente ejemplo muestra este error y no sirve para generar vídeos:
{ "model": "MiniMax-H3", "operation": "video_edit", "provider_options": { "hailuo": { "source_task_id": "video_DOES_NOT_EXIST" } }}Documentación oficial
Al llamar a BetterToken, usa los campos de esta página y la operación correspondiente del catálogo de modelos en tiempo real.

