> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/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 集成指南 - XHuoAPI
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://api.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/v1/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.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/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.xhuoapi.ai/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.