MiniMax Hailuo: API de generación de video

MiniMax Hailuo H3 convierte texto, primer/último fotograma o referencias multimodales en video con audio estéreo incluido: envíe una tarea y luego consulte el ID de tarea de HopBase.

Modelos disponibles

Use los ID exactos MiniMax-H3 / MiniMax-H3-Max / MiniMax-H3-SelfHosted: no hay alias registrados y los nombres de modelo desconocidos se rechazan. H3-Max es la variante rápida: un clip de 5 segundos suele generarse en pocos segundos. Los precios por nivel y las especificaciones completas están en las fichas MiniMax-H3 y MiniMax-H3-Max.

MiniMax-H3-SelfHosted es una versión autoalojada de Hailuo H3 con la misma calidad que H3 a un precio menor. Usa el mismo contrato de solicitud que MiniMax-H3, con estas diferencias: añade 480P, 1080P y 4K (la lista completa está en la tabla anterior); los videos y audios de referencia deben ser URL públicas http(s) y se rechazan los data: incrustados (las imágenes sí pueden incrustarse); un clip suele tardar de 3 a 6 minutos. Lo ofrece el grupo MiniMax H3 autoalojado y aparece en la categoría Autoalojado de la consola. Las especificaciones y los precios por nivel están en la ficha MiniMax-H3-SelfHosted.

MiniMax-H3 y MiniMax-H3-Max se sirven desde dos grupos separados — MiniMax H3 oficial y MiniMax H3 Max oficial — y speech-2.8-hd / speech-2.8-turbo desde un tercero, MiniMax Speech oficial; vea la API de texto a voz. MiniMax-H3-SelfHosted lo ofrece el grupo MiniMax H3 autoalojado, y MiniMax-H3-Max también está disponible en MiniMax H3 Max Cloud (el mismo modelo oficial, con otro precio).

Una clave solo llega a los modelos de los grupos que incluye; si necesita H3 y H3-Max, añada ambos grupos a una misma clave. Confirme qué modelos alcanza su clave con GET /v1/models antes de enviar trabajo de pago.

Parámetros de la solicitud

HopBase expone MiniMax Hailuo H3 a través del contrato oficial v2 de MiniMax. El cuerpo refleja la solicitud oficial POST /v2/video_generation de MiniMax y se decodifica de forma estricta: los campos desconocidos y un segundo valor JSON se rechazan antes de que la solicitud salga.

Solo se aceptan los campos de nivel superior de la tabla; cualquier otro, incluidos prompt / size / n / seconds / image de OpenAI, devuelve 400.

El modo primer/último fotograma acepta cualquier ratio válido y siempre produce adaptive (sigue la imagen); recorte antes el fotograma para una relación concreta. Todas las solicitudes usan Authorization: Bearer sk-tu-clave y Content-Type: application/json.

Elementos de content

La cantidad, los roles y las combinaciones se validan al enviar; el tamaño, las dimensiones, el códec y la duración de los archivos los valida MiniMax durante la ejecución. Los elementos de primer/último fotograma y los reference_* son mutuamente excluyentes, y una solicitud admite como máximo 12 archivos de medios en total.

Los valores url de medios aceptan una URL pública absoluta http(s) o una URI data: (base64). mm_file:// se rechaza: el archivo pertenece a su propia cuenta de MiniMax, a la que la pasarela no tiene acceso. Para MiniMax-H3-SelfHosted, video_url y audio_url deben ser URL públicas http(s); data: solo se acepta para imágenes.

Especificaciones de los medios

Salida y tamaño de la solicitud

• La salida es de 24 FPS y cada clip incluye audio estéreo nativo.
• Los diálogos y las voces en off se generan dentro del modelo, con TTS que cubre 11 idiomas (chino, inglés, japonés, coreano, francés, alemán, español y más).
• 2K significa un lado corto de 1440 píxeles para relaciones entre 16:9 y 9:16; las relaciones más anchas mantienen ≈3.7M píxeles totales, por ejemplo 21:9 → 2976×1248.
• 768P sigue la misma regla a 768 px / ≈1M píxeles.
• El cuerpo JSON completo está limitado a 64 MiB; por encima devuelve 413.
• base64 aumenta los datos en torno a 4/3 y las incrustaciones data: no amplían los límites de cantidad ni de duración, así que use URL para medios grandes.

Respuesta

Los campos de una tarea de MiniMax están en el nivel superior de la respuesta, sin envoltorio task.

Respuesta al enviar

El envío responde con 202 y un ID de tarea de HopBase:

{
  "id": "mmt60x430684635582774",
  "object": "video.generation.task",
  "model": "MiniMax-H3",
  "status": "queued",
  "billing_bucket": "2k"
}

Campos de la consulta de tarea

Solo completed y failed son terminales, así que trate cualquier otro valor como en curso. Un clip típico se completa en 1.5-3 minutos.

En curso

{
  "id": "mmt60x430684635582774",
  "status": "processing"
}

Completada

{
  "id": "mmt60x430684635582774",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "2k", "billed_seconds": 4, "input_seconds": 0, "extra_input_images": 0, "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

Fallida

Una tarea fallida no tiene código de error, así que lea error.message (fallos de tareas asíncronas):

{ "id": "mmt60x...", "status": "failed", "error": { "message": "..." } }

Ejemplo mínimo

# 1. Enviar; texto a video requiere ratio
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{
      "type": "text",
      "text": "Toma aérea de montañas nevadas sobre nubes al amanecer"
    }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

# 2. Consultar con el id devuelto
curl https://api.hop-base.com/v1/video/tasks/mmt-id-de-tu-tarea \
  -H "Authorization: Bearer sk-tu-clave"

Para imagen a video, ponga el primer fotograma en content:

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "La cámara avanza lentamente mientras la luz se desliza sobre la escena" },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." }, "role": "first_frame" }
  ],
  "resolution": "768P",
  "duration": 4
}

Notas

• Un image_url sin role cuenta como primer fotograma, así que en modo referencia ponga "role": "reference_image" en cada imagen.
• Una tarea que sigue sin terminar 2 horas después de su creación se marca como fallida automáticamente, y las tareas de MiniMax no se pueden cancelar.
• outputs es una URL firmada en api.hop-base.com, válida por 24 horas desde el momento en que la tarea se completa. Consultar de nuevo devuelve la misma URL sin extenderla, y una URL vencida devuelve 410, así que descargue los resultados dentro de esa ventana.

Errores comunes y soluciones

Las validaciones propias del gateway devuelven {"error":{"message":…,"type":"invalid_request_error"}} sin code; guíese por message.

Textos habituales de 400 y los de 413 / 404:

400 first/last-frame image-to-video and multimodal reference generation are mutually exclusive: ...
400 {"error":{"message":"request body does not match the JSON contract: json: unknown field \"prompt\"","type":"invalid_request_error"}}
400 callback_url is not supported yet; poll /v1/video/tasks/{id} for task progress
request body exceeds the 64 MiB limit (got N bytes)
invalid task ID format
task not found            # también con la clave de otro usuario

El primero suele indicar una imagen de referencia sin rol; el segundo, que se envió prompt en el nivel superior: ponga el prompt en content.

Para tareas fallidas, actúe según error.message:

Facturación

MiniMax factura ambos modelos por segundo de video, a una tarifa que sigue la resolución de salida, no por token:

cargo = usage.billed_seconds × tarifa del nivel usage.bucket

• Un video de referencia se factura por su duración de entrada a esa misma tarifa: el input_seconds propio de MiniMax.
• Las imágenes de referencia son gratuitas hasta una franquicia; usage.extra_input_images cuenta las que la superan.
• Para H3-Max, MiniMax solo factura el video de salida y no cobra el material de entrada.
• Para H3-SelfHosted, la duración de entrada de un video de referencia se redondea hacia arriba a segundos enteros y se factura a la tarifa del nivel de salida; las imágenes de referencia por encima de 5 se facturan por imagen.

Un envío a MiniMax verifica el saldo disponible menos las estimaciones de las tareas en curso menos la estimación de esta solicitud; si eso no alcanza, recibe un 402 con code insufficient_balance, y la estimación se libera automáticamente al finalizar la tarea. Una tarea fallida nunca se factura. Cuando la tarea termina, el objeto usage de la raíz de la consulta también incluye cost_usd —el importe en USD realmente descontado de su saldo por esta tarea, 0 si falló sin cargo—, cost (el mismo cargo en CNY) y currency (siempre CNY).

Los precios de lista oficiales están en la página de precios. Su tarifa es la que aparece en el catálogo de modelos con la sesión iniciada, y el cargo real de cada solicitud está en su registro de uso. Vea el Resumen de video para las reglas compartidas por todas las familias de video.

Próximos pasos

• Resumen de video: comparación de las familias de video y la retención de saldo, tiempos de espera y URL de resultados que comparten
• API de texto a voz: MiniMax Speech 2.8 y clonación de voz
• Códigos de error y reintentos: incluye fallos de tareas asíncronas
• Concurrencia, tiempos de espera y facturación