Blog

Tutorial

Cómo llamar a la API de imagen a video de seedance-2.5: ejemplos de curl y Python listos para usar

Nov 12, 2026
Arte de portada abstracto: paneles de vidrio translúcidos superpuestos que proyectan franjas de azul frío sobre un campo gris pálido, plano y arquitectónico.
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:

  • prompt describe el movimiento. Mantenlo breve y concreto; las listas largas de adjetivos suelen diluir la instrucción.
  • first_frame_image es obligatorio para imagen a video. last_frame_image es 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 failed y cancelled como 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 →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API