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

Este documento presentará una forma de integración de la API de generación de videos de 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 de SeeDance, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API, que debes guardar como respaldo.

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 de 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; fast / mini de 2.0 soportan hasta 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), rango 1.x de 2 a 12, rango 2.0 de 2 a 15.
seed: semilla aleatoria, entero, de -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 doubao-seedance-1-5-pro-251215 lo soporta.
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 devuelve inmediatamente task_id, y al completar la tarea, enviará el resultado a esa dirección mediante POST.
async: opcional, si se establece en true, la interfaz devuelve inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego puedes consultar el resultado mediante 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 del 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 del resultado. 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 mediante la adición de --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]
`--fps`	`framespersecond`	Tasa de fotogramas	Solo se admite `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 (como resolution, ratio, etc.) en el cuerpo de la solicitud, 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 admite 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 admiten este parámetro, se ignorará si se pasa.

Generar el primer fotograma de un video a partir de una 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 admite la entrada directa 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 a partir de una imagen, el resultado es similar al anterior.

Generar el primer y último fotograma de un video a partir de imágenes

Si deseas generar el primer y último fotograma de un video a partir de imágenes, primero el parámetro content debe incluir elementos de tipo image_url, y se deben establecer los roles como first_frame y last_frame, para especificar el contenido de la siguiente manera:

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) admite la entrada de materiales de referencia de “personas reales / personajes”: al agregar un elemento en content 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 nuevas escenas, acciones o tomas.

📌 Las fotos de personas reales serán registradas automáticamente por la plataforma como materiales 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 un máximo de 9 imágenes; 2.0 también soporta audio_url (con role como reference_audio, un máximo de 3) y video_url (con role como reference_video, un máximo de 3).
Se recomienda usar imágenes de referencia de una sola persona, de frente, claras y sin obstrucciones; cuanto más clara sea la cara, mayor será la similitud.

Ejemplo uno: 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, un 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 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 dos: 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 las acciones son completamente determinadas por las palabras clave. A continuación, con 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 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 “la misma persona en un nuevo escenario”), puede usar first_frame (primer fotograma del video), haciendo 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: cuando 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 en la solicitud, y a través de este campo se puede realizar la asociación de tareas.

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusión

A través de este documento, ha aprendido cómo utilizar la API de generación de videos de SeeDance mediante palabras clave, imágenes de referencia, y la referencia de rostro/personaje 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.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

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

Proceso de solicitud

Uso básico

Descripción de parámetros en línea

Generar video con audio

Generar el primer fotograma de un video a partir de una imagen

Generar el primer y último fotograma de un video a partir de imágenes

Referencia de rostros y personajes (Seedance 2.0)

Ejemplo uno: Primer plano manteniendo la apariencia del personaje

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

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión

​Proceso de solicitud

​Uso básico

​Descripción de parámetros en línea

​Generar video con audio

​Generar el primer fotograma de un video a partir de una imagen

​Generar el primer y último fotograma de un video a partir de imágenes

​Referencia de rostros y personajes (Seedance 2.0)

​Ejemplo uno: Primer plano manteniendo la apariencia del personaje

​Ejemplo dos: Colocar a la misma persona en un nuevo escenario

​Callback asíncrono

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

Proceso de solicitud

Uso básico

Descripción de parámetros en línea

Generar video con audio

Generar el primer fotograma de un video a partir de una imagen

Generar el primer y último fotograma de un video a partir de imágenes

Referencia de rostros y personajes (Seedance 2.0)

Ejemplo uno: Primer plano manteniendo la apariencia del personaje

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

Callback asíncrono

Manejo de errores

Ejemplo de respuesta de error

Conclusión