Tutorial
Cómo usar minimax-h3 a través de la API de HiAPI: curl, Python y solicitudes ejecutables
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:
- Enviar. Haces un
POSTde 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. - 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.
- 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: Bearerlleva 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/jsones obligatorio. Sin él, el servidor puede rechazar o analizar incorrectamente el cuerpo de la solicitud.modelselecciona minimax-h3 explícitamente. Nunca lo omitas: la plataforma enruta según este valor.promptes 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.durationyaspect_ratiorestringen 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-h3prompt: la descripción de la escenaduration,aspect_ratioy 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
Authorizationexiste y tiene el formatoBearer <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/jsonestá presente y que el cuerpo es JSON válido: una coma final sobrante es el culpable clásico. - Comprueba que
modeles exactamenteminimax-h3. - Confirma que
durationyaspect_ratioestá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
timeoutexplí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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio