> ## 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.
# SeeDream Images Generation API Integration Instructions
> ByteDance Seedream Image Generation integration guide - Ace Data Cloud
This article will introduce the integration instructions for the SeeDream Images Generation API, which can generate official SeeDream images by inputting custom parameters.
## Application Process
To use the SeeDream Images Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use.
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 completing this, you will be automatically returned to the current page.
**One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin).
> 📘 Complete Documentation: [SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)
## Basic Usage
First, understand the basic usage method, which involves inputting the prompt `prompt`, the generation action `action`, and the image size `size` to obtain the processed result. You first need to simply pass a field `action` with the value `generate`, and then we also need to input the prompt, as detailed below:
Here we can see that we have set the Request Headers, including:
* `accept`: The format of the response result you want to receive, filled in as `application/json`, which means JSON format.
* `authorization`: The key to call the API, which can be selected directly after application.
Additionally, we set the Request Body, including:
* `prompt`: The prompt.
* `model`: The generation model, default is `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite, latest). Supports `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828`, `doubao-seedream-3-0-t2i-250415`, `doubao-seededit-3-0-i2i-250628`. Among them, `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) is the flagship single image model, generating only a single image, **does not support group images (`sequential_image_generation`), streaming (`stream`), and online search (`tools`)**. **The `model` must pass the complete model string (e.g., `doubao-seedream-5-0-260128`), passing abbreviations like `doubao-seedream-5.0-lite` will return 400.**
* `image`: The input image information, supporting URL or Base64 encoding. Among them, `doubao-seedream-5-0-pro-260628` supports single or multiple image inputs (2-10 images, with charges starting from the second image), `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` support single or multiple image inputs, `doubao-seededit-3-0-i2i-250628` supports only single image input, and `doubao-seedream-3-0-t2i-250415` does not support this parameter.
* `size`: Specifies the size information of the generated image, supporting the following two methods, which cannot be mixed. Method 1 | Specify the resolution of the generated image and describe the aspect ratio in natural language in the prompt. **Different models support different presets**: `doubao-seedream-5-0-pro-260628` supports `1K`/`2K`; `doubao-seedream-5-0-260128` supports `2K`/`3K`/`4K`; `doubao-seedream-4-5-251128` only supports `2K`/`4K`; `doubao-seedream-4-0-250828` supports `1K`/`2K`/`4K`; `doubao-seedream-3-0-t2i-250415` and `doubao-seededit-3-0-i2i-250628` **do not support presets**, only accept Method 2. Method 2 | Specify the pixel values for the width and height of the generated image: default is `2048x2048`, the total pixel and aspect ratio range varies by model (for example, 5.0 Pro total pixel range \[921600, 4194304], 5.0 Lite / 4.5 total pixel lower limit 3,686,400, 4.0 lower limit 921,600, 3.0-t2i / seededit-3.0-i2i range \[512x512, 2048x2048]).
* `seed`: Random number seed used to control the randomness of the content generated by the model. The value range is \[-1, 2147483647]. **Only `doubao-seedream-3-0-t2i-250415` supports this parameter**.
* `sequential_image_generation`: Group images: a set of related images generated based on your input content. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` support this parameter, default is `disabled`.
* `stream`: Controls whether to enable streaming output mode. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` support this parameter, default is `false`.
* `guidance_scale`: The degree of consistency between the model output and the prompt, the larger the value, the stronger the correlation. Value range \[1, 10]. `doubao-seedream-3-0-t2i-250415` default value is 2.5, `doubao-seededit-3-0-i2i-250628` default value is 5.5, other models do not support.
* `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, supporting `jpeg` (default) and `png`. Only `doubao-seedream-5-0-pro-260628` and `doubao-seedream-5-0-260128` support.
* `tools`: Configures the tools the model will call, currently supporting `web_search` (online search). Only `doubao-seedream-5-0-260128` supports.
* `callback_url`: The URL to which the results need to be sent back.
* `async`: Whether to process in asynchronous mode. Set to `true` when the interface immediately returns `task_id`, no need to provide `callback_url`, and then poll for results through `/seedream/tasks`.
After selection, you can find that the corresponding code is also generated on the right side, as shown in the image:
Click the "Try" button to test, as shown in the image above, we obtained the following result:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
}
]
}
```
The return result has 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 image generation task at this time.
* `image_url`, the link to the image generation task at this time.
* `prompt`, the prompt word.
* `size`: the pixel size of the generated image.
It can be seen that we have obtained satisfactory image information, and we only need to obtain the generated SeeDream image based on the image link address in the `data` result.
Additionally, if you want to generate the corresponding integration code, you can directly copy the generation, for example, the CURL code is as follows:
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "doubao-seedream-5-0-260128",
"prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro."
}'
```
## Edit Image Task
If you want to edit a certain image, the parameter `image` must first pass in the link of the image to be edited.
* model: the model used for this image editing task, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` support single or multiple image inputs, `doubao-seededit-3-0-i2i-250628` only supports single image input.
* image: upload the image to be edited, one or more.
The sample format is as follows:
The corresponding code:
```python theme={null}
import requests
url = "https://api.acedata.cloud/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)
```
Clicking run, you can find that 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.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
It can be seen that the generated effect is the editing effect of the original image, and the result is similar to the above text.
## Asynchronous Callback
Since the SeeDream Images Generation API takes a relatively long time to generate, about 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption, so this API also provides support for asynchronous callbacks.
The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the generated image result will be sent to the client-specified `callback_url` in the form of POST JSON, which also includes the `task_id` field, so that the task result can be associated through the ID.
If you do not have a public address for callback, you can also not specify `callback_url`, but set the `async` field to `true` in the request. At this time, the interface will also immediately return `task_id`, but will not push the result, you need to carry the `task_id` to call the `/seedream/tasks` interface to poll the task status to obtain the final result.
Let's understand how to operate specifically through an example.
Clicking run, you can find that you will immediately get a result, as follows:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
The content is 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.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
It can be seen that the result contains a `task_id` field, and the other fields are similar to the above text, and the task can be associated through this field.
## 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 prompt words. We hope this document can help you better connect and use the API. If you have any questions, please feel free to contact our technical support team.