Blog

Tutorial

Cómo llamar a minimax-h3-max-turbo de texto a vídeo mediante la API de HiAPI

Nov 12, 2026
Ilustración de portada: una sección transversal mineral plana y facetada en tonos verde petróleo profundo y verde azulado, como una lámina de gemología impresa, sobre un fondo oscuro.
Modelo
minimax-h3-max-turbo
En esta página

Qué hace este endpoint y cuándo usarlo

minimax-h3-max-turbo/text-to-video es un endpoint de modelo de texto a vídeo expuesto a través de la API de HiAPI. Envías un prompt de texto que describe la escena objetivo, junto con unos pocos parámetros que controlan la forma de la salida, y HiAPI devuelve el vídeo generado. Este modelo es muy adecuado cuando tienes una descripción textual pero no material de origen: clips de marketing, tomas de transición para redes sociales, previsualizaciones de storyboards, vídeos en bucle de fondo para aplicaciones o generación por lotes de variantes de un mismo concepto creativo.

Antes de escribir código, hay varias características que conviene tener en cuenta:

  • Es un endpoint generativo, no una plantilla. La salida solo es predecible en su estructura (obtendrás un vídeo); el contenido en sí no es predecible. Trata cada tarea como un renderizado completamente nuevo y diseña los prompts pensando en la reutilización.
  • Es asíncrono. La llamada de envío no devuelve directamente los bytes del vídeo final. Primero obtienes un identificador de tarea y luego consultas el resultado. Cualquier integración que asuma una respuesta síncrona fallará en el primer timeout.
  • La salida la determinan los parámetros de la solicitud. La duración y la resolución cambian el coste de renderizado y el tiempo real que tarda, así que los parámetros que elijas son también decisiones de latencia y presupuesto.
  • No se necesita medio de origen. No tienes que subir vídeo ni imágenes; el prompt y los parámetros son toda la superficie de entrada.

¿Cuándo deberías usar otra solución? Si ya tienes material y quieres reestilizarlo o extenderlo, este no es el endpoint adecuado. Si necesitas control a nivel de fotograma sobre el movimiento de cámara o la composición precisa, un prompt de texto resulta demasiado laxo. Y si solo necesitas una imagen estática, el endpoint de texto a imagen es más barato y más rápido. Usa minimax-h3-max-turbo/text-to-video cuando el prompt baste como especificación de la toma.

El resto de esta guía cubre, en orden, la autenticación, una llamada curl ejecutable, la llamada equivalente en Python, el ciclo de vida de la tarea, los parámetros clave, los errores que encontrarás y los pasos de endurecimiento antes de salir a producción.

Requisitos previos y autenticación

Antes de la primera solicitud necesitas tres cosas:

  1. La clave de API de tu cuenta de HiAPI. Trátala como un secreto: cárgala desde una variable de entorno, nunca la confirmes en el repositorio y rótala de inmediato si se filtra.
  2. La URL base de HiAPI. Todas las llamadas de esta guía van al mismo host base; el modelo se selecciona mediante el segmento de ruta, no con un dominio distinto por modelo.
  3. Un cliente HTTP. curl para pruebas de humo y cualquier biblioteca estándar o cliente HTTP para el código de servicio.

Cómo se pasa la clave

HiAPI autentica las solicitudes mediante un token bearer en la cabecera Authorization. La forma es siempre la misma:

export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Dos hábitos ahorran muchísimo tiempo de depuración:

  • La cabecera debe escribirse con exactitud. La A de Authorization en mayúscula, Bearer seguido de un espacio y luego la clave. Un espacio de menos es la causa más común de un 401 misterioso.
  • Envía siempre Content-Type: application/json. Los servidores que esperan JSON rechazan o analizan mal los cuerpos que no llevan esta cabecera, y el error que recibes suele decir que falta un campo en lugar de la causa real.

Valida antes de desarrollar

No empieces directamente con el endpoint de vídeo. Haz primero una llamada barata y rápida para confirmar que la clave y la URL base se resuelven correctamente, y luego continúa. Si esta comprobación de sanidad falla, nada de lo que venga después funcionará y estarás depurando en el nivel equivocado. Mantén la clave en un solo lugar del repositorio —un pequeño módulo de cliente— para que rotarla más adelante sea cambiar una línea.

Solicitud curl ejecutable

La llamada de envío envía el prompt y los parámetros como cuerpo JSON a la ruta del modelo. Esta es la llamada mínima ejecutable:

curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Al amanecer, un lento travelling aéreo hacia delante sobre un bosque de pinos brumoso, luz volumétrica suave, aspecto cinematográfico",
    "duration": 5,
    "resolution": "720p"
  }'

Qué hace cada parte:

  • -X POST: las tareas de generación se crean mediante POST.
  • URL: el host base más la ruta minimax-h3-max-turbo/text-to-video. Guarda el host base en una variable para que pruebas y producción apunten al mismo camino de código.
  • Authorization: el token bearer descrito en la sección anterior.
  • Content-Type: declara el cuerpo JSON.
  • prompt: la única entrada creativa obligatoria. Escríbelo como la descripción de una toma: sujeto, comportamiento de cámara, iluminación y atmósfera. Las frases nominales cortas producen resultados ambiguos; una o dos frases con una dirección visual concreta funcionan mucho mejor.
  • duration y resolution: parámetros que controlan la forma de la salida, tratados en una sección propia más abajo.

Usa -sS para que curl sea silencioso pero siga imprimiendo errores, y una herramienta de impresión formateada para la respuesta durante la exploración. La respuesta es un JSON con el identificador de la tarea; guárdalo, porque lo necesitarás para consultar el vídeo terminado. No esperes que esta respuesta contenga los bytes del vídeo.

Si al depurar quieres ver exactamente qué se envió, añade -v para obtener salida detallada, pero elimínala antes de compartir registros, ya que la salida detallada puede contener cabeceras.

Solicitud equivalente en Python

La versión en Python es la misma solicitud, solo que carga la clave desde el entorno y analiza la respuesta. Aquí tienes un pequeño cliente reutilizable:

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"


def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
    payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
    resp = requests.post(
        f"{BASE_URL}{MODEL_PATH}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = submit_video(
        "Al amanecer, un lento travelling aéreo hacia delante sobre un bosque de pinos brumoso, luz volumétrica suave, aspecto cinematográfico"
    )
    print(job)

Notas al adaptarlo:

  • json=payload establece a la vez el cuerpo y el tipo de contenido; no serialices manualmente otra vez.
  • timeout=30 limita el tiempo de la llamada de envío. El envío es rápido, el renderizado no, y por eso aquí el timeout es corto y la espera la asume el sondeo.
  • raise_for_status() convierte las respuestas no 2xx en excepciones, de modo que los fallos de autenticación y validación se manifiestan de inmediato en lugar de devolver silenciosamente un cuerpo de error que luego analizarías por error como una tarea.
  • Devuelve el JSON analizado como diccionario y extrae el identificador de tarea en el punto de llamada. Así la función auxiliar se mantiene genérica y el código de orquestación decide qué hacer con él.

Si usas una pila asíncrona, la misma forma se aplica al cliente HTTP que elijas: construye las cabeceras una vez, haz POST del cuerpo, comprueba el estado y devuelve el cuerpo de respuesta analizado.

Gestión del ciclo de vida de la tarea asíncrona

La generación lleva tiempo, así que el endpoint se divide en envío y sondeo. El ciclo de vida es siempre: enviar, recibir el identificador de tarea, sondear la tarea hasta que informe un estado terminal y después obtener la salida.

Envío

Envía el POST descrito antes y lee el identificador de tarea de la respuesta. Regístralo de inmediato y asócialo a tu propio ID de solicitud, para que si un sondeo falla más tarde puedas rastrear hasta el prompt original.

Sondeo con retroceso

No sondees en un bucle apretado. Empieza con un intervalo corto y luego retrocede:

def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
    deadline = time.time() + max_wait
    interval = 2.0
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}{MODEL_PATH}/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        job = resp.json()
        status = job.get("status")
        if status in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

Tres detalles hacen que este código sea fiable. Primero, la fecha límite: siempre hay que rendirse al final y lanzar un timeout, en lugar de sondear para siempre. Segundo, el retroceso acotado: empieza con unos segundos, multiplica progresivamente y pon un tope al intervalo, para seguir avanzando sin saturar la API. Tercero, el tratamiento de estados terminales: considera terminales solo el éxito y el fallo, y devuelve el objeto de tarea para que quien llama pueda ramificar.

Obtención del resultado

Cuando la tarea informa éxito, la respuesta lleva la ubicación del vídeo terminado. Descárgalo o transmitirlo cuanto antes a tu propio almacenamiento y registra la URL junto con el ID de tarea. No asumas que el enlace es permanente y no obtengas el vídeo en cada iteración de sondeo. Sondea el estado de la tarea y luego obtén el vídeo una sola vez al tener éxito.

Parámetros de duración y resolución

Dos parámetros de la solicitud determinan la salida y, a la vez, el tiempo de renderizado y el coste de la llamada.

duration

La longitud del clip generado. Cuanto más largo es el clip, más aumenta proporcionalmente el tiempo de renderizado, lo que implica una ventana de sondeo más larga y una mayor probabilidad de que salte el timeout del cliente. Consejos prácticos:

  • Ajusta la duración al caso de uso. Las tomas de transición para redes sociales son cortas; un bucle de fondo solo necesita ser lo bastante largo para repetirse de forma aceptable. Generar más de lo que se va a mostrar es puro desperdicio.
  • Empieza corto al iterar. Ajusta el prompt con una duración corta y luego vuelve a renderizar el prompt ganador con la longitud final.
  • Recuerda que el coste crece con el tamaño de la salida. La facturación se calcula por la longitud de la salida, así que la duración es a la vez una palanca creativa y una palanca de presupuesto.

resolution

La calidad espacial de la salida. Una resolución mayor aporta más detalle, pero consume más tiempo de renderizado y más coste. Recomendaciones:

  • Elige según el destino de entrega, no según la hoja de especificaciones. Si el vídeo aparecerá en un feed o en un reproductor pequeño, generar una resolución superior a la de ese contexto no aporta ningún beneficio.
  • Itera a baja resolución y entrega a alta resolución. Previsualiza con una resolución menor mientras sigues modificando el prompt y luego vuelve a enviar el prompt aprobado con la resolución de entrega.
  • Ajustes más altos implican esperas más largas. Ajusta la fecha límite del sondeo a la combinación máxima que permitas, no a la mínima.

Mantén ambos valores en un mismo objeto de configuración, en lugar de dispersarlos por el código, para que el cambio de previsualización a producción sea una edición intencionada y visible, no un literal olvidado.

Depuración de errores comunes

La mayoría de los fallos encajan en cuatro categorías. Antes de tocar el código, asocia el síntoma con la categoría.

Fallos de autenticación

Un 401 significa que HiAPI no acepta tus credenciales. Comprueba en orden: que la cabecera Authorization existe y está bien escrita; que hay exactamente un espacio después de Bearer; que la clave es la vigente y no proviene de otro proyecto; que la variable de entorno está realmente cargada (un salto de línea al final al pegar la clave es un problema clásico). Confírmalo mostrando la longitud de la variable, no la clave en sí.

Fallos de validación

Un 4xx que no sea 401 suele significar que el cuerpo de la solicitud está mal. Falta Content-Type o no es application/json; falta prompt o está vacío; duration o resolution están fuera del conjunto permitido. Lee el mensaje de error al pie de la letra; normalmente indica el campo problemático. Reproduce con la versión curl, porque ahí no hay una capa de biblioteca que oculte el cuerpo.

Timeouts

Hay dos timeouts distintos. Un timeout de envío significa que el POST en sí no devolvió, normalmente por la ruta de red o por un timeout de cliente demasiado agresivo. Un timeout de sondeo significa que la tarea no alcanzó un estado terminal antes de tu fecha límite; o el renderizado realmente tarda más, o tu fecha límite se fijó con ajustes de previsualización en vez de producción. Para arreglar lo segundo, aumenta max_wait para duraciones y resoluciones grandes, no acortes el intervalo de sondeo.

Errores de sondeo

Los más sutiles. Sondear sin dormir desperdicia cuota y atrae limitación de tasa; sondear con un intervalo fijo y corto tiene el mismo efecto. Sondear un ID de tarea equivocado, normalmente porque reutilizaste una variable entre envíos. Tratar un estado intermedio como error. Y obtener la URL del vídeo en cada iteración en lugar de una vez al tener éxito. Registra el ID de tarea y cada estado observado; la secuencia te dirá de inmediato cuál de estos has encontrado.

Lista de comprobación de producción antes del lanzamiento

Pasar de un script funcional a un servicio desatendido significa añadir varias capas alrededor de la misma solicitud.

  • Reintentos con jitter. Reintenta errores de red transitorios y respuestas 5xx con retroceso exponencial y aleatorización. Nunca reintentes errores de validación; fallarán igual y consumirán cuota.
  • Timeouts acotados en todas partes. Timeout corto para el envío, una fecha límite más larga para el sondeo (ajustada a la duración y resolución máximas que permitas) y también timeout para la descarga del vídeo.
  • Registro estructurado. Registra tu ID de solicitud, el ID de tarea, cada transición de estado observada y el resultado final, pero nunca la clave de API ni las cabeceras completas. Cuando algo falle a las tres de la madrugada, este registro es tu única prueba.
  • Idempotencia en tu capa. Mantén un mapa de tu propio ID de solicitud al ID de tarea, para que un reintento del cliente no genere silenciosamente un segundo renderizado.
  • Control de costes. La facturación se calcula por la longitud de la salida, así que fija topes a la duración y resolución máximas que acepta el servicio, y mantén las previsualizaciones de prompts con ajustes bajos hasta que una aprobación humana o por reglas autorice el renderizado final.
  • Higiene de claves. Carga las claves desde un almacén de secretos, rótalas según un calendario y usa claves distintas para pruebas y producción, para que una clave de pruebas filtrada no pueda consumir el presupuesto de producción.
  • Atribución de resultados. En cuanto una tarea tenga éxito, copia el vídeo terminado a un almacenamiento que controles y trata la URL de entrega como un enlace temporal.

Con todo esto en su sitio, el endpoint se convierte en una dependencia predecible en lugar de una fuente de sorpresas. Confirma primero las credenciales con la solicitud curl de arriba, luego integra el cliente de Python en tu servicio y envuélvelo con las comprobaciones de esta lista.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API