Tutorial
Llamar a veo-3.1/image-to-video a través de la API de HiAPI: tutorial con curl y Python
En esta página
Qué espera el endpoint veo-3.1 de imagen a vídeo
Antes de escribir la primera línea de código, conviene tener claro qué tipo de llamada es esta. veo-3.1/image-to-video no devuelve el vídeo directamente en la misma respuesta HTTP en la que envías el prompt. Es un endpoint de tareas asíncronas: describes el vídeo que quieres, la plataforma acepta la tarea y después vuelves a consultar el resultado.
Conceptualmente, una solicitud consta de dos partes bien diferenciadas:
- Imagen del primer fotograma. Es el fotograma estático desde el que arranca la generación del vídeo. Ancla la composición, el sujeto y la apariencia del instante inicial. Todo lo que sigue lo genera el modelo a partir de ese punto de partida.
- Opciones de generación. Son los parámetros que controlan cómo se genera el vídeo, por ejemplo, si se genera audio, la resolución de salida y la duración del clip.
Esta separación importa por dos razones. Primero, facilita el razonamiento ante fallos: un problema de imagen se ve distinto de un problema de parámetros, y conviene poder distinguirlos. Segundo, implica que tu código también debe organizarse del mismo modo: una parte se encarga de preparar la imagen y otra de construir el conjunto de opciones.
Quien llama debe proporcionar al menos: una imagen de primer fotograma válida y las decisiones sobre audio, resolución y duración. Todo lo demás (enviar la tarea, seguir su estado y devolver el vídeo final) lo gestiona el ciclo de vida de tareas de la plataforma. Tu integración solo tiene que hacer tres cosas: enviar una solicitud bien formada, recordar el identificador de tarea devuelto y consultar hasta que la tarea llegue a un estado terminal.
Un consejo práctico antes de continuar: como la llamada es asíncrona, tu código no puede asumir que el vídeo estará disponible en cuanto envíes la tarea. Diseña el flujo en torno a ello desde el principio y el resto del tutorial te resultará natural.
Un modelo mental de dos partes
Mantén este esquema en mente mientras lees las siguientes secciones:
- Entrada → imagen de primer fotograma preparada y validada.
- Opciones → audio, resolución, duración.
- Tarea → enviar, obtener identificador, consultar, recuperar.
Cada sección siguiente corresponde a uno de estos bloques.
Preparar la imagen del primer fotograma
La imagen del primer fotograma es la entrada más importante de una llamada de imagen a vídeo, así que conviene darle un paso propio en la tubería en lugar de esconderla dentro del constructor de solicitudes. La llamada a la API debe poder referenciar esa imagen, lo que significa que debe estar en un formato que la plataforma acepte y pueda leer.
Qué comprobar antes de enviarla
- La imagen se abre de verdad. Una descarga truncada o un archivo corrupto es la causa más común de fallos confusos en pasos posteriores. Antes de enviar nada, verifica que se decodifica correctamente.
- El formato es aceptado por la plataforma. Si tu origen es una captura de pantalla, una foto de móvil o una exportación de una herramienta de diseño, normalízala a un formato ampliamente compatible antes de subirla. Convertir una vez por adelantado te ahorra depuraciones posteriores.
- El tamaño es razonable. Una imagen diminuta o extremadamente estirada ofrece muy poco material al modelo. Si el origen es demasiado pequeño, considera ampliarla o elegir un fotograma mejor.
- La composición es un buen punto de partida. Como es el primer fotograma, el movimiento generado parte de ahí. Elige un fotograma en el que el sujeto se vea claramente y en el que te gustaría ver esa composición al inicio del clip.
Mantenerla separada de las opciones
Organiza el código de modo que la preparación de la imagen devuelva una referencia que puedas pasar al constructor de solicitudes, en lugar de mezclar el procesamiento de la imagen con el ensamblaje de parámetros. En concreto:
# Estructura seudocódigo, no un cliente completo
def prepare_first_frame(path):
image = load_and_validate(path) # decodificar, comprobar formato, comprobar tamaño
ref = upload_or_encode(image) # generar algo que la llamada a la API pueda referenciar
return ref
def build_request(first_frame_ref, options):
return {
"first_frame": first_frame_ref,
# audio / resolución / duración van aquí
}
Esta separación compensa a la hora de depurar. Si una tarea falla, puedes volver a ejecutar prepare_first_frame por separado para confirmar que el lado de la imagen está bien antes de tocar cualquier parámetro de generación.
Validar pronto y fallar de forma ruidosa
Realiza la validación de tu lado y lanza errores claros cuando falle. Una imagen mal formada o ilegible nunca debería llegar a la red: capturarla en local convierte un fallo difuso de tarea asíncrona en una excepción precisa e inmediata escrita por ti.
Configurar las opciones de generación: audio, resolución y duración
Una vez procesada la imagen, las decisiones restantes son las opciones de generación. Cambian la naturaleza de la salida, así que trátalas como parámetros nombrados explícitos, no como valores mágicos enterrados en el cuerpo de la solicitud.
Audio
La opción de audio controla si el vídeo generado incluye una pista de sonido. Es tanto una decisión técnica como una decisión de producto:
- Si el vídeo se insertará en silencio (un bucle de fondo, un visual principal en reproducción automática), normalmente no hace falta audio, y omitirlo simplifica el procesamiento posterior.
- Si el clip se presentará de forma autónoma con sonido (contenido breve para redes sociales, una demostración), activa el audio para obtener el material completo en una sola llamada.
Decide de forma intencionada según el caso de uso, no adoptes el valor predeterminado a ciegas; afecta tanto a la salida como a cómo tu tubería posterior procesará el archivo.
Resolución
La resolución determina las dimensiones en píxeles del vídeo final. Elígela según dónde se mostrará el vídeo y cuánto detalle necesita el contenido, no simplemente elijas el valor máximo disponible. Un clip renderizado para un reproductor integrado pequeño no se beneficia de generarse a un tamaño muy superior al que puede mostrar el panel de visualización. Si la plataforma publica un conjunto de valores admitidos, elige uno explícitamente de ese conjunto y valídalo en el cliente para que los valores no admitidos fallen rápido.
Duración
La duración fija la longitud del clip generado. Interactúa con tu planificación de contenido: un plano que necesita establecer primero la escena y luego mostrar movimiento requiere más tiempo que un único gesto. Ten en cuenta que es probablemente uno de los parámetros que más se factura; la facturación de la plataforma se describe en términos de salida generada, así que vigila la longitud del clip cuando hagas solicitudes por lotes.
Ensamblar las opciones en un objeto
Reúne las tres en una única estructura de opciones, para tener un solo lugar donde mirar y un solo lugar que modificar:
options = {
"audio": True, # generar pista de audio
"resolution": "...", # uno de los valores admitidos
"duration": 8, # segundos de vídeo generado
}
Usa los valores que tu cuenta y la documentación actual del endpoint indiquen como admitidos: léelos de la documentación en lugar de codificar suposiciones y valídalos al construir la solicitud, para que un valor incorrecto nunca se convierta en una tarea fallida.
Enviar la tarea con curl
Ahora combina ambas partes y envía. Empieza desde la línea de comandos, porque curl hace visible la forma de la solicitud y te da una manera rápida de probar cambios antes de escribir código.
La solicitud
La solicitud de envío tiene esta estructura: sustituye los valores de marcador de posición por tus credenciales, la referencia de imagen y los valores de las opciones:
curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_frame": "<referencia de imagen del paso de subida>",
"audio": true,
"resolution": "<valor admitido>",
"duration": 8
}'
Hay varias convenciones que merece la pena adoptar:
- Guarda la clave en una variable de entorno (
$HIAPI_API_KEY) en lugar de pegarla en el comando. Este hábito se traslada directamente a tu código Python y mantiene la clave fuera del historial del shell. - Envía JSON con una cabecera
Content-Typeexplícita. - En el cuerpo de la solicitud, separa la referencia de imagen de las opciones numéricas y booleanas, en línea con el modelo de dos partes de la primera sección.
Leer la respuesta
Como es un endpoint asíncrono, una respuesta correcta no es el vídeo. Es solo la confirmación de que la tarea se ha aceptado y lleva la información necesaria para seguirla; lo más importante es el identificador de tarea, normalmente junto con un campo de estado que indica que la tarea está en cola o en ejecución.
Léela en dos pasos. Primero, confirma que el estado HTTP indica aceptación y no un error de cliente. Después, analiza el cuerpo de la respuesta y extrae el identificador de tarea:
curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | tee submit.json
Al escribir la respuesta en submit.json, tendrás algo que inspeccionar y que pasar al paso de consulta. Si el envío falla, el cuerpo de la respuesta de error es tu primera y mejor pista: comprueba si apunta a la referencia de imagen o a alguna opción, corrige solo esa mitad y vuelve a enviar.
Consultar la tarea asíncrona hasta que el vídeo esté listo
Una vez que tienes el identificador de tarea, el flujo de trabajo se convierte en un bucle: preguntas a la plataforma por el estado de la tarea y paras cuando la tarea alcanza un estado terminal.
Ciclo de vida
Una tarea de imagen a vídeo pasa por un número reducido de estados. Se acepta y se pone en cola, se procesa y finalmente o bien tiene éxito y produce el vídeo, o bien falla y devuelve un error. Tu código de consulta solo tiene que distinguir tres cosas:
- Sigue procesándose: continúa esperando.
- Éxito: lee la ubicación de salida y descarga o almacena el vídeo.
- Fallo: detente y lanza un error.
Consultar de forma responsable
Dos hábitos hacen que la consulta sea más robusta:
- Espera entre comprobaciones. Un bucle apretado que martillea el endpoint de estado desperdicia solicitudes sin aportar nada; la generación requiere tiempo real. Usa un intervalo fijo o un retroceso moderado.
- Establece una fecha límite. Nunca consultes indefinidamente. Elige un número máximo de intentos o un tiempo máximo y trata superarlo como un fallo que puedas informar con claridad.
# Esquema del bucle de consulta
for i in $(seq 1 60); do
status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
-H "Authorization: Bearer $HIAPI_API_KEY")
echo "$status"
# salir cuando el campo de estado indique éxito o fallo
sleep 5
done
Trata las cadenas de estado exactas y la ruta del endpoint como algo que debes confirmar con la documentación actual de la API, no como suposiciones fijadas en el script.
Cuando tiene éxito
Cuando la tarea informa de éxito, la respuesta incluye la ubicación del vídeo final. Descárgalo a tiempo y guárdalo en una ubicación persistente: el resultado de una tarea en cualquier plataforma asíncrona debe tratarse como algo que hay que recuperar ya, no como algo que se cargará de forma perezosa mucho después. Registra el identificador de tarea junto con el archivo almacenado, para que cualquier salida pueda rastrearse hasta la solicitud que la produjo.
La misma solicitud en Python
La versión en Python no debería ser una segunda implementación, sino la misma solicitud, expresada una vez y reutilizada. El objetivo es una única función que envía y consulta, construida a partir de la misma referencia de imagen que validaste antes y el mismo objeto de opciones.
Un cuerpo de solicitud, un cliente
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
})
def build_body(first_frame_ref, options):
return {"first_frame": first_frame_ref, **options}
def submit(body):
r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
r.raise_for_status()
data = r.json()
return data["job_id"]
def poll(job_id, interval=5, max_attempts=60):
for _ in range(max_attempts):
r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
r.raise_for_status()
data = r.json()
state = data.get("status")
if state in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"La tarea {job_id} no terminó a tiempo")
def image_to_video(first_frame_ref, options):
job_id = submit(build_body(first_frame_ref, options))
result = poll(job_id)
if result["status"] == "failed":
raise RuntimeError(result.get("error", "La tarea falló"))
return result # contiene la ubicación del vídeo final
Por qué tiene esta forma
- Una única
Session. Reutilizar la sesión mantiene la cabecera de autenticación en un solo sitio y reutiliza la conexión entre el envío y cada consulta. - Un único
build_body. La solicitud curl y la solicitud Python son el mismo cuerpo: las mismas claves y los mismos valores. Cuando cambies una opción, la cambias en un solo lugar. - Tiempos de espera y fechas límite explícitos. Ambas llamadas tienen tiempos de espera, y
polllimita el número de intentos, de modo que una tarea estancada nunca bloquea tu proceso. - Los fallos se exponen de forma ruidosa.
raise_for_statusen el envío captura de inmediato los errores a nivel de solicitud; la rama de fallo explícita enimage_to_videocaptura los fallos a nivel de tarea.
Si más adelante necesitas llamar a otros modelos a través de la misma plataforma, esta estructura se generaliza: la sesión, la función auxiliar de envío y la función auxiliar de consulta se mantienen, y solo cambian el endpoint y el constructor del cuerpo de la solicitud.
Diagnosticar llamadas de imagen a vídeo fallidas
Cuando una llamada no produce un vídeo, acota el problema preguntando en qué fase falló. El modelo de solicitud en dos partes te da una lista de comprobación clara.
Fase 1: el envío se rechaza
Si la llamada de envío devuelve un error, no se ha generado nada; eso es bueno, porque el problema está en la solicitud.
- Problema con la referencia de imagen. Es la causa individual más común. Vuelve a ejecutar el paso de preparación de la imagen por separado y confirma que produce una imagen válida, legible y con el formato correcto, así como una referencia aceptada por la API. Comprueba primero las subidas truncadas y los formatos no admitidos.
- Valores de opción no válidos. Una resolución no admitida o una duración fuera de rango se rechazan en el envío. Valida las opciones con los valores admitidos de la documentación antes de enviar.
- Autenticación y cabeceras. Confirma que la clave se envía realmente (
Authorization: Bearer ...) y que el cuerpo se envía como JSON. Al construir solicitudes a mano con curl, un cuerpo vacío o mal formado pasa fácilmente desapercibido.
Fase 2: la tarea se envió pero falló
Si el envío se aceptó pero la consulta termina en fallo, significa que la solicitud estaba bien formada y el problema está en el contenido o en la propia tarea.
- Lee el error de la tarea. La respuesta de fallo explica qué salió mal mejor que cualquier conjetura. Regístrala tal cual.
- Revisa el primer fotograma. Una imagen de origen sin un sujeto claro, recortada en exceso o muy distorsionada ofrece muy poco material al modelo. Cambia a un fotograma más limpio y vuelve a intentarlo.
- Reconsidera las opciones. Una duración muy larga o una combinación inusual de ajustes merece volver a probarse con una configuración más simple para aislar qué parámetro es el problemático.
Fase 3: la consulta nunca termina
Si tu bucle expira en lugar de fallar, trátalo como un problema de infraestructura, no de contenido. Confirma que estás consultando el identificador de tarea correcto, que el intervalo no es demasiado agresivo y que la fecha límite es lo bastante amplia para la duración solicitada. Registra el identificador de tarea al enviarla; sin él, no podrás investigar una tarea atascada.
Un flujo de depuración eficaz
Cuando algo vaya mal, sigue este orden: valida la imagen en local, vuelve a enviar y captura la respuesta sin procesar, comprueba el error de la tarea si aparece, y luego simplifica las opciones y vuelve a intentarlo. Cada paso pone a prueba exactamente la mitad de la solicitud, y por eso separar en el código la imagen de los parámetros de generación compensa justo cuando algo falla.
Con esto ya tienes el ciclo completo: preparar el primer fotograma, configurar audio, resolución y duración, enviar de forma asíncrona y consultar hasta la finalización, todo con la misma solicitud tanto si la ejecutas con curl como con Python.
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