Tutorial
Cómo llamar a la API de texto a video veo-3.1: ejemplos con curl y Python
Guía práctica de integración para desarrolladores
En esta página
Qué puede hacer veo-3.1/text-to-video por ti
veo-3.1/text-to-video es un modelo de generación de texto a video que se ofrece a través de la API unificada de HiAPI. Envías un prompt de texto, eliges algunas opciones de salida y recibes el video generado. Se encuentra en HiAPI junto a otros endpoints de generación, así que si ya usas capacidades de imagen o chat en la plataforma, este método de integración te resultará familiar: una solicitud HTTP autenticada devuelve una tarea y tú consultas su estado hasta que finaliza.
Este endpoint es la opción adecuada cuando tienes una descripción textual de una escena y quieres generar un video corto sin gestionar la infraestructura por tu cuenta. No necesitas encargarte de la asignación de GPU, los pesos del modelo ni las colas. El precio a pagar es que la generación es asíncrona: envías la tarea y vuelves más tarde a consultar el resultado. Esto es lo habitual en video, ya que el renderizado requiere más tiempo que un único ciclo de solicitud/respuesta.
Usa texto a video cuando la entrada principal sea un prompt. Si más adelante necesitas generación condicionada por imagen o por video, consulta los endpoints correspondientes en el catálogo de modelos. La estructura de solicitud que se usa aquí (autenticación, envío de tarea, sondeo) es el mismo patrón que reutilizarás en los endpoints multimedia de HiAPI, así que aprenderlo una vez te servirá a largo plazo. Puedes encontrar los detalles completos del modelo en la página del modelo veo-3.1/text-to-video.
Endpoint, autenticación y estructura de la solicitud
Todas las solicitudes a HiAPI usan HTTPS y un token bearer. Guarda tu clave de API en una variable de entorno en lugar de codificarla directamente, y envíala en la cabecera Authorization:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Una solicitud de texto a video es un objeto JSON que contiene el campo model y un objeto input. El objeto input contiene el prompt y cualquier control de salida. El cuerpo mínimo de la solicitud es el siguiente:
{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Un callejón de neón empapado por la lluvia de noche, con un travelling de acercamiento lento"
}
}
Lo que se devuelve no es el video final, sino un sobre de tarea. Normalmente contiene un identificador de tarea, un campo de estado y una marca de tiempo. Su estructura es aproximadamente así:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-01-01T00:00:00Z"
}
Consulta la respuesta real para conocer los nombres exactos de los campos, pero la estructura es consistente: necesitas id para hacer el sondeo y status te indica si la tarea está en cola, en ejecución o completada. No asumas que la tarea ha terminado porque la llamada de envío devolvió un 200; eso solo significa que la tarea fue aceptada.
Elegir parámetros: audio nativo y niveles de resolución
Además del prompt, los parámetros más importantes para texto a video son si se genera audio nativo y el nivel de resolución objetivo. Ambos afectan al tiempo de generación y a la naturaleza de la salida, así que elígelos de forma consciente en lugar de usar los valores predeterminados sin pensar.
Audio nativo
Algunos modelos de video pueden generar una pista de audio además de la imagen. Si el endpoint ofrece un interruptor de audio nativo, activarlo significa que el clip generado incluye sonido sincronizado. Esto es útil en escenas donde el audio forma parte de la experiencia: ruido ambiente, música o efectos de sonido que acompañan a la acción. Si planeas añadir tu propia banda sonora o narración en posproducción, desactívalo para que la salida se centre en la imagen. La generación de audio también aumenta el tiempo de procesamiento, así que actívala solo si realmente la necesitas.
Niveles de resolución
Los niveles de resolución te permiten elegir entre fidelidad de imagen y coste o latencia. Los niveles más altos producen una salida más nítida, pero tardan más y consumen más recursos. Elige el nivel más bajo que cumpla tu objetivo de entrega: un nivel de borrador para iterar y revisar, y un nivel más alto para el renderizado final. Si vas a generar muchos candidatos para un mismo prompt, explora con un nivel más bajo y luego regenera el ganador a calidad completa. La facturación sigue a la salida que generas, así que elegir el nivel de forma consciente es la principal palanca que controlas.
Si no estás seguro de qué valores acepta actualmente el endpoint, envía primero una solicitud solo con el prompt y luego revisa la respuesta o el mensaje de error. HiAPI devuelve errores de validación estructurados que enumeran los campos aceptados, así que puedes ajustar en función de ellos sin adivinar.
Solicitud curl ejecutable
Este comando curl envía una tarea de texto a video. Establece el tipo de contenido JSON, pasa el token bearer desde una variable de entorno y envía un cuerpo de solicitud con model e input.
curl -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Un callejón de neón empapado por la lluvia de noche, con un travelling de acercamiento lento",
"duration": 5,
"resolution": "720p"
}
}'
Una llamada correcta devuelve un objeto JSON con el id y el status de la tarea. Anota ese id: lo necesitarás para el sondeo. Si estás escribiendo un script, puedes extraer el id procesando la salida con un procesador JSON:
JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Un callejón de neón empapado por la lluvia de noche, con un travelling de acercamiento lento"}}' \
| jq -r '.id')
echo "$JOB_ID"
Ajusta la ruta del endpoint, los nombres de los parámetros y cualquier campo opcional según lo que espere la API real. Este patrón —enviar un cuerpo JSON con POST y leer el id de la respuesta— es la base de todos los ejemplos siguientes.
Enviar la misma solicitud con Python
La versión en Python hace lo mismo usando la biblioteca estándar requests. Lee la clave del entorno, construye el payload y envíalo.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Un callejón de neón empapado por la lluvia de noche, con un travelling de acercamiento lento",
},
}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"Tarea enviada: {job_id} (estado: {job.get('status')})")
Hay dos puntos que merece la pena destacar. Primero, response.raise_for_status() convierte los errores HTTP en excepciones, de modo que un fallo sea visible de inmediato en lugar de dejar que un payload defectuoso pase desapercibido. Segundo, timeout=60 evita que una conexión colgada bloquee tu script. El envío en sí es rápido; el video real se renderiza de forma asíncrona, así que no esperarás el archivo aquí. A continuación, usarás job_id para consultar el estado de finalización.
Sondear la tarea asíncrona hasta que el video esté listo
Tras el envío, consulta el endpoint de la tarea hasta que el estado indique finalización o fallo. Un bucle simple con una pausa breve es suficiente para empezar.
import time
while True:
res = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=headers,
timeout=30,
)
res.raise_for_status()
state = res.json().get("status")
print(f"Estado: {state}")
if state == "succeeded":
video_url = res.json().get("output", {}).get("url")
print(f"Video listo: {video_url}")
break
if state == "failed":
raise RuntimeError(f"La tarea falló: {res.json()}")
time.sleep(5)
Algunas mejoras prácticas: empieza con un intervalo corto y luego aplica un retroceso progresivo para reducir solicitudes innecesarias; añade un número máximo de intentos o una fecha límite para evitar bucles infinitos en tareas atascadas; y trata con cautela cualquier estado inesperado en lugar de asumir que significa «sigue esperando». Los valores de estado habituales son queued, running, succeeded y failed. Cuando la tarea tiene éxito, la respuesta suele incluir una URL de salida; descarga y guarda el archivo cuanto antes, porque las URL firmadas pueden caducar.
Haz que el sondeo sea idempotente y registra el id de la tarea en cada cambio de estado. Si tu proceso se reinicia, puedes reanudar por id sin volver a enviar la tarea. En producción, si la plataforma ofrece webhooks, considera usarlos y deja el sondeo como respaldo.
Diagnosticar errores comunes
La mayoría de los fallos se agrupan en unas pocas categorías. Revisa la siguiente lista en orden en lugar de reintentar a ciegas.
Fallos de autenticación (401/403)
Comprueba que la cabecera Authorization existe y tiene el formato correcto Bearer <key>, y que la variable de entorno está realmente definida en el shell o proceso que realiza la solicitud. Una trampa habitual es ejecutar el script en un entorno donde la clave existe en un shell pero no en otro.
Errores de validación (400/422)
Estos errores devuelven detalles estructurados sobre qué campo es incorrecto. Causas habituales: falta el prompt, valores no admitidos de resolution o duration, o un nivel de anidamiento incorrecto de los parámetros. Toma el mensaje de error al pie de la letra: normalmente señala el campo problemático. Envía primero el payload mínimo y luego añade un parámetro cada vez.
Límite de velocidad (429)
Estás enviando solicitudes demasiado rápido. Implementa retroceso exponencial y un límite de reintentos. Si vas a lanzar muchas tareas, escalona los envíos y lleva un seguimiento de las tareas en curso.
Tiempos de espera y errores de red
Un tiempo de espera del cliente al enviar rara vez es culpa de la tarea en sí: la tarea se ejecuta en el servidor. Usa tiempos de espera razonables tanto en el envío como en el sondeo, y reintenta las solicitudes GET idempotentes. Nunca reintentes un POST a ciegas sin comprobar antes si la tarea original ya se creó.
La tarea nunca finaliza
Si una tarea permanece en queued o running mucho más de lo esperado, revisa el código de estado y el mensaje en lugar de volver a enviarla. Los prompts largos o los niveles de resolución más altos tardan más; es normal. Si la tarea informa de failed, registra el cuerpo completo de la respuesta: el mensaje de error suele indicar la causa.
Si tienes dudas, reproduce el problema con la solicitud más pequeña posible y revisa cada respuesta. Esto es mucho mejor que cambiar varios parámetros a la vez y adivinar cuál importa. Para detalles específicos del endpoint, consulta la página del modelo.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Casos prácticos de aplicación de kling-image-4.0: 5 usos de alto valor y puntos clave de integración
-
Tutorial
Cómo llamar a gemini-omni-1.1-flash mediante la API de HiAPI: guía con curl y Python
-
Tutorial
Cómo usar qwen-image-2.0-pro a través de la API de HiAPI: curl, Python y una solicitud que funciona
Ejercicio práctico de integración para desarrolladores: primera llamada exitosa, anatomía de la estructura de la solicitud y diagnóstico de fallos