API de video MiniMax Hailuo H3

HopBase expone MiniMax Hailuo H3 a través del contrato oficial v2 de MiniMax. Es una API asíncrona: envíe una tarea y luego consulte el ID de tarea de HopBase. Use una clave que tenga habilitado el grupo de MiniMax y confirme la disponibilidad con GET /v1/models antes de enviar trabajo de pago.

Endpoints

Todas las solicitudes usan Authorization: Bearer sk-tu-clave y Content-Type: application/json. 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 llamar al upstream.

Modelo

Use el ID exacto MiniMax-H3. No hay alias registrados; los nombres de modelo desconocidos se rechazan.

Contrato de solicitud

content es un arreglo multimodal. Debe contener exactamente un elemento text no vacío (el prompt, hasta 7,000 caracteres). Los elementos de medios declaran su rol de forma explícita:

Los elementos de primer/último fotograma y los elementos reference_* son mutuamente excluyentes en una solicitud.

Las referencias de audio deben ir acompañadas de al menos una referencia de imagen o video — la entrada de referencia de solo audio se rechaza. La entrada de referencia mixta tiene un límite total de 12 archivos.

Los valores url de medios aceptan una URL pública absoluta http(s) o un URI data: (incrustación en base64). Los localizadores mm_file:// se rechazan — el archivo pertenecería a su propia cuenta de MiniMax, a la que el gateway no puede acceder. callback_url no es compatible; consulte la tarea mediante polling.

Especificaciones de entrada y salida

• Salida: 24 FPS; 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.
• Imágenes: JPG / JPEG / PNG / WEBP / HEIC / HEIF, ≤30 MB cada una, 256-5760 px por lado, aspecto entre 5:2 y 2:5.
• Referencias de video: H.264 / H.265, ≤50 MB cada una, 2-15 s por clip y ≤15 s combinados.
• Referencias de audio: WAV / MP3, ≤15 MB cada una, 2-15 s por pista y ≤15 s combinados.
• Los límites de tamaño son por recurso; el cuerpo completo de la solicitud tiene un límite de 64 MB, así que prefiera referencias por URL sobre incrustaciones data: para medios grandes.

Relación de aspecto

• Texto a video: ratio es obligatorio y no puede ser adaptive — elija 21:9, 16:9, 4:3, 1:1, 3:4 o 9:16.
• Imagen a video (primer / último fotograma): la salida siempre sigue la imagen de entrada. Se acepta cualquier valor ratio legal y se normaliza a adaptive, coincidiendo con el comportamiento oficial. Para obtener una relación específica, recorte primero la imagen de fotograma.
• Referencia multimodal: ratio es opcional y por defecto es adaptive.

Ejemplo — texto a video

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 con dron sobre montañas nevadas encima de un mar de nubes al amanecer" }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

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" }

Ejemplo — imagen a video

{
  "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
}

Ciclo de vida de la tarea

Haga polling de GET /v1/video/tasks/{task_id}. El estado avanza queued → processing → completed | failed. Un clip típico se completa en 1.5-3 minutos. Al completarse, la respuesta lleva URLs de relay estables de HopBase (los enlaces de descarga del upstream expiran; el relay los renueva de forma transparente):

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

Facturación

La facturación ocurre solo cuando la tarea tiene éxito, a partir del consumo reportado por el upstream:

• Los segundos de salida y los segundos de entrada de video de referencia se facturan según el nivel de resolución (768P o 2K).
• Las primeras 5 imágenes de entrada son gratuitas; cada imagen adicional se factura por imagen.
• La referencia de audio es gratuita. Las generaciones fallidas o filtradas por seguridad nunca se facturan.

Consulte la página de precios para conocer los precios de lista oficiales; su tarifa efectiva se muestra en la Plaza de modelos tras iniciar sesión.