> ## 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 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](https://platform.acedata.cloud/console/applications) 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](https://platform.acedata.cloud/console/coin).
> 📘 Documentación completa: [API de generación de videos 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`; 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:
```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 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:
```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 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`:
```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 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:
```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 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:
```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`) 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:
```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, 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:
```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 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:
```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 devuelto 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 "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.
```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 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
```json theme={null}
{
"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.