> ## 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.
# SeeDance Videos Generation API Integration Instructions
> ByteDance Seedance Video Generation 集成指南 - XHuoAPI
This document will introduce the SeeDance Videos Generation API integration instructions, which can generate official SeeDance videos by inputting custom parameters.
## Application Process
To use the API, you need to first apply for the corresponding service on the [SeeDance Videos Generation API](https://api.xhuoapi.ai/documents/seedance-videos) page. After entering the page, click the "Acquire" button, as shown in the image below:
If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.
There is a free quota available for first-time applicants, allowing you to use the API for free.
## Basic Usage
First, understand the basic usage method, which is to input the prompt `content.text`, type `content.type=text`, and model `model` to obtain the processed result. The specific content is as follows:
Here we can see that we have set the Request Headers, including:
* `accept`: the format of the response result you want to receive, here filled in as `application/json`, which means JSON format.
* `authorization`: the key to call the API, which can be selected directly after application.
Additionally, the Request Body is set, including:
* `model`: the model for generating videos, optional values: `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`: an array of input content, `type` can be `text` or `image_url`.
* `resolution`: output resolution, optional `480p` / `720p` / `1080p`.
* `ratio`: aspect ratio, optional `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`.
* `duration`: video duration (seconds), range 2–12.
* `seed`: random seed, integer, -1 to 4294967295.
* `camerafixed`: whether to fix the camera, `true` / `false`.
* `watermark`: whether to add a watermark, `true` / `false`.
* `generate_audio`: whether to generate a video with sound, `true` / `false`, **only `doubao-seedance-1-5-pro-251215` supports**.
* `service_tier`: inference mode, `default` (online) or `flex` (offline, priced at 50% of online).
* `return_last_frame`: whether to return the URL of the last frame image in the result.
* `execution_expires_after`: task timeout (seconds), range 3600–259200.
* `callback_url`: asynchronous callback address, after setting, the API will immediately return `task_id`, and when the task is completed, it will POST the result to this address.
After selection, you can find that the corresponding code is also generated on the right side, as shown in the image below:
Click the "Try" button to test, as shown in the above image, we obtained the following result:
```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"
}
}
```
The returned result contains multiple fields, described as follows:
* `success`, the status of the video generation task at this time.
* `task_id`, the ID of the video generation task at this time.
* `trace_id`, the tracking ID of the video generation at this time.
* `data`, the result list of the video generation task at this time.
* `task_id`, the server-side ID of the video generation task at this time.
* `video_url`, the video link of the video generation task at this time.
* `status`, the status of the video generation task at this time.
* `model`, the model used to generate the video.
We can see that we have obtained satisfactory video information, and we only need to access the generated SeeDance video using the video link address in `data`.
Additionally, if you want to generate the corresponding integration code, you can directly copy it, for example, the CURL code is as follows:
```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"
}'
```
## Inline Parameter Description
At the end of the `content[].text` prompt, you can pass in generation parameters in the form of `--parameter value` (old method, weak validation, defaults will be used if filled incorrectly). The complete parameter list is as follows:
| Inline Parameter | Corresponding Field | Description | Value Range |
| ---------------- | ------------------- | -------------------------- | ------------------------------------------------------------- |
| `--rs` | `resolution` | Output resolution | `480p` / `720p` / `1080p` |
| `--rt` | `ratio` | Aspect ratio | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` |
| `--dur` | `duration` | Video duration (seconds) | 2–12 |
| `--frames` | `frames` | Number of video frames | Integers satisfying 25+4n in \[29, 289] |
| `--fps` | `framespersecond` | Frame rate | Only supports `24` |
| `--seed` | `seed` | Random seed | -1 to 4294967295 |
| `--cf` | `camerafixed` | Whether to fix the camera | `true` / `false` |
| `--wm` | `watermark` | Whether to add a watermark | `true` / `false` |
> **Recommended Practice**: Directly use the corresponding top-level fields (such as `resolution`, `ratio`, etc.) in the Request Body for strong validation mode. If parameters are filled incorrectly, clear error messages will be returned, making it easier to troubleshoot issues.
## Generating Videos with Sound
`doubao-seedance-1-5-pro-251215` supports generating videos with audio through the `generate_audio` parameter:
```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
}
```
Other models do not support this parameter, and it will be ignored if passed in.
## Image to Video First Frame
If you want to perform the image to video task, the `content` parameter must first include an item with `type` as `image_url`, and the `image_url` field must be in object format: `{"url": "https://..."}` or Base64 format `{"url": "data:image/png;base64,..."}`.
> **Note**: `image_url` does not support being passed in string format (e.g., `"image_url": "https://..."`), it must use object format `"image_url": {"url": "https://..."}`, otherwise a 400 error will be returned.
Corresponding code:
```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": "A girl holds a fox in her arms. She opens her eyes and gazes tenderly at the camera, while the fox affectionately holds her back. As the camera slowly pulls away, her hair is gently blown by the wind. --ratio adaptive --dur 5"
}
],
"model": "doubao-seedance-1-0-pro-250528"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Clicking run, you will find that you will immediately get a result as follows:
```
{
"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"
}
}
```
As you can see, the generated effect is image to video, and the result is similar to the above.
## Image to Video First and Last Frame
If you want to perform the image to video first and last frame, the `content` parameter must first include the type `image_url`, and set `role` to `first_frame` and `last_frame` respectively, to specify the following content:
* role: specify the first frame or last frame.
* image\_url
* url image link
At the same time, `content` also needs to input type `text` as a prompt.
Corresponding code:
```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": "360-degree shot"
},
{
"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)
```
Clicking run, you will find that you will immediately get a result as follows:
```
{
"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"
}
}
```
As you can see, the generated effect is character generated video, and the result is similar to the above.
## Asynchronous Callback
Since the SeeDance Videos Generation API takes a long time to generate (about 1-2 minutes), you can use the `callback_url` field to use asynchronous mode, avoiding long HTTP connection occupation.
Overall process: When the client initiates a request, specify the `callback_url`, the API immediately returns a response containing the `task_id`; after the task is completed, the platform will send the generated result to the `callback_url` in POST JSON format, and the result also contains the `task_id` for association.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
When the task is completed, the content pushed to the `callback_url` by the platform is as follows:
```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"
}
}
```
The `task_id` field in the result is consistent with the one returned during the request, and this field can be used to associate the task.
## Error Handling
When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:
* `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters.
* `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters.
* `401 invalid_token`: Unauthorized, invalid or missing authorization token.
* `429 too_many_requests`: Too many requests, you have exceeded the rate limit.
* `500 api_error`: Internal server error, something went wrong on the server.
### Error Response Example
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusion
Through this document, you have learned how to use the SeeDance Videos Generation API to generate videos by inputting prompt words and reference images. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.