Tutorial
Cómo llamar a la API de imagen a video de seedance-2.5: ejemplos de curl y Python listos para usar
En esta página
Qué te ofrece el endpoint de imagen a video de seedance-2.5
seedance-2.5 imagen a video es un endpoint de modelo asíncrono en HiAPI que convierte una o dos imágenes estáticas en un clip de video corto. Le envías una imagen (o un par de imágenes que sirven como puntos de inicio y fin del movimiento), describes el cambio que deseas y la plataforma devuelve una tarea que se resuelve en una URL de archivo de video cuando la generación finaliza.
En una pila típica de generación de video, este endpoint ocupa la capa de «dar vida a una imagen estática». Ya tienes la imagen de origen —imágenes de producto, renders de personajes, fotogramas de storyboard— y lo que necesitas es movimiento, no una imagen nueva. Como la llamada es asíncrona, tu trabajo consiste en enviar la tarea, conservar el identificador de la tarea y consultar repetidamente hasta que el resultado esté listo. Este patrón de enviar y luego consultar es común en los endpoints de generación de larga duración de HiAPI, así que el cliente que escribas aquí puede adaptarse a otros modelos.
El endpoint también ofrece opciones de audio nativo, lo cual es importante si tu flujo de trabajo necesita un clip con sonido en lugar de un material silencioso al que luego se le añade música. Si necesitas movimientos de cámara precisos fotograma a fotograma o animaciones en bucle, usar imagen a video con un primer fotograma y un último fotograma explícitos suele ser la opción más controlable sin tener que construir una escena 3D.
Requisitos previos y autenticación
Antes de la primera llamada, prepara tres cosas.
1. Una clave de API de HiAPI
Cada solicitud se autentica con tu clave, enviada como token bearer en la cabecera Authorization. No la incluyas en el control de código fuente: léela desde una variable de entorno, de modo que el mismo script funcione tanto en local como en CI.
export HIAPI_API_KEY="your_key_here"
2. Imágenes de origen accesibles para la API
Las entradas de imagen son URL. Aloja las imágenes en una ubicación accesible para el servicio: almacenamiento de objetos con URL firmadas, una CDN o cualquier dirección HTTPS pública. Si no quieres exponer las imágenes públicamente, genera una URL firmada de corta duración en lugar de hacer público el bucket.
Para el flujo de primer fotograma/último fotograma, necesitas una imagen (solo el primer fotograma) o dos imágenes (primer y último fotograma).
3. Un cliente HTTP
Cualquier herramienta que pueda enviar JSON sirve: curl para una prueba rápida de humo, requests o httpx en Python, fetch en Node. No necesitas un SDK especial.
La URL base, la ruta y los nombres de campo específicos del modelo están en la página del modelo en la consola de HiAPI; usa esos valores literalmente en los ejemplos de abajo. Una vez que tengas la clave y la URL de la imagen, ya puedes enviar la solicitud.
Entrada de primer fotograma y entrada de último fotograma
Las dos entradas de imagen controlan puntos distintos del clip de video, y cuál elijas cambia el grado de control que tienes sobre el movimiento.
Solo primer fotograma. Proporcionas una imagen y el modelo genera hacia delante desde ella. Es la opción correcta cuando quieres que el modelo invente el movimiento: un retrato que gira lentamente, un producto que rota, un paisaje con nubes que se desplazan. Renuncias a la certeza sobre dónde termina el clip, pero ganas más espacio creativo y solo necesitas un material.
Primer y último fotograma. Proporcionas dos imágenes y el modelo genera la trayectoria entre ellas. Es la opción correcta cuando los puntos finales importan: un logo que se ensambla en el emblema final, un personaje que pasa de la pose A a la pose B, un objeto que se desliza de izquierda a derecha por el encuadre. Proporcionar el último fotograma restringe el movimiento, lo que suele implicar menos sorpresas y, si planeas repetir el clip, una mejor capacidad de bucle.
Una regla práctica: si puedes describir el clip como «esta imagen cambia de alguna manera», usa solo el primer fotograma. Si puedes describirlo como «esta imagen se convierte en aquella imagen», proporciona las dos. Cuando proporciones dos, mantén ambas imágenes coherentes en composición, relación de aspecto e iluminación: un par de imágenes desemparejadas obliga al modelo a gestionar un salto que parece un fallo.
Tu prompt debe complementar las imágenes, no entrar en conflicto con ellas. Describe el movimiento, no el contenido estático que el modelo ya puede ver.
Enviar la primera solicitud con curl
La siguiente solicitud envía una tarea de imagen a video. Sustituye la ruta del endpoint, el identificador del modelo y los nombres de campo por los valores que aparecen en la página del modelo de imagen a video seedance-2.5 en la consola de HiAPI, y cambia las URL de imagen por las tuyas.
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "La cámara se acerca lentamente mientras el sujeto gira hacia la luz",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
Hay varios aspectos que conviene tener en cuenta sobre la estructura de la solicitud:
promptdescribe el movimiento. Mantenlo breve y concreto; las listas largas de adjetivos suelen diluir la instrucción.first_frame_imagees obligatorio para imagen a video.last_frame_imagees opcional: para generar solo con el primer fotograma, elimina por completo ese campo.- Si necesitas opciones de audio, son campos adicionales en el mismo cuerpo JSON (se explican más abajo).
La respuesta es un objeto de tarea que contiene un identificador y un estado. Guarda ese identificador; lo necesitarás en cada consulta. Si la llamada devuelve un error de autenticación o de validación, revisa primero las cabeceras y la URL de la imagen antes de reintentar.
La misma solicitud en Python
A continuación tienes el código de envío equivalente en Python, reestructurado para que sea fácil capturar el identificador de la tarea.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="La cámara se acerca lentamente mientras el sujeto gira hacia la luz",
)
print(task_id)
Hay dos hábitos que conviene adoptar cuanto antes. Primero, establece un timeout explícito en la llamada de envío: una solicitud colgada debe fallar rápido en lugar de bloquear tu worker. Segundo, conserva la respuesta original durante el desarrollo. El campo que guarda el identificador de la tarea puede diferir de task_id según la versión del endpoint; imprimir el JSON original una vez te ahorra una ronda de depuración.
Consultar la tarea asíncrona hasta que el video esté listo
La generación de imagen a video tarda más de lo que una solicitud HTTP debería permanecer abierta, así que la plataforma usa un ciclo de vida de enviar y luego consultar. El envío devuelve el identificador de la tarea; después consultas periódicamente el endpoint de la tarea hasta que su estado alcance un estado terminal.
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"La tarea {task_id} terminó como {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"La tarea {task_id} no estuvo lista tras {max_wait}s")
Diseña la consulta periódica en torno a cuatro reglas:
- Consulta con un intervalo moderado. Cinco segundos es un valor predeterminado razonable. Martillear el endpoint no hace que el video se renderice más rápido.
- Establece siempre una fecha límite. Las tareas pueden fallar o permanecer en cola más de lo esperado; un bucle sin límite convierte un problema temporal en un worker bloqueado.
- Trata
failedycancelledcomo estados terminales. Expone el campo de error en lugar de reintentar la misma tarea para siempre. - Usa retroceso al consultar de forma continua. Si consultas muchas tareas a la vez, aumenta gradualmente el intervalo para evitar picos de tráfico.
En producción, consulta desde un worker en segundo plano o una cola, no dentro del manejador de una solicitud web. El resultado es una URL de video; descárgala pronto y cópiala a tu propio almacenamiento, porque las URL de recursos generados normalmente no son permanentes.
Gestionar el indicador de audio nativo
seedance-2.5 puede generar clips con audio nativo, y ese control es un campo de la solicitud que va junto a las entradas de imagen y al prompt, no un endpoint separado. El nombre exacto del campo y los valores aceptables se indican en la página del modelo; la función auxiliar de Python de arriba lo ilustra pasando un valor booleano audio.
Activarlo o no depende de cómo se consuma el clip.
Solicita audio cuando: la salida va directamente a la audiencia —publicaciones sociales, avances, demostraciones— y quieres que el clip se sienta completo sin una segunda edición. El audio nativo también ayuda a los revisores a juzgar el ritmo, porque el sonido hace que la sincronización del movimiento sea más fácil de leer.
Omite el audio cuando: tu flujo de trabajo superpone su propia banda sonora, el clip se va a introducir en una herramienta de composición o edición, o planeas generar muchas variantes y poner música solo a la versión final elegida. La generación silenciosa mantiene el material neutro y evita problemas de sincronización posteriores.
Una nota práctica para acotar el alcance: trata el audio como una decisión por solicitud, no como una configuración global. Como se muestra arriba, una única función auxiliar que acepte un indicador audio permite que la misma ruta de código sirva tanto para el procesamiento por lotes silencioso en segundo plano como para el render final pulido.
Si el indicador está presente pero el resultado es silencioso, confirma primero que el valor se serializa como esperas —la cadena "true" frente al booleano true es un desajuste habitual— antes de suponer que el modelo lo ignoró.
Puntos de fallo habituales y próximos pasos
La mayoría de los problemas de integración iniciales se agrupan en cuatro categorías.
Entradas que el servicio no puede obtener
Una URL que funciona en tu navegador puede fallar en el lado del servidor: buckets privados, enlaces caducados o hosts que bloquean agentes de usuario que no son navegadores. Usa URL firmadas cuya vigencia cubra todo el proceso de generación y confirma que la imagen se carga desde una máquina fuera de tu red.
Fotogramas desemparejados
Cuando el primer y el último fotograma difieren en relación de aspecto, recorte o temperatura de color, el modelo tiene que reconciliar ese salto. Antes de enviar, preprocesa el par de imágenes a las mismas dimensiones y a una gradación de color similar.
Nombres de campo o identificadores de modelo incorrectos
Los ejemplos de aquí usan la estructura de solicitud de la página del modelo; copia literalmente los nombres de campo y la cadena del modelo desde la consola, no de memoria ni de fragmentos antiguos. Los errores tipográficos en los nombres de campo suelen ignorarse en silencio en lugar de rechazarse.
Consultas que nunca terminan
Si tu bucle agota el tiempo una y otra vez, registra cada valor de estado que observes. Ver un estado inesperado suele explicar el estancamiento: puede que tu comprobación de estado terminal simplemente no coincida con lo que devuelve la API.
Una vez que un solo clip funciona de extremo a extremo, los siguientes pasos naturales son procesar varias imágenes por lotes con la misma función auxiliar de envío y consulta, añadir reintentos con retroceso alrededor del envío y escribir los resultados en almacenamiento persistente. Puedes encontrar los detalles del endpoint, los campos de solicitud y la referencia de parámetros en la página del modelo de imagen a video seedance-2.5, y adaptar el código anterior a tus propias imágenes a partir de ahí.
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