ByteDance

Seedance 2.5

seedance-2.5/reference-to-video

Modelo de generación conjunta de audio y vídeo de ByteDance Seed, compatible con clips continuos de hasta 30 segundos y 4K, y con control preciso de la imagen mediante referencias multimodales y edición a nivel de marca de tiempo

seedance-2.5/image-to-video seedance-2.5/reference-to-video seedance-2.5/text-to-video

Probar seedance-2.5/reference-to-video

Entrada

Creaciones

Ver todas las creaciones

Salida

video

Rellena los parámetros y genera: los resultados aparecerán aquí.

Precios

seedance-2.5/reference-to-video per second

Especificaciones	Precio unitario
480P	$0.1215
720P	$0.2715
1080P	$0.680

Descripción general

Esta es la vía de generación de video con referencias de Seedance 2.5, orientada a tareas de generación de video en las que se necesita restringir la consistencia visual mediante materiales. El desarrollador envía una instrucción (prompt) y al menos un video de referencia, y puede añadir además referencias de imagen y audio para que el modelo cite los materiales en el orden @image1, @video1, @audio1 y genere un video final de 4 a 30 segundos, de 480p a 1080p. Es adecuada para equipos de publicidad, series cortas y contenido de marca que necesitan fijar la apariencia de personajes, productos y escenarios en creaciones seriadas, y también para producir fragmentos narrativos que requieren efectos de sonido y diálogos sincronizados.

Aspectos destacados

Restricción conjunta de la imagen mediante materiales multimodales: admite hasta 30 imágenes, 10 videos y 10 audios como referencias simultáneas, para fijar la apariencia de productos, personajes y escenarios.
Referencia ordenada de materiales en la instrucción: en el prompt se hace referencia a los elementos de referencia en el orden @image1, @video1, @audio1, vinculando claramente cada material con el objetivo visual.
Duración y relación de aspecto controlables: la duración de salida puede elegirse entre 4 y 30 segundos o dejarse a criterio automático del modelo; la relación de aspecto admite desde 16:9, 9:16 hasta 21:9, así como adaptación automática según los materiales.
Generación sincronizada de audio y video: por defecto se generan diálogos, efectos de sonido y audio de fondo sincronizados con la imagen, y puede desactivarse para obtener una salida solo de imagen.

Descripción de capacidades

Generación impulsada por video de referencia: se introduce al menos un video de referencia y el modelo genera un fragmento nuevo a partir de él, sin extender ni recortar el original; es adecuado para producciones que necesitan reutilizar el lenguaje de cámara y la textura visual existentes.

Referencia mixta de imágenes y videos: hasta 30 imágenes y hasta 10 videos, que pueden enviarse combinados para restringir por separado personajes, productos y escenarios, reduciendo la deriva de apariencia en contenidos seriados.

Referencia de audio y generación de audio: se pueden añadir hasta 10 referencias de audio en wav o mp3 (deben enviarse junto con al menos un video de referencia) y elegir si se generan diálogos, efectos de sonido y sonido de fondo sincronizados.

Opciones de resolución y formato de salida: la salida admite tres niveles, 480p, 720p y 1080p, y formatos mp4 o mov orientado a postproducción profesional; la facturación se calcula por segundos de salida.

Búsqueda en línea para complementar información: se puede activar web_search para que el modelo consulte, antes de generar, información de actualidad relacionada con el prompt; es adecuado para contenidos que necesitan citar hechos actuales.

Escenarios de aplicación

Equipos de publicidad y marca para cortos de producto: restringir la apariencia con imágenes de producto y videos de referencia grabados, y generar fragmentos publicitarios de 4 a 30 segundos para materiales de campaña y distribución en redes sociales.
Equipos de series cortas para mantener la consistencia de personajes: usar imágenes de personajes y fragmentos existentes como referencia para generar por lotes tomas continuas del mismo personaje, destinadas al montaje y la edición posterior.
Equipos de postproducción para previsualizar propuestas de tomas: enviar videos de referencia de escenarios e imágenes de composición para obtener rápidamente fragmentos de previsualización con una calidad cercana al video final, útiles para la aprobación del cliente y la comunicación previa al rodaje.
Equipos de contenido para fragmentos con audio y video sincronizados: aportar referencias de doblaje o música y activar la generación de audio para producir videos finales con diálogos y efectos de sonido sincronizados, listos para uso directo o para una mezcla posterior.

Limitaciones y recomendaciones de selección

Cada fragmento generado tiene una duración máxima de 30 segundos; las narraciones más largas deben dividirse en varios fragmentos generados por separado y unirse después. Los materiales de referencia tienen restricciones claras: los videos deben durar entre 2 y 30 segundos y su duración total no puede superar los 30 segundos; la duración total del audio tampoco puede superar los 30 segundos, y el tamaño de archivo y el número de píxeles tienen límites mínimos y máximos; los materiales que no cumplan los requisitos provocarán un fallo directo. Esta vía está destinada a la generación guiada por referencias y no admite edición de video ni extensión del original; además, el uso de múltiples materiales de referencia implica un mayor coste de redacción de instrucciones y ajuste de parámetros. Para necesidades ligeras, de una sola toma y sin requisitos de consistencia, puede considerarse la vía de generación de video a partir de texto de la misma serie.

Preguntas frecuentes

Ver todas las preguntas →

¿Se requiere subir tanto el primer fotograma como el último para la generación de video a partir de imagen con Seedance 2.5?

No es necesario. En el modo de primer fotograma/primer y último fotograma, si solo se sube first_frame_url, el modelo extiende naturalmente las imágenes posteriores a partir del primer fotograma; si se necesita controlar el estado final de la toma, se proporciona además last_frame_url. El último fotograma no puede usarse de forma independiente. También se puede optar por usar reference_image_urls o reference_audio_urls como modo de referencia, sin pasar los fotogramas de los extremos.
¿Se pueden mezclar el primer fotograma, el primer y último fotograma y múltiples materiales de referencia en una sola solicitud?

Actualmente, HiAPI Playground los trata como dos modos de entrada: el modo de primer fotograma/primer y último fotograma, o el modo de referencia con reference_image_urls y reference_audio_urls. Para evitar que las señales de control entren en conflicto, conserve un solo modo en cada solicitud; cuando necesite un video de referencia para guiar la acción o el movimiento de cámara, utilice en su lugar el endpoint independiente seedance-2.5/reference-to-video.
¿Qué duraciones y resoluciones admite la generación de video a partir de imagen de Seedance 2.5?

El contrato de solicitud actual admite duraciones enteras de 4–30 segundos, así como 720p y 1080p. El aspect_ratio de salida es fijo en adaptive y sigue la relación de aspecto del primer fotograma. Los cuatro casos de la página son todos en 720p, de los cuales tres son de 4 segundos y uno de 5 segundos; los 30 segundos están dentro del rango admitido por la interfaz, pero la página aún no cuenta con un caso correspondiente.
¿Cómo se factura Seedance 2.5 de imagen a video?

Se factura según la duración y la resolución de salida; 720p y 1080p usan tarifas por segundo diferentes; el importe exacto se rige por el precio en tiempo real de la página del modelo y el registro de tareas.

Crear una tarea de generación

POST https://api.hiapi.ai/v1/tasks

Encabezados

AuthorizationstringObligatorio

Clave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API

Content-TypestringOpcional

El cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.

Idempotency-KeystringOpcional

Clave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.

Clave de idempotencia

Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.

Cuerpo

modelstringObligatorio

Valor fijo actual: seedance-2.5/reference-to-video

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para seedance-2.5/reference-to-video y la ruta default; consulta la tabla de parámetros a continuación.

promptstringObligatorio

Instrucción de generación que explica cómo utilizar los materiales de referencia; haz referencia a los elementos de referencia en orden como @image1, @video1, @audio1. Este modelo está diseñado para generación guiada por referencias y no admite edición ni continuación de vídeo.

durationintegerOpcionalPredeterminado: 5

Duración del vídeo de salida en segundos; puedes pasar -1 para duración automática, o un número entero entre 4 y 30. Valor predeterminado: 5.

Opciones:-145678910

Mostrar todo (20)

1112131415161718192021222324252627282930

resolutionstringOpcionalPredeterminado: "480p"

Resolución del vídeo de salida; admite 480p, 720p, 1080p. Valor predeterminado: 480p.

Opciones:480p720p1080p

web_searchbooleanOpcionalPredeterminado: false

Indica si se permite al modelo buscar en línea información en tiempo real mencionada en el prompt. Valor predeterminado: false.

aspect_ratiostringOpcionalPredeterminado: "adaptive"

Relación de aspecto del fotograma de salida; adaptive indica que el modelo sigue la proporción de los materiales de referencia. Valor predeterminado: adaptive.

Opciones:16:94:31:13:49:1621:9adaptive

output_formatstringOpcionalPredeterminado: "mp4"

Formato de contenedor del vídeo de salida; mp4 es el formato predeterminado con mejor compatibilidad, mov está orientado a postproducción profesional. Valor predeterminado: mp4.

Opciones:mp4mov

generate_audiobooleanOpcionalPredeterminado: true

Indica si se generan simultáneamente diálogos, efectos de sonido y audio de fondo. Valor predeterminado: true.

reference_audio_urlsarrayOpcionalmaxItems 10

Arreglo de URL de audio de referencia, máximo 10 pistas; cada pista debe ser wav o mp3, tamaño no superior a 15 MB, duración de 2 a 30 segundos, y la duración total de audio no debe superar los 30 segundos. Al proporcionar audio de referencia, se debe proporcionar también al menos un vídeo de referencia.

Array [ string ]

reference_image_urlsarrayOpcionalmaxItems 30

Arreglo de URL de imágenes de referencia, máximo 30 imágenes; admite jpeg, png, webp, bmp, tiff, gif, cada una no superior a 30 MB, de 300 a 6000 píxeles por lado, relación de aspecto de 0.4 a 2.5, no admite SVG, HEIC, HEIF.

Array [ string ]

reference_video_urlsarrayObligatoriominItems 1maxItems 10

Arreglo de URL de vídeos de referencia, máximo 10 pistas; cada pista debe ser mp4 o mov, con un total de píxeles no inferior a 409600 (por ejemplo, 854x480 o superior), frecuencia de fotogramas de 24 a 60 fps, tamaño no superior a 200 MB, duración de 2 a 30 segundos, de 300 a 6000 píxeles por lado, relación de aspecto de 0.4 a 2.5, y la duración total de vídeo no debe superar los 30 segundos.

Array [ string ]

callbackobjectOpcional

Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.

Callbacks (Webhook)

Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.

urlstringObligatorio

Obligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.

whenstringOpcionalPredeterminado: "final"

Actualmente solo se admite final: notifica tanto en success como en fail.

Opciones:final

storagestringOpcionalPredeterminado: "temp"

Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.

Opciones:temppersistent

Ejemplos de solicitud

# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "resolution": "480p",
    "web_search": false,
    "aspect_ratio": "adaptive",
    "output_format": "mp4",
    "generate_audio": true,
    "reference_video_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5/reference-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "resolution": "480p",
      "web_search": false,
      "aspect_ratio": "adaptive",
      "output_format": "mp4",
      "generate_audio": true,
      "reference_video_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "seedance-2.5/reference-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "resolution": "480p",
          "web_search": False,
          "aspect_ratio": "adaptive",
          "output_format": "mp4",
          "generate_audio": True,
          "reference_video_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obtener el detalle de la tarea

GET https://api.hiapi.ai/v1/tasks/:id

Campos de respuesta

taskIdstringObligatorio

ID de tarea, siempre con prefijo tk-hiapi-.

modelstringObligatorio

Nombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.

routestringOpcional

Solo aparece si se usó el parámetro route explícito; repite el valor enviado.

statusstringObligatorio

Estado de la tarea.

Valores de estado

queued En cola, sin iniciar. handling Procesando. archiving Proceso terminado, preparando artefactos. success Terminal: completado, artefactos disponibles (se devuelve output). fail Terminal: error (se devuelve error). Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.

creatednumberObligatorio

Hora de creación de la tarea (segundos Unix).

completednumberObligatorio

Segundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.

outputarrayOpcional

Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).

Array [ object ]

Elementos del array

urlstringObligatorio

URL del artefacto, descargable directamente.

typestringObligatorio

Valores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.

expireAtnumberObligatorio

Segundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.

errorobjectOpcional

Solo con status == fail.

codestringObligatorio

Código de error de negocio.

messagestringObligatorio

Descripción del error.

Ejemplos de respuesta

Éxito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

En proceso (no terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fallido

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}