> ## 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.
# SeeDream Images Generation API Integration Guide
> ByteDance Seedream Image Generation 集成指南 - XHuoAPI
This document introduces the SeeDream Images Generation API integration guide, which allows you to generate official SeeDream images by inputting custom parameters.
## Application Process
To use the API, you need to apply for the corresponding service on the [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images) page. After entering the page, click the "Acquire" button, as shown below:
If you are not logged in or registered, you will be automatically redirected to the login page to register and log in. After logging in or registering, you will be automatically returned to the current page.
There is a free quota granted upon the first application, allowing you to use the API for free.
## Basic Usage
First, understand the basic usage method, which is to input the prompt `prompt`, generation action `action`, and image size `size` to get the processed result. You need to simply pass an `action` field with the value `generate`, and then input the prompt. The details are as follows:
Here you can see the Request Headers set, including:
* `accept`: The desired response format, here set to `application/json`, i.e., JSON format.
* `authorization`: The API key for calling the API, which can be selected from a dropdown after application.
Also, the Request Body includes:
* `prompt`: The prompt text.
* `model`: The generation model, default is `doubao-seedream-5.0-lite`. Supported models include `doubao-seedream-5.0-lite` (latest), `doubao-seedream-4.5`, `doubao-seedream-4.0`, `doubao-seedream-3.0-t2i`, and `doubao-seededit-3.0-i2i`.
* `image`: Input image information, supports URL or Base64 encoding. Among them, `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, and `doubao-seedream-4.0` support single or multiple image inputs, `doubao-seededit-3.0-i2i` supports only single image input, and `doubao-seedream-3.0-t2i` does not support this parameter.
* `size`: Specifies the size of the generated image, supporting two mutually exclusive methods. Method 1 | Specify the resolution of the generated image and describe the aspect ratio in natural language within the prompt. **Each model supports different presets**: `doubao-seedream-5.0-lite` supports `2K`/`3K`/`4K`; `doubao-seedream-4.5` supports only `2K`/`4K`; `doubao-seedream-4.0` supports `1K`/`2K`/`4K`; `doubao-seedream-3.0-t2i` and `doubao-seededit-3.0-i2i` **do not support presets**, only accept method 2. Method 2 | Specify the width and height in pixels: default is `2048x2048`. The total pixels and aspect ratio range vary by model (e.g., 5.0 / 4.5 minimum total pixels 3,686,400, 4.0 minimum 921,600, 3.0-t2i / seededit-3.0-i2i range \[512x512, 2048x2048]).
* `seed`: Random seed to control the randomness of the model output. Range is \[-1, 2147483647]. **Only supported by `doubao-seedream-3.0-t2i`**.
* `sequential_image_generation`: Group images: generates a set of related images based on your input content. Supported by `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, and `doubao-seedream-4.0`, default is `disabled`.
* `stream`: Controls whether to enable streaming output mode. Supported by `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, and `doubao-seedream-4.0`, default is `false`.
* `guidance_scale`: Degree of consistency between the model output and the prompt; higher values mean stronger relevance. Range \[1, 10]. Default is 2.5 for `doubao-seedream-3.0-t2i`, 5.5 for `doubao-seededit-3.0-i2i`, not supported by other models.
* `response_format`: Specifies the return format of the generated image. Default is `url`, also supports `b64_json`.
* `watermark`: Whether to add a watermark to the generated image. Default is `true`.
* `output_format`: Specifies the file format of the generated image, supports `jpeg` (default) and `png`. Only supported by `doubao-seedream-5.0-lite`.
* `tools`: Configures tools the model should call, currently supports `web_search` (online search). Only supported by `doubao-seedream-5.0-lite`.
* `callback_url`: URL for callback results.
After selection, you will see the corresponding code generated on the right side, as shown:
Click the "Try" button to test. As shown above, we get the following result:
```json theme={null}
{
"success": true,
"task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
"trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
"data": [
{
"prompt": "a white siamese cat",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
}
]
}
```
The returned result contains multiple fields, described as follows:
* `success`: The status of the image generation task.
* `task_id`: The ID of the image generation task.
* `trace_id`: The trace ID of the image generation.
* `data`: The list of image generation task results.
* `image_url`: The link to the generated image.
* `prompt`: The prompt text.
* `size`: The pixel size of the generated image.
You can see that we obtained satisfactory image information. We only need to retrieve the generated SeeDream image from the image link in the `data` field.
If you want to generate corresponding integration code, you can directly copy the generated code. For example, the CURL code is as follows:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "doubao-seedream-4-0-250828",
"prompt": "a white siamese cat"
}'
```
## Image Editing Task
If you want to edit an image, the parameter `image` must include the link of the image to be edited.
* model: The model used for this image editing task. `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, and `doubao-seedream-4.0` support single or multiple image inputs; `doubao-seededit-3.0-i2i` supports only single image input.
* image: Upload the image(s) to be edited, one or multiple.
Example input:
Corresponding code:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/flux/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
"image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
"size": "2K",
"watermark": False
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
After running, you will immediately get a result as follows:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
You can see that the generated effect is an edited version of the original image, similar to the previous results.
## Asynchronous Callback
Because the SeeDream Images Generation API takes relatively long to generate images, about 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, causing extra system resource consumption. Therefore, this API also supports asynchronous callbacks.
The overall process is: when the client initiates a request, it additionally specifies a `callback_url` field. After the client sends the API request, the API immediately returns a result containing a `task_id` field, representing the current task ID. When the task is completed, the generated image result will be sent via POST JSON to the client-specified `callback_url`, which also includes the `task_id` field, so the task result can be correlated by ID.
Let's understand the specific operation through an example.
After clicking run, you will immediately get a result as follows:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
Content example:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
You can see the result contains a `task_id` field, and other fields are similar to above. This field allows task correlation.
## 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 SeeDream Images Generation API to generate images by inputting prompts. We hope this guide helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team.