Tutorial
Cómo llamar a wan2.7-video de texto a vídeo mediante la API de HiAPI: curl y Python
En esta página
Qué vas a construir en este tutorial
Al terminar esta guía tendrás una pequeña canalización funcional: enviarás una tarea de texto a vídeo a wan2.7-video/text-to-video mediante la API de HiAPI —primero una vez con curl y luego otra vez con Python— y después esperarás a que el vídeo se genere.
Las dos llamadas son deliberadamente equivalentes. La versión con curl es la implementación de referencia, que puedes pegar en la terminal para confirmar que las credenciales y el cuerpo de la solicitud son correctos. La versión en Python encapsula la misma solicitud en una función, fácil de integrar en un script o servicio, e incluye sondeo, manejo de errores y valores predeterminados razonables.
Como la generación de vídeo es mucho más lenta que una finalización de chat, todo el flujo es asíncrono: primero se envía la tarea, se obtiene un identificador y después se consulta repetidamente hasta que la tarea informa de un estado terminal. El artículo se organiza en torno a este ciclo de vida, por lo que si más adelante pasas a imagen a vídeo u otros modelos de vídeo de la misma familia de endpoints, la estructura general seguirá siendo aplicable.
Antes de enviar la primera solicitud
Para que la primera llamada funcione hay que cumplir tres condiciones.
Credenciales
Necesitas una clave de API de HiAPI, que se envía como bearer token en la cabecera Authorization. Guárdala en una variable de entorno en lugar de escribirla en el código fuente:
export HIAPI_API_KEY="your-key-here"
Identificador de modelo conocido
El identificador de modelo es una cadena exacta. En este tutorial el valor es wan2.7-video/text-to-video, incluido el sufijo de tarea. Variantes aproximadas como wan2.7-video o wan2.7/text-to-video serán rechazadas, así que copia el identificador desde la lista de modelos en lugar de escribirlo de memoria.
Un prompt que puedas evaluar
Iterar a ciegas sobre la generación de vídeo sale caro. Escribe de antemano un prompt concreto (sujeto, acción, comportamiento de cámara, iluminación, estilo), de modo que cuando llegue el resultado puedas juzgar si lo que hay que ajustar son esos ajustes y no la redacción.
También necesitarás un cliente HTTP y una forma de leer JSON. En el lado del shell, curl junto con jq; en el lado del script, Python junto con requests.
Anatomía del cuerpo de la solicitud
Una solicitud de texto a vídeo es un objeto JSON cuyos campos se agrupan en tres bloques.
Identidad
model: el identificador exacto del modelo, es decir,wan2.7-video/text-to-video.
Contenido
prompt: el texto que describe el vídeo que quieres. Es el campo que más influye; especifica movimiento, composición y estilo en lugar de acumular adjetivos.negative_prompt: opcional. Describe lo que no debe aparecer. Resulta útil para suprimir defectos habituales, pero no sustituye a un buen prompt.
Ajustes de generación
duration: la duración del clip de salida.resolution: el nivel de tamaño/resolución de la salida.seed: opcional. Fíjala cuando quieras comparar dos prompts o dos cambios de ajustes partiendo de un punto de partida estable.
Un cuerpo mínimo solo necesita model y prompt; la plataforma aplicará valores predeterminados al resto de campos. Pero un valor predeterminado no es una elección tuya: consulta la sección de duración y resolución más abajo para saber por qué conviene establecerlos explícitamente en producción.
Mantén el cuerpo plano y poco profundo. Anidar solo los campos que realmente pertenecen a un subobjeto hace que la solicitud sea más legible y que los errores de esquema se detecten con más facilidad.
Enviar la tarea con curl
A continuación tienes un ejemplo completo de envío. El endpoint recibe JSON y devuelve un identificador de tarea en lugar del vídeo en sí.
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "Plano de seguimiento que avanza lentamente por un callejón de neón mojado por la lluvia de noche, charcos que reflejan la luz en el suelo, profundidad de campo reducida, etalonaje cinematográfico",
"duration": 5,
"resolution": "720p"
}'
Un envío correcto devuelve un objeto con el identificador de la tarea o del trabajo y el estado. La estructura se parece a esto:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
Hay dos cosas que conviene observar. Primero, status no es succeeded: en este momento todavía no se ha renderizado nada. Segundo, la respuesta no contiene ninguna URL de vídeo. Esa URL solo aparece cuando la tarea alcanza un estado terminal.
Si quieres conservar el identificador en la sesión del shell para usarlo en el paso de sondeo:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
Mover el cuerpo de la solicitud a payload.json mantiene el comando corto y facilita ajustar el prompt entre ejecuciones.
Enviar la tarea con Python
La versión en Python es la misma solicitud, solo que más cómoda de usar. Lo que en curl es una cabecera o una clave JSON, aquí se convierte en un argumento de palabra clave.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"Plano de seguimiento que avanza lentamente por un callejón de neón mojado por la lluvia de noche, "
"charcos que reflejan la luz en el suelo, profundidad de campo reducida, etalonaje cinematográfico"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
La correspondencia con la versión del shell es uno a uno:
-H "Authorization: ..."→ el diccionarioHEADERS.-d '<json>'→json=payload. Pasar un diccionario en lugar de una cadena significa querequestsse encarga de la serialización, así que no se enviará por error JSON mal formado.- El
.idextraído conjq→job["id"].
Hay dos hábitos propios de Python que merece la pena adoptar desde ya. Establece siempre un timeout en la llamada de envío: la solicitud es pequeña y debería devolverse rápido, así que una espera larga indica un problema de conexión, no de renderizado. Y llama a raise_for_status() antes de leer el cuerpo de la respuesta, de modo que un fallo en la capa HTTP produzca un traceback claro en lugar de un confuso KeyError en job["id"].
Gestionar tareas asíncronas y el sondeo
El sondeo es el punto en el que la mayoría de las integraciones se vuelven robustas o frágiles. Las tareas tienen un ciclo de vida —normalmente en cola, procesando y después un estado terminal de éxito o fallo— y tu bucle debe gestionar esos tres casos.
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
Hay varias decisiones de diseño en este bucle cuya importancia es mayor de lo que parece:
Comprobar explícitamente los estados terminales. Tratar cualquier estado distinto de succeeded como «sigue esperando» hace que una tarea fallida consuma silenciosamente todo tu presupuesto de sondeos. Haz coincidir los estados de fallo y lanza una excepción.
Elegir el intervalo de sondeo con criterio. El renderizado de vídeo tarda entre decenas de segundos y varios minutos. Sondear cada 200 ms solo añade carga y no te aporta información nueva. Empieza con unos 5 segundos; si las tareas suelen tardar mucho, aumenta el intervalo en lugar de aumentar el número de intentos.
Poner siempre un límite al bucle. Un límite de max_attempts convierte un bloqueo indefinido en un TimeoutError diagnosticable. Registra también el ID de la tarea: es el valor que necesitarás para investigar el problema.
Respetar los límites de tasa. Si envías tareas en lote, no lances todas las solicitudes de sondeo a la vez. Usar un sondeador compartido que se ejecute a intervalos fijos, o un limitador de cliente sencillo, te mantendrá dentro de los límites.
Cuando tiene éxito, la respuesta contiene la ubicación del recurso completado. Descárgalo de inmediato; no uses el registro de la tarea como almacenamiento permanente.
Elegir duración y resolución
Estos dos ajustes influyen en la salida más que cualquier otro parámetro, y ambos afectan a la duración de la tarea y al coste. El consumo facturable se calcula en segundos de salida, y la resolución determina el trabajo por segundo, así que considera ambos como decisiones deliberadas para cada caso de uso, no como campos que puedan quedarse en su valor predeterminado.
Duración
Los clips más largos dejan espacio para que la acción se desarrolle, pero cada segundo adicional implica más renderizado y mayor coste, y las generaciones largas tienden más a sufrir problemas de coherencia. Consejos prácticos:
- Corto (unos segundos): bucles para redes sociales, imágenes principales de producto, B-roll. Es lo más barato de iterar y lo más fácil de evaluar.
- Medio: momentos narrativos, planos de establecimiento.
- Largo: úsalo solo cuando la historia realmente lo necesite. Si necesitas un vídeo largo, considera generar varios clips cortos y montarlos después; suele salir más barato que un único renderizado largo y te da más control.
Mientras iteres sobre el prompt, genera el clip más corto que permita el modelo. Evalúa composición y movimiento con esa duración y alarga cuando estés satisfecho.
Resolución
Una resolución más alta significa más píxeles por fotograma, tiempos de renderizado más largos y mayor coste. Pero en pantallas pequeñas importa menos de lo que crees. Un máster a 1080p sirve para entregar al cliente; un borrador a 720p (o menos) sirve para juzgar si el prompt funciona.
El patrón eficiente es un flujo de trabajo en dos fases: fija el prompt y la duración a baja resolución y después vuelve a ejecutar la tarea final a la resolución de entrega. No iteres con los ajustes más altos: gastarás la mayor parte del presupuesto en material que vas a descartar.
Diagnosticar errores habituales
La mayoría de los fallos provienen de cómo se organiza la solicitud, no del modelo en sí. Antes de sacar conclusiones sobre las capacidades del modelo, revisa en orden los siguientes tipos de problemas.
401 / 403: problemas de credenciales
Comprueba que la clave está definida en el entorno que realmente ve el proceso (una clave exportada en un shell no es visible para un servicio de systemd), que la cabecera es Authorization: Bearer <key> y que la variable no tiene espacios en blanco al final. Al depurar, imprime solo los primeros caracteres de la clave; nunca la clave completa.
404: ruta o modelo incorrectos
La ruta del endpoint y el identificador del modelo son dos cosas distintas, y ambas deben ser exactas. Confirma la URL a la que haces POST y confirma que wan2.7-video/text-to-video se copió carácter por carácter desde la lista de modelos. Una clave válida con una cadena de modelo incorrecta seguirá devolviendo un error similar a not-found.
400: cuerpo de solicitud mal formado
Es la categoría más frecuente. Las causas habituales incluyen enviar campos numéricos como duration como cadena "5", enviar el prompt como lista en lugar de cadena, o que el cuerpo se haya codificado doble por accidente. El triaje más rápido es reenviar exactamente el mismo comando curl: si la llamada del shell funciona y la de Python falla, el problema está en cómo el script construye el diccionario, no en la solicitud.
422 / errores de validación
La sintaxis es válida pero la semántica no: duración fuera del rango admitido, un nivel de resolución desconocido o falta un campo obligatorio. Lee el mensaje de error; normalmente señala el campo problemático.
La tarea falla después del envío
La llamada de envío tuvo éxito, pero el renderizado no. Puede ser un rechazo por políticas de contenido o un fallo temporal de renderizado. Registra el ID de la tarea y la carga de error; si es un problema temporal, reenviar la misma carga es un primer paso razonable. Si el mismo prompt falla una y otra vez, cambia la redacción del prompt o los ajustes de generación en lugar de reintentar la misma solicitud repetidamente.
El sondeo no termina nunca
Si una tarea se queda en procesando mucho más tiempo que otras similares, deja de sondear, registra el ID de la tarea y trátala como una tarea fallida. Los casos de cola larga son lo bastante raros como para que un tiempo de espera acotado con un mensaje de error claro sea mejor que un bucle abierto.
Cada vez que aparezca un problema nuevo, empieza por la implementación de referencia con curl: elimina tu código de la ecuación y así aísla si el problema está en la solicitud o en el cliente.
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