> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Instrucciones de integración de la API de generación de videos de 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 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](https://platform.acedata.cloud/console/applications) 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](https://platform.acedata.cloud/console/coin).
> 📘 Documentación completa: [API de generación de videos de SeeDance →](https://platform.acedata.cloud/documents/seedance-videos)
## 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:
```json theme={null}
{
"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:
```shell theme={null}
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`:
```json theme={null}
{
"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:
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```json theme={null}
{
"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
```json theme={null}
{
"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.