Blog

Tutorial

Cómo usar minimax-h3 a través de la API de HiAPI: curl, Python y solicitudes ejecutables

Nov 10, 2026
Imagen de portada geométrica minimalista: sobre un fondo verde pino profundo, varios prismas grandes cortados en bloques de color planos, acentuados con verde salvia y verde neblina.
En esta página

Cómo se ve la integración de minimax-h3 de extremo a extremo

La generación de video no es una operación instantánea. minimax-h3 necesita recibir un prompt o una imagen de origen, programar la tarea en un grupo de GPU, codificar fotogramas y ensamblar el archivo de salida. Todo el proceso puede tardar desde unos segundos hasta varios minutos según la duración y la resolución. Si el endpoint de HiAPI bloqueara hasta que el archivo esté listo, tu cliente HTTP mantendría una conexión abierta durante todo el proceso: frágil ante reintentos, incompatible con los límites de tiempo de serverless y imposible de ejecutar en un manejador web de tipo solicitud/respuesta.

Por eso, la integración sigue la forma primero enviar, luego sondear, el patrón estándar de las APIs de medios asíncronas:

  1. Enviar. Haces un POST de una carga JSON que describe la tarea (prompt, imagen opcional, duración, relación de aspecto y cualquier parámetro específico del modelo). La API valida y devuelve inmediatamente un identificador de tarea y un estado inicial.
  2. Sondear. Llamas al endpoint de estado de la tarea con ese identificador a intervalos cortos. El estado pasa por en cola, procesando y luego éxito o fallo.
  3. Obtener. Una vez que el estado entra en un estado terminal, la respuesta incluye el resultado, normalmente una URL descargable del video generado.

Este modelo tiene tres consecuencias que determinan todo lo que sigue en esta guía:

  • El ID de tarea es tu único identificador. Persístelo. Si lo pierdes, no podrás recuperar la tarea; solo podrás reenviarla y pagar de nuevo por el trabajo.
  • Tu código tiene dos superficies de fallo, no una. El envío puede fallar (autenticación, carga mal formada) y el sondeo también puede fallar (tiempos de espera, errores de red transitorios, tarea terminada en fallo). Trátalos por separado.
  • El ritmo de sondeo es una decisión de diseño. Ser demasiado agresivo desperdicia solicitudes; ser demasiado lento hace que el usuario espere por un estado que ya estaba listo.

En este artículo, todas las llamadas van a la API unificada de HiAPI. Necesitas obtener una clave de API desde tu cuenta de HiAPI y referenciar el modelo como minimax-h3 en la carga. Todo lo demás —encabezado de autenticación, URL base, endpoint de sondeo— se comparte en toda la plataforma, así que el patrón que aprendas aquí se puede trasladar a otros modelos sin reestructurar el cliente.

Con este modelo mental claro, la forma más rápida de confirmar la configuración es una sola llamada curl.

Tu primera solicitud curl ejecutable

Antes de escribir código de aplicación, confirma que tu clave es válida y que puedes acceder a la API. Un comando curl puntual es la forma más barata de distinguir un problema de autenticación de un problema de carga.

Primero exporta tu clave, para que no quede en texto plano en el historial del shell:

export HIAPI_API_KEY="your-api-key-here"

Luego envía una tarea mínima de texto a video:

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Una respuesta exitosa devuelve un objeto JSON con el identificador de tarea y el estado. Su estructura se parece más o menos a esto:

{
  "id": "task_abc123xyz",
  "status": "queued",
  "model": "minimax-h3",
  "created_at": "2024-01-01T00:00:00Z"
}

Fíjate que todavía no hay URL de video. Esto es lo esperado: la tarea solo ha sido aceptada. Los nombres de campo de tu respuesta real pueden diferir ligeramente de los de la ilustración anterior; lee el cuerpo de la respuesta en lugar de suponer, y registra todo su contenido durante el desarrollo.

Qué hace cada parte de la solicitud

  • La URL apunta al recurso de generación de video en la plataforma HiAPI. Todas las llamadas a modelos comparten esta base, por eso cambiar de modelo solo implica cambiar la carga y no reescribir el código.
  • Authorization: Bearer lleva tu clave de API. Es la fuente de fallo más común, así que verifícala primero cuando algo vaya mal.
  • Content-Type: application/json es obligatorio. Sin él, el servidor puede rechazar o analizar incorrectamente el cuerpo de la solicitud.
  • model selecciona minimax-h3 explícitamente. Nunca lo omitas: la plataforma enruta según este valor.
  • prompt es la instrucción creativa. Sé específico sobre el sujeto, el movimiento de cámara y la iluminación; los prompts vagos producen videos vagos.
  • duration y aspect_ratio restringen la salida. Mantenlos dentro del rango admitido por el modelo; los valores fuera de rango son errores de validación de la carga, no fallos del servidor.

Confirma que la tarea existe

Inmediatamente después de enviar, obtén la tarea una vez para demostrar que el ID es válido:

curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Sustituye task_abc123xyz por el ID de la respuesta de envío. Si esto devuelve un estado, entonces tu clave, endpoint y identificador de tarea son correctos: ya puedes pasar a Python.

Vale la pena adoptar dos hábitos ahora: ejecutar curl con -sS para que los errores afloren en lugar de silenciarse, y citar siempre las URL. La expansión inesperada del shell en una carga JSON es una trampa de depuración que cuesta mucho más tiempo que las propias comillas.

Construir la misma solicitud en Python

La llamada curl prueba el contrato; Python es donde construyes algo reutilizable. No saltes directamente al bucle de sondeo; empieza con una pequeña clase de cliente que maneje el envío y la recuperación de resultados como dos métodos claros. Esta separación mantiene la lógica asíncrona fuera de tu capa de transporte.

Usa requests (o httpx si prefieres asíncrono); la forma es la misma en ambos casos.

import os
import time
import requests

BASE_URL = "https://api.hiapi.ai/v1"

class MiniMaxH3Client:
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ["HIAPI_API_KEY"]
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        })

    def submit(self, prompt: str, duration: int = 5,
               aspect_ratio: str = "16:9", **extra) -> str:
        payload = {
            "model": "minimax-h3",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            **extra,
        }
        resp = self.session.post(
            f"{BASE_URL}/video/generations",
            json=payload,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        return data["id"]

Hay varias decisiones deliberadas que vale la pena señalar.

Usa una sesión, no requests sin más. Reutilizar requests.Session mantiene viva la conexión entre las llamadas de envío y sondeo, lo cual importa cuando sondeas repetidamente el mismo host. También centraliza los encabezados, así que el de autenticación se define una sola vez.

Establece un tiempo de espera estricto al enviar. Treinta segundos es holgado para una solicitud que debería devolver casi de inmediato. Sin tiempo de espera, una fluctuación de red dejaría tu proceso colgado indefinidamente. Nunca hagas una llamada a una API remota sin configurar timeout.

Llama a raise_for_status() antes de analizar. La forma del cuerpo de una respuesta no 2xx suele ser distinta a la de una respuesta exitosa. Comprobar primero el código de estado significa que tu manejo de errores lee un mensaje de error bien formado en lugar de fallar al buscar la clave id.

Paso de **extra. Las opciones específicas del modelo evolucionan. Pasar argumentos de palabra clave adicionales te permite experimentar con nuevos parámetros sin editar la firma del método cada vez.

Úsalo

client = MiniMaxH3Client()
task_id = client.submit(
    "A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")

Eso es toda la ruta de envío. El cliente devuelve una cadena —el identificador de tarea— y nada más. Resiste la tentación de hacer que submit espere también el resultado. Mezclar envío y espera en un solo método difumina los reintentos: cuando falla, no puedes saber si la tarea llegó a crearse, así que corres el riesgo de generar duplicados. Mantenlos separados y deja que quien llama decida la estrategia.

Sondear resultados sin bombardear la API

El sondeo es la parte que más fácil se escribe con descuido. Un bucle ingenuo while True sin espera lanzaría cientos de solicitudes para una tarea que necesita dos minutos, y seguiría haciéndolo incluso después de que la tarea haya fallado.

Un bucle de sondeo correcto tiene cuatro responsabilidades: comprobar el estado, esperar, detenerse en un estado terminal y rendirse al final.

TERMINAL = {"succeeded", "failed", "cancelled"}

def wait_for(self, task_id: str, interval: float = 3.0,
             max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status", "unknown")
        if status in TERMINAL:
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")

Elegir el intervalo

Para la generación de video, un intervalo fijo de unos pocos segundos es un valor predeterminado razonable. Las tareas no terminan en los primeros segundos —la carga del modelo y la codificación de fotogramas requieren tiempo real—, así que sondear cada 200 ms no aporta nada salvo carga. Si quieres ser a la vez educado y eficiente, usa retroceso exponencial con límite superior: empieza con uno o dos segundos, multiplica por aproximadamente 1,5 en cada ronda hasta llegar a cinco o diez segundos y mantente ahí. El sondeo temprano captura rápido los fallos rápidos; el sondeo tardío mantiene bajo el coste durante los renderizados largos.

Detenerse correctamente

Trata cualquier estado no reconocido como no terminal y sigue esperando, pero solo hasta cierto límite. Importan dos condiciones de parada:

  • Estado terminal. Devuelve inmediatamente en caso de éxito. En caso de fallo, expón el mensaje de error de la respuesta en lugar de devolver un resultado vacío; la causa es importante para tus registros.
  • Presupuesto de tiempo real. Usa un reloj monótono, no el reloj de pared, para que los ajustes del reloj del sistema no hagan que tu bucle salga antes de tiempo o se ejecute para siempre. Elige un límite superior cómodamente mayor que la tarea realista más larga para la duración y resolución que hayas elegido, y trata alcanzarlo como un error operativo que merece una alerta.

Devolver el resultado

Cuando el estado es terminal y exitoso, la respuesta incluye la URL del video generado. Descárgalo pronto —las URL de resultado suelen tener caducidad— y, si necesitas acceso persistente, guárdalo en tu propio almacenamiento de objetos. No pases la URL del proveedor directamente al usuario final asumiendo que existirá para siempre.

Un consejo práctico más: registra en nivel de depuración el ID de tarea, el estado y el tiempo transcurrido de cada sondeo, y en nivel de información el resultado terminal. Cuando una tarea tarda más de lo esperado, esa línea de tiempo es la diferencia entre un diagnóstico de cinco minutos y una hora de conjeturas.

Formas de solicitud de texto a video e imagen a video

Ambos modos de generación comparten la mayor parte de la carga. La diferencia está en la entrada creativa, y esa diferencia tiene efectos posteriores sobre qué fallos deberías esperar.

Texto a video

Esta es la forma mostrada en las secciones anteriores: prompt más restricciones de salida. El modelo inventa todo: composición, movimiento, iluminación y detalles del sujeto. Tu carga incluye:

  • model: minimax-h3
  • prompt: la descripción de la escena
  • duration, aspect_ratio y cualquier otro control de salida

Como no hay nada que ancle la generación, la calidad del prompt domina el resultado. Describe el comportamiento de la cámara («avance lento», «plano estático sobre trípode») y la iluminación («luz de fondo en hora dorada»), en lugar de acumular adjetivos sobre la calidad. Los adjetivos grandilocuentes y vagos sirven de poco; las descripciones físicas concretas sirven mucho.

Imagen a video

La variante de imagen a video añade una referencia de imagen de origen a la misma solicitud. Normalmente proporcionas una URL de imagen o un identificador de recurso subido en un campo de imagen junto al prompt, y el modelo anima a partir de ese fotograma inicial.

client.submit(
    "Gentle wind moves the hair, subtle camera push forward",
    duration=5,
    image_url="https://example.com/portraits/source.jpg",
)

El prompt ahora desempeña un papel distinto: guía el movimiento y la cámara, no el contenido, porque el contenido visual ya está fijado por la imagen. Escribir una descripción completa de la escena suele ser contraproducente: el modelo no puede añadir posiciones que no estén en el encuadre. Mantén el prompt de movimiento breve y concreto.

Consulta la referencia de la solicitud para conocer los nombres exactos de los campos en el modo de imagen y los formatos de imagen aceptados, así como los rangos válidos de duración y relación de aspecto en ambos modos. Estas restricciones son precisamente las que provocan errores de validación de la carga, así que leerlas una vez te ahorra una ronda de depuración posterior.

Una regla práctica

Elige texto a video cuando necesites escenas novedosas: B-roll, clips de ambiente, visualización de conceptos. Elige imagen a video cuando la consistencia importe: animar fotos de producto, dar vida a retratos de personajes o convertir fotogramas de storyboard en tomas en movimiento. El modo es una diferencia de carga, no de integración, así que una sola clase de cliente puede servir a ambos con solo aceptar un parámetro de imagen opcional.

Depurar errores comunes

Cuando una llamada a minimax-h3 falla, la causa está casi siempre en uno de cuatro lugares. Investígalos en este orden.

1. Autenticación

Síntoma: respuesta 401 o 403, o un cuerpo de error que indica credenciales no válidas.

  • Confirma que el encabezado Authorization existe y tiene el formato Bearer <key>, con un solo espacio en medio.
  • Comprueba que la variable de entorno contiene realmente un valor: un salto de línea final pegado en la variable de entorno rompe el encabezado de una forma invisible en los registros.
  • Verifica que la clave pertenece al mismo proyecto de HiAPI que esperas y que no ha sido rotada.

La prueba más rápida: vuelve a ejecutar el curl original anterior. Si curl funciona y Python no, el error está en tu cliente, no en tu cuenta.

2. Carga mal formada

Síntoma: respuesta 400 o 422, o un mensaje de validación que nombra un parámetro.

  • Confirma que Content-Type: application/json está presente y que el cuerpo es JSON válido: una coma final sobrante es el culpable clásico.
  • Comprueba que model es exactamente minimax-h3.
  • Confirma que duration y aspect_ratio están dentro de los rangos admitidos por el modelo.
  • En el modo de imagen, confirma que la referencia de imagen es accesible y tiene un formato aceptado.

Lee literalmente el mensaje de error. Los errores de validación suelen nombrar el campo infractor; a menudo los desarrolladores lo pasan por alto y empiezan a reescribir partes irrelevantes de la carga.

3. El sondeo nunca termina

Síntoma: el estado sigue en cola o procesando después de un tiempo razonable, o el bucle se ejecuta para siempre.

  • Registra la respuesta de estado completa: puede que el valor de estado no sea el que tu código supone.
  • Comprueba el campo que lees. Si tu conjunto terminal comprueba "completed" pero la API devuelve "succeeded", tu bucle se ejecutará para siempre. Imprime una respuesta sin procesar al principio del desarrollo.
  • Confirma que el ID de tarea se copió exactamente, sin truncamiento ni espacios en blanco.
  • Añade un límite de tiempo real; un bucle atascado sin límite superior es un error de tu código, no de la API.

4. Tiempos de espera y errores de red transitorios

Síntoma: errores de conexión, tiempos de espera de lectura o respuestas 5xx al enviar o sondear.

  • Asegúrate de pasar un timeout explícito en cada llamada: el valor predeterminado de muchos clientes es ninguno, lo que significa que un socket colgado puede bloquear indefinidamente.
  • Distingue entre tiempo de espera de conexión y de lectura; un envío con tiempo de espera de lectura puede haber creado la tarea en realidad. Si se devolvió un ID de solicitud, regístralo desde los encabezados de la respuesta y comprueba si apareció una tarea antes de reenviar a ciegas.
  • Para un 5xx en el sondeo, reintenta: la tarea probablemente esté bien. Para un 5xx en el envío, verifica que no se creó una tarea para evitar generar duplicados.

Un hábito rápido de triaje: mantén un archivo curl de borrador junto al proyecto, con los comandos de envío y sondeo prellenados desde variables de entorno. Reproducir cualquier error fuera del código de la aplicación lleva unos segundos y te dice de inmediato si el problema es de transporte o de lógica.

Prepararlo para producción

Un script ejecutable no es un servicio ejecutable. Las tareas de video son lo bastante lentas como para que el tráfico de producción se solape, reintente y, de vez en cuando, falle de formas que una sola ejecución manual nunca revelaría. Cuatro patrones soportan la mayor parte del peso.

Reintentos con retroceso, pero solo donde es seguro

La estrategia de reintento depende de qué llamada falló:

  • El sondeo es intrínsecamente seguro de reintentar. Una comprobación de estado fallida no tiene efectos secundarios, así que reintenta con retroceso exponencial y jitter, limitado a unos pocos intentos.
  • El envío no se puede reintentar a ciegas. Un tiempo de espera no significa que la tarea no se haya creado. Antes de reenviar, comprueba si ya existe una tarea para esa solicitud (usando el ID de solicitud de los encabezados de respuesta, si está disponible, o una ventana corta de reconciliación). Como alternativa, haz que tus envíos sean idempotentes almacenando en caché el ID de tarea según un hash de la carga, de modo que una solicitud reintentada devuelva la tarea existente en lugar de iniciar un nuevo renderizado.
  • Los fallos a nivel de modelo —estado terminal failed— normalmente no deberían reintentarse automáticamente con la misma carga. Las mismas entradas tienden a fallar de la misma manera. Regístralo, alerta y deja que lo retome una persona o un prompt modificado.

Añade jitter a cada espera de retroceso. Sin él, un lote de workers que reintentan sincronizadamente produce picos sincronizados que empeoran la situación.

Registrar el ID de tarea en todas partes

El ID de tarea es el único vínculo persistente entre tu sistema y el video generado. En el momento en que el envío tenga éxito, escríbelo en los registros con campos estructurados: task_id, modelo, duración y marca de tiempo del envío. Cuando un usuario informe que falta un video, buscar por ID de tarea encontrará el historial completo en segundos. Registra también el estado terminal y el tiempo transcurrido, para que puedas responder «cuánto suele tardar esto» con datos en lugar de con memoria.

Establecer un presupuesto de tiempo de espera explícito

Piensa en un presupuesto total para toda la operación, no solo en el tiempo de espera de cada solicitud. Una tarea tiene tres fases —envío, espera y descarga— y cada una necesita límites. Una estructura razonable:

  • Tiempos de espera cortos para las solicitudes de envío y sondeo, para detectar rápido las conexiones muertas.
  • Un límite de tiempo real total para el sondeo, fijado según la duración y resolución más largas que admitas, con margen.
  • Una descarga acotada con escritura en streaming, para que los archivos grandes no agoten la memoria ni cuelguen el worker.

Cuando se agota el presupuesto, haz fallar la tarea de forma limpia, libera el slot de concurrencia e informa un error claro. Un fallo predecible es mejor que una solicitud colgada hasta que la plataforma reinicie el contenedor.

Separar el envío del consumo

El diseño de primero enviar y luego sondear se corresponde naturalmente con una arquitectura de colas: tu manejador web envía y devuelve el ID de tarea, un worker en segundo plano sondea y almacena el resultado, y el cliente sondea tu endpoint de estado. Esto desacopla la latencia de cara al usuario del tiempo de renderizado, facilita la aplicación de límites de concurrencia y hace que un pico de envíos no agote el grupo de hilos de tu capa web.

Si aciertas en estos cuatro puntos, la forma asíncrona de minimax-h3 trabajará contigo en lugar de contra ti: las tareas se rastrean, los reintentos son seguros, los fallos son visibles y nada se cuelga indefinidamente.

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