Tutorial
Cómo usar minimax-h3-max-turbo/image-to-video a través de la API de HiAPI: curl, Python y ejemplos de solicitud funcionales
En esta página
Qué hace este endpoint y cuándo usarlo
minimax-h3-max-turbo/image-to-video recibe una imagen de origen más un prompt de texto y devuelve un video corto que comienza con esa imagen. La imagen actúa como primer fotograma (o ancla visual), por lo que la salida hereda su composición, paleta de colores e identidad del sujeto. A continuación, el prompt describe lo que debería ocurrir después: el movimiento de cámara, la acción del sujeto y la atmósfera.
Cuándo elegirlo en lugar de texto a video
Texto a video es la herramienta adecuada cuando no tiene una referencia visual y desea que el modelo cree todo por sí mismo. Imagen a video es la elección correcta cuando el primer fotograma es lo importante: ya tiene una imagen de producto aprobada, un fotograma clave del guion gráfico, un diseño de personaje o una foto subida por el usuario, y necesita que se mueva manteniendo su recognoscibilidad. En concreto, los equipos utilizan este endpoint en los siguientes casos:
- El primer fotograma es un requisito contractual. El equipo de marketing necesita abrir con la imagen principal exacta, no con una imagen similar.
- La consistencia entre fragmentos es importante. Reutilizar la misma imagen de origen mantiene estables el personaje o el producto a lo largo de una serie de fragmentos.
- Está animando contenido de usuarios. Las fotos subidas por los usuarios finales deben animarse, no reimaginarsee.
- Desea un alcance de prompt más enfocado. Describir movimiento es más sencillo que describir toda la escena desde cero, por lo que el prompt se mantiene breve y predecible.
Este endpoint es asíncrono: se envía una tarea y luego se recupera el video renderizado. Esta forma encaja bien en backends impulsados por colas, como se detalla más adelante. Para conocer la superficie completa de parámetros, consulte la página del modelo.
Requisitos previos y estructura de la solicitud
Antes de llamar al endpoint, confirme que dispone de cuatro elementos:
- Una clave de API. Créela en su cuenta de HiAPI y envíela como token bearer. Trátela como confidencial: nunca la incruste en el código del cliente.
- La URL base. Todas las solicitudes se envían al host unificado de la API de HiAPI; la ruta del endpoint es el identificador del modelo.
- Una imagen de origen accesible o codificable, ya sea una URL HTTPS pública o una carga útil en base64, según lo que acepte el esquema de la solicitud.
- Un cliente HTTP:
curlpara pruebas rápidas y cualquier biblioteca estándar orequestsen Python para la integración real.
Componentes de la solicitud
Independientemente del lenguaje, cada envío de tarea contiene las mismas partes conceptuales:
- Modelo / endpoint:
minimax-h3-max-turbo/image-to-video, que forma parte de la ruta de la solicitud y se repite en el cuerpo de la solicitud para mayor claridad. - Imagen de origen: el primer fotograma. Este es el campo que distingue imagen a video de texto a video, y también el que más fácilmente provoca errores de validación.
- Prompt: descripción del movimiento y de la escena. Describa solo lo que cambiará, no lo que ya está presente en la imagen.
- Sugerencias de generación opcionales: controles de duración y estilo de resolución, si el endpoint los ofrece. Envíe solo los parámetros documentados en el esquema; las claves desconocidas son una causa común de respuestas 4xx.
El envío devuelve un identificador de tarea y un estado. El video en sí llega más tarde mediante una segunda solicitud; por eso la sección de sondeo a continuación es tan importante como la llamada de envío.
Una solicitud curl funcional
El siguiente comando envía una tarea de imagen a video. Antes de ejecutarlo, sustituya los marcadores de posición (los tokens en mayúsculas entre corchetes angulares) por sus propios valores.
curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
}'
Algunas notas prácticas sobre este comando:
- Lea la clave desde una variable de entorno.
$HIAPI_API_KEYevita que la clave acabe en el historial del shell, siempre que la exporte en lugar de pegarla en línea. - Para las primeras pruebas, use una URL de imagen pública. Esto elimina el factor de la codificación base64 y confirma que la autenticación y la conexión funcionan correctamente.
- Mantenga pequeño el cuerpo JSON. La carga útil de
-des toda la solicitud; una coma de menos aquí produce un 400 confuso en lugar de un error de esquema claro. - Entrecomille el prompt. Los prompts con signos de puntuación rompen las cadenas del shell sin comillas.
La respuesta es un objeto de tarea, no un video. Capture el ID de tarea: lo usará en la solicitud de sondeo. Si la llamada falla de inmediato, pase a la sección de solución de problemas; los errores de autenticación y de carga útil se manifiestan en este paso, no más tarde.
La misma solicitud en Python
A continuación se muestra la llamada de envío equivalente en Python usando requests. Supone que HIAPI_API_KEY ya está definida en las variables de entorno.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"
payload = {
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": (
"Slow push-in on the product, soft studio light shifting "
"across the surface, shallow depth of field."
),
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))
Puntos clave que debe conservar al adaptar este fragmento:
- El tiempo de espera no es opcional. El envío es rápido, pero un socket colgado en un controlador de solicitudes web arrastrará consigo a su worker.
- Llame a
raise_for_status()antes de analizar la respuesta. Convierte un 401 silencioso en una excepción que puede registrar realmente. - Devuelva el ID de tarea, no la respuesta. En un servicio, la función de envío debe devolver el identificador para que un sondeador independiente, o una tarea en segundo plano, se encargue de la espera.
- Guarde la carga útil en una variable. Una vez que la llamada tenga éxito, sustituir la URL de la imagen por una URL de carga firmada o una cadena base64 requiere cambiar una sola línea.
Aquí se utiliza deliberadamente un cliente HTTP simple en lugar de una biblioteca envolvente: la forma de la solicitud es el contrato, y usted debería poder reproducirla en cualquier lenguaje que use su stack.
Preparar la imagen y el primer fotograma
La mayoría de las tareas de imagen a video fallidas fallan por la imagen, no por el prompt. Adoptar algunos hábitos evita esto.
Formato y entrega
Use un formato raster estándar y ampliamente compatible, como JPEG o PNG, y asegúrese de que la URL sea accesible públicamente, sin cookies, sin redirecciones a una página de inicio de sesión y sin depender de firmas caducadas generadas después del envío. Si sus recursos están en un bucket privado, genere una URL firmada cuya vigencia sea claramente superior al tiempo de ejecución previsto de la tarea. Para cargas útiles en base64, si el esquema espera bytes codificados sin procesar, elimine el prefijo data-URI y asegúrese de que el tamaño codificado esté muy por debajo de los límites documentados.
Dimensiones y composición
El modelo renderiza el video con un tamaño de salida fijo, por lo que la imagen de origen se ajusta. Dos consecuencias:
- Coincida con la relación de aspecto deseada. Enviar una foto vertical a una renderización horizontal hará que se recorte o se añadan barras negras, y el sujeto podría quedar descentrado.
- Deje margen para el movimiento. Si el prompt describe un acercamiento de cámara o un sujeto que se mueve hacia arriba, deje espacio en esa dirección en la imagen de origen.
Mantener intacto el primer fotograma
El fotograma inicial depende principalmente de la propia imagen. Escriba el prompt como una instrucción sobre lo que ocurre después del primer fotograma: describa el comportamiento de la cámara, la acción del sujeto y los cambios de iluminación. Evite volver a describir la escena: cuando la imagen ya muestra una “silla roja sobre un suelo blanco”, repetir la descripción suele aumentar la deriva en lugar de la fidelidad. Si el resultado se aleja de la imagen de origen, acorte primero el prompt antes de considerar cambiar la imagen.
No asuma que existen parámetros no documentados. Si el control que desea no está en el esquema, consígalo mediante el prompt o la preparación de la imagen.
Gestionar el ciclo de vida de tareas asíncronas
Las tareas de imagen a video no son síncronas. El patrón es enviar, sondear y recuperar, y una integración de producción debe implementar explícitamente los tres pasos.
1. Enviar y persistir
Envíe la solicitud y almacene inmediatamente el ID de tarea devuelto, preferiblemente junto con su propio ID de correlación, un hash de la carga útil de la solicitud y una marca de tiempo. Si el proceso muere entre el envío y el almacenamiento, habrá pagado por una tarea que no puede recuperar.
2. Sondear con retroceso exponencial
Use el ID almacenado para sondear el endpoint de estado de la tarea. La renderización de video tarda considerablemente más que la generación de imágenes, por lo que:
- Empiece con un intervalo moderado (unos segundos) y auméntelo a medida que crece el tiempo de la tarea, en lugar de saturar el endpoint a una tasa fija.
- Limite el tiempo total de espera a un máximo adecuado para la tarea, y luego trate la tarea como agotada y decida si desea reintentarla.
- Trate los estados terminales como terminales: una vez que la tarea informa éxito o fallo, deje de sondear.
import time
def wait_for_job(poll_fn, job_id, max_wait=600):
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
job = poll_fn(job_id)
if job["status"] in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
3. Recuperar y almacenar la salida
Tras el éxito, el objeto de tarea contiene la ubicación del resultado. Descargue el video de inmediato y cópielo en su propio almacenamiento: la URL de salida debe considerarse un recurso temporal, no su biblioteca permanente de activos. Registre el ID de tarea junto al archivo almacenado para que el personal de soporte pueda rastrear cualquier fragmento hasta su solicitud.
Para los reintentos, vuelva a sondear solo las tareas cuyo ID ya haya almacenado; nunca vuelva a enviar a ciegas, ya que eso genera renderizaciones duplicadas y facturación duplicada.
Solución de problemas comunes
Fallos de autenticación (401 / 403)
Compruebe primero la cabecera Authorization: la palabra Bearer, un espacio, luego la clave, sin un salto de línea final arrastrado al copiar la clave. Confirme que la clave está activa y pertenece a la cuenta que espera. Si curl funciona pero Python no, imprima la longitud de la cabecera: una variable de entorno vacía produce un token que parece válido pero es inútil.
Cargas útiles de imagen mal formadas o no compatibles (400 / 422)
El fallo no relacionado con la autenticación más común. Compruebe en orden:
- La URL de la imagen se resuelve correctamente y no redirige a una página de inicio de sesión HTML.
- El formato es JPEG o PNG, no WebP, HEIC ni una miniatura de PDF.
- El tamaño tras la codificación o la descarga está dentro de los límites documentados.
- La carga útil base64 no tiene prefijo
data:ni espacios en blanco por saltos de línea. - La imagen no está dañada: descárguela y ábrala usted mismo antes de culpar a la API.
Parámetros desconocidos o no válidos
Un nombre de campo mal escrito, o un parámetro que el endpoint no expone, suele devolver un error de validación que identifica el campo. Elimine los parámetros especulativos y reconstruya a partir del mínimo requerido documentado.
Límites de tasa (429)
Retroceso exponencial y respete cualquier indicación de reintento en la respuesta. No reintente en un bucle ajustado; eso agrava el límite. Si lo encuentra con frecuencia, envíe en lote mediante una cola en lugar de hacerlo en línea desde la solicitud del usuario.
Tiempos de espera de tareas y sondeos bloqueados
Si una tarea nunca alcanza un estado terminal dentro de su presupuesto, registre el ID de tarea y el historial de estados y deje de sondear. Los tiempos de espera persistentes suelen indicar que la imagen era demasiado grande o anómala en el momento del envío, así que revise de nuevo la sección de preparación de imágenes. No vuelva a enviar automáticamente sin un límite de intentos.
Lista de verificación de producción antes del lanzamiento
Antes de que el endpoint se acerque al tráfico real, verifique cada uno de los siguientes puntos:
- Tiempos de espera en todas partes. El envío usa un tiempo de espera corto, el sondeo establece un límite total de espera y los intentos de reintento tienen un límite estricto. Sin bucles
while Truesin límite. - Reintentos con retroceso exponencial. Reintente las respuestas 429 y los 5xx transitorios; nunca reintente errores de validación, ya que fallarán de la misma manera.
- ID de tarea en los registros. Registre el ID de tarea, su ID de correlación y el estado final de cada solicitud. Es el artefacto de depuración más útil que puede conservar.
- Salida en su propio almacenamiento. Copie el video terminado desde la URL devuelta al almacenamiento persistente y conserve la referencia de la imagen de origen para la reproducibilidad.
- Validación de imágenes en el borde. Rechace formatos incorrectos y cargas demasiado grandes antes de que lleguen a la API, de modo que los usuarios reciban un error claro de inmediato en lugar de un fallo asíncrono minutos después.
- Conciencia de costes. La generación se factura por cada salida de video renderizado, así que haga un seguimiento del volumen de tareas y la duración por usuario o función. Consulte el panel de precios actual en lugar de codificar suposiciones en el código o la documentación.
- Prompt canario. Mantenga un conjunto de imágenes y prompts que se sabe que funcionan bien en su suite de pruebas y ejecútelo tras cualquier cambio de integración para confirmar que el contrato de la solicitud sigue vigente.
Una vez que el ciclo de vida asíncrono se gestiona correctamente (enviar, persistir, sondear, almacenar), el endpoint es sencillo. Obtenga el esquema exacto en la página del modelo y luego implemente el patrón de envío y sondeo descrito anteriormente.
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