API de imagen a video Seedance 2.5: cómo enviar el primer fotograma, el primero y el último, y las imágenes de referencia

TL;DR

• seedance-2.5/image-to-video hace que una imagen se mueva, y también permite dar el primer fotograma y el último a la vez para que el modelo complete el proceso intermedio. Cada clip dura de 4 a 30 segundos e incluye audio. Abre la página del modelo para generarlo en línea; los usuarios nuevos reciben 200 créditos al registrarse.
• Mismo precio que texto a video: 720p a $0.204 por segundo, 1080p a $0.516 por segundo. 4 segundos en 720p son $0.816.
• Dos modos de uso, elige uno: primer fotograma / primer y último fotograma, o imagen de referencia + audio de referencia; no se pueden mezclar.

Primero, un ejemplo real: primer y último fotograma

Da una imagen de «maceta vacía» como primer fotograma y una de «maceta llena de albahaca» como último, y escribe en el prompt solo cómo cambia en el medio:

Time-lapse growth of a basil seedling sprouting and unfurling leaves inside the terracotta pot, smooth continuous motion, soft morning light staying consistent, camera locked off, no cuts

Generar con este prompt → (sube tu primer y último fotograma, 4 segundos, 720p)

seedance-2.5/image-to-video, primer fotograma + último fotograma, 720p, 4 segundos, con audio, $0.816.

Mantén la composición, la iluminación y la posición de los objetos iguales en las dos imágenes, y cambia solo lo que quieres que muestre el video (aquí, la planta); así la transición intermedia sale fluida. La frase "soft morning light staying consistent" del prompt sirve para que el modelo no convierta también la luz en un time-lapse.

curl: solo el primer fotograma

El uso más común: una imagen de producto o una ilustración, más una frase de «cómo se mueve a continuación»:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "input": {
      "prompt": "La cámara se acerca lentamente a una taza de café humeante, el vapor gira y sube en la luz del amanecer, ligero temblor de cámara en mano",
      "first_frame_url": "https://your-cdn.example.com/coffee-cup.jpg",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Devuelve un taskId:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Consulta el resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Cuando status sea success, descarga el video desde output[0].url.

Primer y último fotograma: añade un last_frame_url

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Time-lapse del mismo escritorio del día a la noche: la luz del día se va atenuando, la lámpara de mesa se enciende con luz cálida, las luces de la ciudad al otro lado de la ventana se van encendiendo una a una, cámara fija",
    "first_frame_url": "https://your-cdn.example.com/desk-day.jpg",
    "last_frame_url": "https://your-cdn.example.com/desk-night.jpg",
    "duration": 4,
    "resolution": "720p"
  }
}

• last_frame_url debe usarse junto con first_frame_url.
• Si la proporción del último fotograma no coincide con la del primero, el último se recorta desde el centro; lo mejor es generar ambas imágenes con la misma proporción.
• El formato de imagen sigue al primer fotograma; aspect_ratio solo tiene el valor adaptive, no hace falta enviarlo.

Python: enviar, consultar y descargar

# pip install requests; antes, export HIAPI_KEY=tu_Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="seedance-2.5/image-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # Al reintentar el envío de la misma tarea, usa el mismo Idempotency-Key para evitar cargos duplicados
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "Time-lapse growth of a basil seedling sprouting and unfurling leaves, camera locked off, no cuts",
    first_frame_url="https://your-cdn.example.com/seedling-start.jpg",
    last_frame_url="https://your-cdn.example.com/seedling-grown.jpg",
    duration=4, resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Otro modo de uso: imagen de referencia + audio de referencia

Si no quieres fijar una imagen como primer fotograma, sino que el modelo «tome como referencia» el aspecto de una persona, la apariencia de un producto o un estilo visual, usa reference_image_urls (hasta 30 imágenes) y, además, puedes añadir reference_audio_urls (hasta 10 fragmentos) para referenciar el estilo de sonido:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "La chica de la imagen de referencia lleva la misma mochila azul y cruza una esquina lluviosa, cámara en seguimiento",
    "reference_image_urls": [
      "https://your-cdn.example.com/girl.jpg",
      "https://your-cdn.example.com/backpack.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }
}

Ojo: las imágenes de referencia y los audios de referencia no se pueden enviar junto con first_frame_url / last_frame_url; elige una de las dos opciones.

Vista general de parámetros

Parámetro	Valor	Descripción
prompt	cadena, obligatorio	Describe la acción, la cámara y el sonido; no hace falta volver a describir toda la imagen
first_frame_url	URL de imagen	Primer fotograma
last_frame_url	URL de imagen	Último fotograma, se usa junto con el primero
reference_image_urls	hasta 30 imágenes	No se puede usar junto con el primer/último fotograma
reference_audio_urls	hasta 10 fragmentos	No se puede usar junto con el primer/último fotograma
duration	entero de 4 a 30, por defecto 5	En segundos
resolution	720p / 1080p, por defecto 720p
generate_audio	por defecto true	El audio se genera junto con la imagen
output_format	mp4 / mov

Calcula el coste

Duración	720p ($0.204/segundo)	1080p ($0.516/segundo)
4 segundos	$0.816	$2.064
5 segundos	$1.02	$2.58
10 segundos	$2.04	$5.16
15 segundos	$3.06	$7.74

El primer y el último fotograma cuestan lo mismo que solo el primero; el coste depende solo de la resolución y los segundos. Para más detalle, consulta Precios de la API de Seedance 2.5.

Antes de lanzar

• La URL de la imagen debe ser accesible públicamente: vale una dirección HTTP(S) o un data URL; el modelo no puede acceder a direcciones de red internas.
• Usa callbacks en lugar de polling: añade en el nivel superior de la solicitud "callback": {"url": "https://tu-dominio/hiapi/callback"} y elimina duplicados por taskId.
• Guarda el resultado cuanto antes: output[0].url es un enlace temporal; en cuanto lo recibas, guárdalo en tu propio almacenamiento.
• Reintenta con clave de idempotencia: añade la cabecera Idempotency-Key; al reintentar con la misma clave, la tarea solo se crea una vez.
• Reembolso automático en caso de fallo: solo se cobran los videos generados correctamente.

Preguntas frecuentes

¿Qué hago si entre el primer y el último fotograma aparece un «fundido»?

Cuando las dos imágenes son muy distintas, es fácil que durante uno o dos segundos parezca que se funden. Mantén la composición y los objetos iguales en ambas imágenes y cambia solo el sujeto, y añade en el prompt "camera locked off, no cuts".

¿Se puede dar solo el último fotograma?

No, el último fotograma debe usarse junto con el primero.

¿Se puede pedir vertical?

El formato de imagen sigue al primer fotograma; para vertical, sube una imagen de primer fotograma en vertical.

¿Cuál es la diferencia entre el primer fotograma y una imagen de referencia?

El primer fotograma se convierte tal cual en el primer fotograma del video; la imagen de referencia solo sirve para que el modelo tome como referencia la apariencia y el estilo, y la imagen se puede recomponer.

¿Solo tienes prompt y ninguna imagen? Consulta API de texto a video Seedance 2.5. Si quieres más formas de escribir el primer fotograma, consulta el Manual de uso de Seedance 2.5, o directamente ve a la página del modelo y prueba a subir una imagen.