¿Cómo se usa la API de MiniMax H3 Max? De texto o imágenes a video

MiniMax H3 Max se ofrece en HiAPI bajo dos nombres de modelo: texto a video minimax-h3-max/text-to-video e imagen a video minimax-h3-max/image-to-video. Genera videos de 0.92–15 segundos: 480P a $0.072 por segundo, 768P a $0.115 por segundo y 1080P a $0.229 por segundo, con cobro según los segundos solicitados. Primero genera un corto horizontal de 5 segundos con el siguiente prompt del barco de papel; con 768P el presupuesto es $0.575. Para integrar la API, envía una tarea una sola vez y luego usa el taskId devuelto para obtener el video.

MiniMax H3 Max ya está disponible en HiAPI. Genera con este prompt →. El prompt se rellena automáticamente; después selecciona manualmente 5 segundos, 768P y 16:9.

El primer video: el barco de papel tras la lluvia

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

Genera con este prompt →

Este prompt separa la acción y el movimiento de cámara: el barco de papel flota con el agua, una cámara baja lo sigue con suavidad y el sonido se resuelve con el canto lejano de pájaros. Cuando sustituyas el barco de papel por tu propio sujeto, conserva primero una acción y un movimiento de cámara; así será más fácil ver qué ajustar.

Prueba en línea o integración con la API: ¿cuál elegir?

Si primero quieres ver el resultado, abre la página del modelo de texto a video, copia el prompt, elige la duración y la resolución, y envía la generación. Si ya tienes una imagen inicial, cambia a la página del modelo de imagen a video y sube tu primer fotograma. Para integrarlo en una aplicación, obtén primero una clave en la página de API Key, crea la tarea con una petición del servidor, guarda el taskId y espera a que la tarea termine correctamente para leer la URL del video.

Se recomienda indicar la resolución de forma explícita: 5 segundos en 480P cuestan $0.36, en 768P $0.575 y en 1080P $1.145. Confirma la acción con baja resolución y luego elige el nivel según tus necesidades de entrega; consulta la tabla completa de presupuesto en Precios de H3 y H3 Max.

cURL: crear la tarea y consultar el resultado

Después de definir la API Key como variable de entorno local HIAPI_API_KEY, ejecuta esta petición:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

Si el POST agota el tiempo de espera, la conexión se interrumpe o la respuesta no permite confirmar que se creó la tarea, el estado de envío es desconocido: consulta primero el historial de tareas y no vuelvas a ejecutar el POST directamente. Cuando confirmes que la respuesta tiene code=200, que data es un objeto y que data.taskId no está vacío, guarda el ID y sustituye YOUR_TASK_ID en la URL de consulta:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Mientras la tarea está pendiente, sigue consultando el mismo ID. Cuando data.status sea success, lee la url de la entrada de video en data.output; si es fail, revisa el mensaje de error de la tarea. Si hay errores de entrada o de autenticación, corrige primero el problema correspondiente; si ya tienes un ID de tarea, sigue consultando esa tarea.

Python: enviar una vez y esperar la misma tarea

El siguiente ejemplo usa la biblioteca estándar de Python. Hace un solo POST y valida la respuesta; si el resultado del envío es desconocido, se detiene y avisa que hay que consultar el historial de tareas. Si una consulta falla temporalmente, conserva el ID de tarea y continúa con GET; 600 segundos es el límite de espera de este ejemplo.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Controlar el primer o el último fotograma con imágenes

Para que el video empiece a partir de la imagen de tu producto, cambia el nombre del modelo a minimax-h3-max/image-to-video y añade first_frame_image en input. Para especificar el final, añade last_frame_image. Puedes enviar solo el último fotograma o enviar tanto el primero como el último; imagen a video no tiene el campo aspect_ratio, y la relación de aspecto sigue a la imagen.

Campo	Uso
prompt	Obligatorio; máximo 50000 caracteres; describe acción, movimiento de cámara y sonido
duration	0.92–15 segundos; admite decimales; por defecto 5 segundos
resolution	480P, 768P o 1080P; por defecto 768P
aspect_ratio	Solo texto a video: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16; por defecto 16:9
first_frame_image	Imagen a video: URL pública de la imagen del primer fotograma
last_frame_image	Imagen a video: URL pública de la imagen del último fotograma
target_audio_url	Opcional; sustituye la pista de audio por la tuya; al menos 2 segundos
prompt_expansion_mode	Opcional: disabled / balanced (por defecto) / quality

A continuación se muestra el cuerpo completo de una petición con primer y último fotograma; las URL de imagen son marcadores de posición para tus propias direcciones de acceso público; las imágenes definen la composición inicial y final:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Si solo necesitas controlar el último fotograma, puedes eliminar first_frame_image y conservar last_frame_image. Escribe solo el movimiento de cámara en el prompt; la imagen define el sujeto y la composición inicial. Para varios planos, indica cada cambio en el prompt; los campos de la petición siguen siendo los de esta tabla, no añadas camera_angle, mode ni watermark.

Para un corto vertical, en texto a video escribe directamente "aspect_ratio": "9:16"; en imagen a video, usa una imagen inicial vertical, y la relación de aspecto seguirá a la imagen.

Al integrarlo en una aplicación, coloca el callback en el nivel superior de la petición

Añade un callback opcional en el nivel superior de la petición de creación, junto a model e input:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Combina este fragmento con la petición completa. El receptor debe deduplicar por taskId, tratar por separado los éxitos y los fallos, y compensar las notificaciones perdidas con consultas de tarea. Después de obtener el ID de tarea, no vuelvas a enviarla; si hay errores HTTP, lee primero el contenido de la respuesta para distinguir si es un problema de autenticación o de parámetros.

Revisa estos cuatro puntos tras la integración

1. Guarda un data.taskId no vacío y sigue usándolo aunque la consulta falle.
2. Confirma que el estado final sea success o fail; no confundas el límite de espera con el tiempo del modelo.
3. En data.output de una tarea exitosa, busca la URL del video con type=video.
4. Descarga el resultado y comprueba que el tamaño real, la duración y la imagen cumplan los requisitos de entrega.

Preguntas frecuentes

¿H3 Max puede usar videos o audios de referencia? H3 Max sustituye la pista de audio con target_audio_url, pero no acepta videos de referencia; si necesitas referencias multimodales de imagen, video y audio, elige MiniMax H3.

¿Es Max más caro que H3? H3 2K cuesta $0.1189 por segundo; Max 768P cuesta $0.115 por segundo y 1080P $0.229 por segundo. Elige primero el modelo según la resolución y el material de referencia que necesites, y luego calcula el presupuesto según la duración.

¿Cómo empezar con un corto vertical? En texto a video, escribe "aspect_ratio": "9:16"; en imagen a video, prepara una imagen inicial vertical, y la relación de aspecto seguirá a la imagen.

Copia el prompt del barco de papel, genera con este prompt → y crea primero un corto de 5 segundos. Para más formas de escribir acciones y movimientos de cámara, consulta 4 videos reales y prompts completos; para todos los campos, consulta la documentación de parámetros de texto a video y la documentación de parámetros de imagen a video.