Tutorial
Cómo llamar a seedance-2.5-flash de texto a vídeo mediante la API de HiAPI (curl y Python)
Recorrido práctico de una solicitud funcional para desarrolladores: endpoint, parámetros, gestión de tareas asíncronas y ejemplos ejecutables en curl y Python
En esta página
Qué te ofrece seedance-2.5-flash/text-to-video
seedance-2.5-flash/text-to-video es un endpoint de generación de vídeo a partir de texto en la API de HiAPI. Envías un prompt de texto que describe la escena deseada y el modelo devuelve el vídeo generado. El contrato es así de simple: entra texto, sale vídeo.
Como la generación de vídeo tarda más que un chat completion típico, este endpoint es asíncrono. Una sola llamada no se bloquea esperando a que el vídeo esté listo; en su lugar, crea una tarea de generación y tú obtienes el resultado una vez que la tarea alcanza un estado terminal. Si has integrado antes cualquier API de medios de larga duración, esta forma te resultará familiar: envías, guardas el identificador de la tarea y luego recuperas el resultado.
Por tanto, el trabajo de integración de tu lado se divide en tres cosas: construir una solicitud de envío válida, persistir el ID de la tarea y recuperar de forma fiable el vídeo terminado. Este tutorial recorre estos tres pasos con código ejecutable en curl y Python, y después explica la validación de parámetros, la disyuntiva entre sondeo y callback, y los modos de fallo en los que tropieza la mayoría de las primeras integraciones.
Si estás construyendo un pipeline que convierte prompts en clips de vídeo cortos de forma programática —una herramienta de contenido, un backend de prototipos o un servicio de generación interno— esta guía es para ti. Si necesitas respuestas síncronas, o si buscas generación de imágenes en lugar de vídeo, otro endpoint encaja mejor. Si esto se ajusta a tu caso de uso, sigue leyendo para ver los requisitos previos.
Requisitos previos y obtención de la API Key
Antes de enviar tu primera solicitud, confirma tres cosas.
Cuenta de HiAPI y API Key
Todas las solicitudes a este endpoint se autentican con una API Key vinculada a tu cuenta de HiAPI. Crea la Key en el panel de control de tu cuenta y evita confirmarla en el control de código fuente. Los ejemplos siguientes la leen de una variable de entorno, de modo que puedes pegarla directamente en la terminal o en el script sin editar la clave en línea:
export HIAPI_API_KEY="your_api_key_here"
Un cliente capaz de realizar solicitudes HTTPS
Para la parte de curl necesitas curl, que viene preinstalado en macOS y en la mayoría de las distribuciones de Linux. Para la parte de Python necesitas Python 3 y la librería requests (pip install requests). No hace falta un SDK específico del proveedor: el endpoint es HTTPS normal con un cuerpo JSON, así que sirve cualquier cliente HTTP, desde fetch de Node hasta httpx de Python.
Una forma de almacenar estado entre solicitudes
Como la generación es asíncrona, necesitas algún lugar donde guardar el identificador de tarea que devuelve la llamada de envío: una fila de base de datos, una cola de tareas o un archivo JSON durante las pruebas. Si piensas usar callbacks en lugar de sondeo, también necesitarás un endpoint HTTPS accesible por HiAPI.
Con la Key y un cliente operativo, ya puedes enviar la solicitud.
Enviar la primera solicitud funcional con curl
La llamada de envío es un POST con un cuerpo JSON. La ruta exacta del endpoint y el nombre de la cabecera de autenticación están documentados en la página del modelo; usa esos valores tal cual y no los infieras de otras API. La estructura de la llamada es la siguiente:
curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
}'
Algunas notas sobre cada parte:
- Método y ruta.
POSTcrea una nueva tarea de generación. La ruta identifica el modelo; confírmala en la página del modelo antes de copiarla a tu propia configuración. - Cabeceras. La cabecera
Authorizationtransporta tu Key yContent-Type: application/jsonindica al servidor cómo interpretar el cuerpo. - Cuerpo. Como mínimo debes enviar una cadena
prompt. El prompt es la entrada creativa: todo lo que el modelo renderiza proviene de él, así que especifica con claridad el sujeto, el movimiento, la iluminación y el comportamiento de cámara.
Si la solicitud se acepta, la respuesta contiene un objeto de tarea. No obtienes la URL del vídeo de inmediato. Extrae el identificador de tarea de la respuesta y guárdalo. Los nombres exactos de los campos forman parte del esquema de respuesta documentado en la página del modelo; trátalos como la única fuente de verdad y no codifiques suposiciones en el cliente hasta haber visto una respuesta real.
Puedes usar curl primero para inspeccionar la respuesta sin procesar y después trasladar la misma llamada al código una vez que entiendas su forma.
Elegir parámetros: prompt, resolución y duración
Solo prompt es estrictamente obligatorio, pero varios parámetros opcionales determinan el resultado y el coste de la solicitud. Configúralos de forma consciente en lugar de aceptar los valores predeterminados a ciegas.
Prompt
El prompt es el parámetro con mayor impacto. Redáctalo como un briefing para un operador de cámara: sujeto, acción, entorno, iluminación y estilo de plano. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" da al modelo mucha más información que "a city". Mantén el prompt dentro del límite de longitud documentado en la página del modelo.
Resolución
Una resolución mayor implica más detalle y archivos de salida más grandes, y posiblemente tiempos de generación más largos. La generación de vídeo suele facturarse por la duración de salida, pero confirma la base de facturación actual y los posibles niveles de resolución en el panel de precios y en la documentación del modelo, en lugar de suponerlo. Elige la resolución más baja que cumpla tu objetivo de entrega: escalar en posproducción suele ser más económico que generar todo a la máxima calidad.
Duración
La duración controla cuántos segundos de vídeo genera el modelo y normalmente afecta tanto a la latencia como al coste. Los clips más cortos son mejores para iterar: pule el prompt con una duración corta hasta que el movimiento se vea correcto y luego vuelve a generar con la longitud final.
Validación antes del envío
Antes de conectar valores al código de producción, consulta la página del modelo para conocer los rangos permitidos de cada parámetro: duraciones admitidas, resoluciones soportadas y cualquier valor de enumeración. Después valida en el cliente: rechaza duraciones fuera de rango y valores de resolución desconocidos antes de que la solicitud salga de tu proceso. Así conviertes una clase de errores de validación del servidor en fallos inmediatos y baratos en tus propios registros.
La misma regla se aplica a los nombres de los parámetros. Cópialos de la documentación; una errata como un guion bajo de más en el campo de duración suele rechazarse o ignorarse en silencio, y el silencio es el bug más difícil de detectar.
Enviar la misma solicitud con Python
A continuación tienes el código de envío equivalente en Python. Lee la Key de una variable de entorno, envía el cuerpo JSON, comprueba el código de estado y devuelve el identificador de tarea desde los campos de respuesta documentados.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_video(prompt: str, **options) -> str:
payload = {
"prompt": prompt,
**options, # e.g. resolution="720p", duration=5
}
response = requests.post(
f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
body = response.json()
task_id = body["id"] # confirm the field name on the model page
return task_id
if __name__ == "__main__":
task_id = submit_video(
"A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
)
print("submitted task:", task_id)
Hay varias decisiones deliberadas en este código:
- Timeout. La llamada de envío debería devolver rápido, pero un
timeoutexplícito evita que un socket colgado bloquee tu worker. raise_for_status(). Falla de inmediato ante un error HTTP en lugar de analizar el cuerpo de error como si fuera una respuesta correcta.- Opciones por palabra clave. Pasar
**optionsmantiene legible el punto de llamada y hace trivial añadirresolutionodurationuna vez que hayas confirmado los nombres exactos en la página del modelo. - Devolver el ID. La responsabilidad de la función termina en el envío. Persiste ese ID en algún almacenamiento duradero: la siguiente sección lo usará para recuperar el resultado.
En un pipeline real, trata submit_video como un paso de un flujo de trabajo basado en colas: encólalo, guarda el ID de tarea devuelto junto con el registro de tu trabajo y deja que un worker independiente se encargue de recuperar el resultado.
Gestionar resultados asíncronos: sondeo frente a callback
Tras el envío tienes un ID de tarea, pero aún no tienes el vídeo. Hay dos formas de salvar esa distancia.
Sondeo
Consulta el endpoint de estado de la tarea a intervalos regulares hasta que la tarea alcance un estado terminal y, a continuación, obtén la URL de salida de la respuesta de finalización.
import time
import requests
def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}", # confirm path on the model page
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()
state = task["status"]
if state == "completed":
return task
if state == "failed":
raise RuntimeError(task.get("error", "generation failed"))
time.sleep(delay)
delay = min(delay * 1.5, 15) # gentle backoff, capped
raise TimeoutError(f"task {task_id} did not finish in time")
Tres reglas prácticas para el sondeo:
- Backoff. Empieza con un retardo corto y auméntalo gradualmente. Sondear a alta frecuencia de forma continua desperdicia cuota y añade carga sin ningún beneficio.
- Pon un límite. Todo bucle de sondeo necesita una fecha límite. La generación de vídeo puede tardar, pero un bucle sin límite acabará colgando tu worker para siempre por culpa de una tarea atascada.
- Distingue los estados. Gestiona
failedde forma explícita para que un prompt deficiente no se confunda en silencio con un timeout.
Callback
Si registras una URL de callback HTTPS, HiAPI puede notificarte cuando la tarea termine, evitando por completo el sondeo. Dos reglas hacen que los callbacks sean seguros y fiables:
- Verifica antes de confiar. Trata el callback como entrada no autenticada hasta haber verificado su firma u origen mediante el mecanismo documentado por la plataforma.
- Mantén la idempotencia. Un callback puede entregarse más de una vez. Usa el ID de tarea como clave de tu manejador y convierte el procesamiento de entregas repetidas en una operación nula: almacena el resultado una sola vez y acusa recibo de las entregas duplicadas.
Sea cual sea el método elegido, la recuperación del resultado es idempotente: obtener la URL del resultado de una tarea completada debe devolver el mismo vídeo, por lo que reintentar tras un error de red es seguro.
Errores habituales y cómo solucionarlos
La mayoría de los fallos se reduce a unas pocas categorías. Revisa esta lista antes de suponer que existe un comportamiento no documentado.
Fallo de autenticación
Un 401 o un 403 casi siempre significa que la Key falta, tiene un formato incorrecto o ha caducado. Comprueba que la cabecera Authorization existe, que el esquema de autenticación coincide exactamente con la documentación y que la variable de entorno contiene realmente la Key: una cadena vacía produce un fallo desconcertante pero relacionado con la autenticación.
Validación rechazada
Un 4xx con un mensaje de validación significa que el servidor ha rechazado tus parámetros. Vuelve a leer los rangos permitidos en la página del modelo y confirma los nombres de los parámetros carácter a carácter. Si la duración o la resolución están fuera de rango, la solución es la validación en el cliente descrita antes: falla rápido en tu propio código en lugar de ir y volver al servidor.
Tarea atascada en un estado no terminal
Si el sondeo nunca ve completed ni failed, puede que la tarea siga ejecutándose o que tu bucle de sondeo esté consultando un ID de tarea incorrecto. Registra el ID que enviaste y el ID que consultas, y compáralos. Tu bucle también debe imponer una fecha límite; cuando se active, expón el ID de la tarea en lugar de reintentar a ciegas.
El resultado no llega tras el callback
Si dependes de callbacks, comprueba que tu endpoint es accesible públicamente por HTTPS, que devuelve un estado de éxito rápidamente en lugar de ejecutar trabajo pesado en línea y que las entregas repetidas se gestionan de forma idempotente. Si el manejador del callback da error en la segunda entrega de la misma tarea, parecerá que el resultado se ha perdido.
Envío duplicado del mismo trabajo
Si tu worker reintenta la llamada de envío tras un timeout, puede crear tareas duplicadas. Antes de llamar al endpoint, registra una clave de solicitud de cliente o un ID de trabajo en tu propia base de datos y compruébala antes de reintentar, de modo que el envío sea idempotente por tu parte.
Principio general: cuando se produzca un fallo, lee primero el cuerpo de la respuesta de error y la documentación del modelo antes de modificar el código. Si un valor o un campo no está documentado, evita suponer que existe: verifícalo en la página del modelo y ajusta la solicitud en consecuencia.
Artículos relacionados
Ver todos los artículos →-
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
-
Tutorial
Casos prácticos de gemini-4-neon: 5 usos de alto valor y puntos clave de integración
-
Tutorial
Tutorial de la API seedance-2.5-flash de imagen a video: curl y Python Requests
Recorrido práctico de integración para desarrolladores: estructura de la solicitud, entradas de primer y último fotograma, sondeo asíncrono y solución de errores