Instrucciones de integración de la API de generación de videos SeeDance

ByteDance Seedance Video Generation API guide - Ace Data Cloud

Este documento presentará una forma de integración de la API de generación de videos SeeDance, que permite generar videos oficiales de SeeDance mediante la entrada de parámetros personalizados.

​

Proceso de solicitud

Para utilizar la API de generación de videos SeeDance, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API y guardarlo para uso futuro.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual.

Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno para cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.

📘 Documentación completa: API de generación de videos SeeDance →

​

Uso básico

Primero, debes entender la forma básica de uso, que consiste en ingresar la palabra clave content.text, el tipo content.type=text y el modelo model, para obtener el resultado procesado. El contenido específico es el siguiente:

Aquí podemos ver que hemos configurado los encabezados de la solicitud, que incluyen:

• accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, formato JSON.
• authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.

Además, se ha configurado el cuerpo de la solicitud, que incluye:

• model: el modelo para generar el video.
  • Serie Seedance 1.x: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
  • Serie Seedance 2.0 (soporta entrada multimodal como referencia de rostro/personaje): doubao-seedance-2-0-260128 (estándar), doubao-seedance-2-0-fast-260128 (rápido), doubao-seedance-2-0-mini-260615 (ligero). Consulta la sección “Referencia de rostro y personaje (Seedance 2.0)” a continuación.
• content: matriz de contenido de entrada, type puede ser text (palabra clave), image_url (imagen de referencia), audio_url (audio de referencia, 2.0), video_url (video de referencia, 2.0). Las imágenes pueden especificar su uso a través de role: first_frame (primer fotograma) / last_frame (último fotograma) / reference_image (referencia de rostro/personaje/sujeto).
• resolution: resolución de salida, opciones 480p / 720p / 1080p (el modelo estándar 2.0 también soporta 4k; los modelos fast / mini de 2.0 tienen un máximo de 720p).
• ratio: relación de aspecto, opciones 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
• duration: duración del video (segundos, entero). Los rangos varían según la serie: Serie 1.0 2–12; 1.5 Pro 4–12; Serie 2.0 4–15. La serie 1.5 Pro y 2.0 también soportan -1 (duración seleccionada automáticamente por el modelo).
• seed: semilla aleatoria, entero, -1 a 4294967295.
• camerafixed: si la cámara está fija, true / false.
• watermark: si se añade una marca de agua, true / false.
• generate_audio: si se genera un video con audio, true / false, solo soportado por doubao-seedance-1-5-pro-251215.
• return_last_frame: si se devuelve la URL de la última imagen del video en el resultado.
• execution_expires_after: tiempo de espera de la tarea (segundos), rango 3600–259200.
• callback_url: dirección de callback asíncrono, al configurarla la API devolverá inmediatamente task_id, y cuando la tarea esté completa, enviará el resultado a esa dirección.
• async: opcional, si se establece en true, la interfaz devolverá inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego podrás consultar el resultado a través de la interfaz de consulta de tareas correspondiente.

Después de seleccionar, puedes ver que a la derecha también se ha generado el código correspondiente, como se muestra en la imagen:

Haz clic en el botón “Try” para realizar una prueba, como se muestra en la imagen anterior, y obtendremos el siguiente resultado:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}

El resultado devuelto tiene varios campos, que se describen a continuación:

• success, el estado de la tarea de generación de video en ese momento.
• task_id, el ID de la tarea de generación de video en ese momento.
• trace_id, el ID de seguimiento de la generación de video en ese momento.
• data, la lista de resultados de la tarea de generación de video en ese momento.
  • task_id, el ID del lado del servidor de la tarea de generación de video en ese momento.
  • video_url, el enlace al video de la tarea de generación de video en ese momento.
  • status, el estado de la tarea de generación de video en ese momento.
    • model, el modelo utilizado para generar el video.

Podemos ver que hemos obtenido información satisfactoria sobre el video, solo necesitamos obtener el video generado de SeeDance a través de la dirección del enlace de video en data.

Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'

​

Descripción de parámetros en línea

Al final de la palabra clave content[].text, puedes pasar parámetros de generación adicionales mediante la forma --parameter value (método antiguo, verificación débil, si se introduce incorrectamente se utilizarán valores predeterminados). La lista completa de parámetros es la siguiente:

Parámetro en línea	Campo correspondiente	Descripción	Rango de valores
--rs	resolution	Resolución de salida	480p / 720p / 1080p
--rt	ratio	Relación de aspecto	16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive
--dur	duration	Duración del video (segundos)	2–12
--frames	frames	Número de fotogramas del video	Enteros que satisfacen 25+4n en [29, 289] (solo soportado en la serie 1.0)
--fps	framespersecond	Tasa de fotogramas	Solo soporta 24
--seed	seed	Semilla aleatoria	-1 a 4294967295
--cf	camerafixed	¿Cámara fija?	true / false
--wm	watermark	¿Agregar marca de agua?	true / false

Práctica recomendada: Utilizar directamente los campos de nivel superior correspondientes en el cuerpo de la solicitud (como resolution, ratio, etc.), para un modo de validación estricta, si los parámetros están incorrectos, se devolverá un mensaje de error claro, lo que facilita la identificación de problemas.

​

Generar video con audio

doubao-seedance-1-5-pro-251215 soporta la generación de videos con audio a través del parámetro generate_audio:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "Una chica sostiene un zorro, el viento sopla su cabello, se puede escuchar el sonido del viento"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

Otros modelos no soportan este parámetro, si se pasa, será ignorado.

​

Primer fotograma de video generado a partir de imagen

Si deseas generar un video a partir de una imagen, primero el parámetro content debe incluir un elemento con type como image_url, el campo image_url debe estar en formato de objeto: {"url": "https://..."} o en formato Base64 {"url": "data:image/png;base64,..."}.

Nota: image_url no soporta ser pasado directamente en formato de cadena (como "image_url": "https://..."), debe usarse en formato de objeto "image_url": {"url": "https://..."}, de lo contrario se devolverá un error 400.

Código correspondiente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "Una chica sostiene un zorro en sus brazos. Ella abre los ojos y mira tiernamente a la cámara, mientras el zorro la sostiene afectuosamente. A medida que la cámara se aleja lentamente, su cabello es suavemente soplado por el viento. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como el siguiente:

{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Se puede ver que el efecto generado es un video creado a partir de la imagen, el resultado es similar al anterior.

​

Primer y último fotograma de video generado a partir de imagen

Si deseas generar el primer y último fotograma de un video a partir de imágenes, primero el parámetro content debe incluir un tipo image_url, y establecer role como first_frame y last_frame, se puede especificar el siguiente contenido:

• role: especifica el primer fotograma o el último fotograma.
• image_url
  • url enlace de la imagen Al mismo tiempo, content también necesita incluir un tipo text como palabra clave de prompt.

Código correspondiente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "Toma de 360 grados"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como el siguiente:

{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Se puede ver que el efecto generado es un video de personajes, el resultado es similar al anterior.

​

Referencia de rostros y personajes (Seedance 2.0)

La serie Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) soporta la inclusión de materiales de referencia de personas reales / personajes: añadiendo en content un elemento con type como image_url y role como reference_image, se puede usar una foto de la persona como referencia, el modelo mantendrá las características faciales de esa persona en el video generado, permitiendo “colocar” a la misma persona en un nuevo escenario, acción o toma.

📌 Las fotos de personas reales serán registradas automáticamente por la plataforma como material de fondo antes de ser utilizadas para la generación, todo el proceso es completamente transparente para el llamador: el formato de solicitud y respuesta no cambia, no se requieren parámetros adicionales, solo la primera generación tomará unos segundos más para el procesamiento del material.

Puntos clave de uso:

• Solo los modelos de la serie Seedance 2.0 soportan reference_image; para modelos 1.x, utilice first_frame / last_frame (primer y último fotograma del video).
• reference_image no puede ser utilizado junto con first_frame / last_frame, solo se puede elegir uno.
• Límite máximo de referencias multimodales: image_url hasta 9 imágenes; 2.0 también soporta audio_url (con role como reference_audio, hasta 3) y video_url (con role como reference_video, hasta 3).
• Requisitos para el material de audio de referencia (audio_url): formato wav / mp3; duración de 2 a 15 segundos por archivo, hasta 3 archivos y duración total no superior a 15 segundos; cada archivo no debe exceder 15 MB. Exceder el rango de duración resultará en un fallo en la fase de procesamiento del material.
• Requisitos para el material de video de referencia (video_url): formato mp4 / mov; duración de 2 a 15 segundos por archivo, hasta 3 archivos y duración total no superior a 15 segundos.
• Se recomienda usar imágenes de referencia que sean de una sola persona, de frente, claras y sin obstrucciones; cuanto más clara sea la cara, mayor será la similitud.

​

Ejemplo 1: Primer plano manteniendo la apariencia del personaje

Proporcione una foto de rostro y haga que la persona sonría y salude a la cámara. El código correspondiente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "La mujer mira a la cámara, da una cálida sonrisa natural y saluda con la mano, iluminación suave de estudio, suave acercamiento de cámara."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

El resultado devuelto es el siguiente, el video generado mantiene la apariencia del personaje con la foto de referencia:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

​

Ejemplo 2: Colocar a la misma persona en un nuevo escenario

La gran ventaja de reference_image es que solo se conserva la identidad del personaje, mientras que el escenario, la vestimenta y los movimientos son completamente determinados por las palabras clave. A continuación, usando la misma foto de rostro, haga que la persona vista un abrigo beige y camine por un parque otoñal:

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "La misma mujer vestida con un abrigo beige camina por un soleado parque de otoño, hojas doradas cayendo a su alrededor, sonríe suavemente a la cámara, toma de seguimiento cinematográfica."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

El resultado devuelto es el siguiente, la apariencia del personaje se mantiene, mientras que el escenario ha cambiado a un parque otoñal:

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 Si desea que el personaje replique con precisión la composición de la foto (en lugar de “el mismo personaje en un nuevo escenario”), puede usar first_frame (primer fotograma del video) para que el video comience a moverse desde esta foto.

​

Callback asíncrono

Debido a que la generación de videos de SeeDance API toma un tiempo considerable (aproximadamente 1-2 minutos), puede utilizar el campo callback_url para emplear el modo asíncrono, evitando que la conexión HTTP esté ocupada durante mucho tiempo.

Flujo general: el cliente inicia la solicitud especificando callback_url, la API devuelve inmediatamente una respuesta que incluye task_id; una vez que la tarea se completa, la plataforma enviará los resultados generados en formato JSON POST a callback_url, y los resultados también incluirán task_id para facilitar la asociación.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

Cuando la tarea se completa, el contenido que la plataforma envía a callback_url es el siguiente:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

El campo task_id en los resultados es el mismo que el devuelto al realizar la solicitud, y a través de este campo se puede lograr la asociación de la tarea.

​

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error correspondiente y la información. Por ejemplo:

• 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 401 invalid_token: No autorizado, token de autorización inválido o faltante.
• 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
• 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

A través de este documento, usted ha aprendido cómo utilizar la API de generación de videos de SeeDance mediante palabras clave, imágenes de referencia, y referencias de rostros / personajes de Seedance 2.0 para generar videos. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.