> ## Documentation Index
> Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/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 集成指南 - Ace Data Cloud
Este documento presentará una guía 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, primero debe ir a la página correspondiente de [API de generación de videos de SeeDance](https://platform.acedata.cloud/documents/seedance-videos) para solicitar el servicio correspondiente. Una vez en la página, haga clic en el botón "Acquire", como se muestra en la imagen:
Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión que le invita a registrarse e iniciar sesión. Después de iniciar sesión o registrarse, será redirigido automáticamente a la página actual.
En la primera solicitud, se le otorgará un crédito gratuito que le permitirá utilizar la API de forma gratuita.
## Uso básico
Primero, comprenda 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 Request Headers, que incluyen:
* `accept`: el formato de respuesta que desea recibir, aquí se establece como `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API, que puede seleccionarse directamente después de la solicitud.
Además, se ha configurado el Request Body, que incluye:
* `model`: el modelo para generar el video, los valores opcionales son: `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`.
* `content`: un array de contenido de entrada, `type` puede ser `text` o `image_url`.
* `resolution`: la resolución de salida, puede ser `480p` / `720p` / `1080p`.
* `ratio`: la relación de aspecto, puede ser `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`.
* `duration`: duración del video (segundos), rango de 2 a 12.
* `seed`: semilla aleatoria, entero, de -1 a 4294967295.
* `camerafixed`: si la cámara está fija, `true` / `false`.
* `watermark`: si se agrega 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**.
* `service_tier`: modo de inferencia, `default` (en línea) o `flex` (fuera de línea, el precio es el 50% del en línea).
* `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 de 3600 a 259200.
* `callback_url`: dirección de callback asíncrono, después de configurarla, la API devolverá inmediatamente `task_id`, y cuando la tarea esté completa, enviará el resultado a esa dirección.
Después de seleccionar, puede ver que a la derecha también se ha generado el código correspondiente, como se muestra en la imagen:
Haga clic en el botón "Try" para realizar una prueba, como se muestra en la imagen anterior, y aquí obtuvimos el siguiente resultado:
```json theme={null}
{
"success": true,
"task_id": "ec22ae22-0140-4033-8c86-a48b536da595",
"trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
"data": {
"task_id": "cgt-20251222005129-62fhb",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
El resultado devuelto tiene varios campos, que se describen a continuación:
* `success`, el estado de la tarea de generación de video en este momento.
* `task_id`, el ID de la tarea de generación de video en este momento.
* `trace_id`, el ID de seguimiento de la generación de video en este momento.
* `data`, la lista de resultados de la tarea de generación de video en este momento.
* `task_id`, el ID del lado del servidor de la tarea de generación de video en este momento.
* `video_url`, el enlace del video de la tarea de generación de video en este momento.
* `status`, el estado de la tarea de generación de video en este 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 desea generar el código de integración correspondiente, puede 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": [{"text":"A kitten yawning at the camera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
"model": "doubao-seedance-1-0-pro-250528"
}'
```
## Descripción de parámetros en línea
En el final de la palabra clave `content[].text`, puede pasar parámetros de generación mediante la adición de `--parameter value` (método antiguo, verificación débil, si se ingresan incorrectamente, se utilizarán valores predeterminados automáticamente). 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 soporta `24` |
| `--seed` | `seed` | Semilla aleatoria | -1 a 4294967295 |
| `--cf` | `camerafixed` | Si la cámara está fija | `true` / `false` |
| `--wm` | `watermark` | Si se agrega una marca de agua | `true` / `false` |
> **Práctica recomendada**: use directamente los campos de nivel superior correspondientes en el Request Body (como `resolution`, `ratio`, etc.), para un modo de verificación fuerte, si hay un error en los parámetros, 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": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 5
}
```
其他模型 no soportan este parámetro, se ignorará si se pasa.
## Generación de video a partir de imagen - primer fotograma
Si desea realizar la tarea de generación de video a partir de imagen, primero el parámetro `content` debe incluir un elemento con `type` igual a `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 el paso directo en formato de cadena (como `"image_url": "https://..."`), debe utilizar el 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 abraza con cariño. A medida que la cámara se aleja lentamente, su cabello es suavemente agitado 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 la imagen, el resultado es similar al anterior.
## Generación de video a partir de imagen - primer y último fotograma
Si desea realizar la tarea de generación de video a partir de imagen para el primer y último fotograma, primero el parámetro `content` debe incluir el tipo `image_url`, y debe establecer `role` como `first_frame` y `last_frame`, para 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 el 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 generación de personajes, el resultado es similar al anterior.
## Callback asíncrono
Debido a que la API de generación de videos SeeDance tiene un tiempo de generación largo (aproximadamente 1-2 minutos), se 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 el resultado también incluirá `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 el resultado es el mismo que el devuelto al realizar la solicitud, y se puede utilizar este campo para asociar 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": "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 SeeDance para generar videos mediante la entrada de palabras clave y imágenes de referencia. 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.