SeeDream Images Generation API Integration Guide

This article introduces a SeeDream Images Generation API integration guide, which can generate official SeeDream images by entering custom parameters.

Application Process

To use the SeeDream Images Generation API, first go to the 知数云 Console to obtain your API Token and keep it for later use.

If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.

One API Token can call all services on the platform; there is no need to apply separately for each service. Your first application will include free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.

📘 Full documentation: SeeDream Images Generation API →

Basic Usage

First, let us understand the basic usage method: by entering the prompt prompt, generation action action, and image size size, you can obtain the processed result. First, you need to simply pass an action field with the value generate, and then you also need to enter a prompt. The specific content is as follows:

You can see that we have set the Request Headers here, including:

  • accept: The format of the response result you want to receive. Enter application/json here, which is JSON format.
  • authorization: The key for calling the API. After applying, you can directly select it from the dropdown.

Additionally, the Request Body has been set, including:

  • prompt: Prompt.
  • model: Generation model, default is doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, latest). Supports doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828. Among them, doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) is a flagship single-image model that only generates single images and does not support image groups (sequential_image_generation), streaming (stream), or web search (tools). model must be passed as the full model string (such as doubao-seedream-5-0-lite-260128); passing an abbreviation such as doubao-seedream-5.0-lite will return 400.
  • image: Input image information, supporting URL or Base64 encoding. doubao-seedream-5-0-pro-260628 supports single-image or multi-image input (up to 10 images), while doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 support single-image or multi-image input.
  • size: Specifies the size information of the generated image. The following two methods are supported and cannot be mixed. Method 1 | Specify the resolution of the generated image and describe the image aspect ratio in natural language in the prompt. The presets supported by each model differ: doubao-seedream-5-0-pro-260628 supports 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 supports 2K/3K/4K; doubao-seedream-4-5-251128 only supports 2K/4K; doubao-seedream-4-0-250828 supports 1K/2K/4K. Method 2 | Specify the width and height pixel values of the generated image: the default is 2048x2048; the total pixel and aspect ratio value ranges vary by model (for example, the total pixel range for 5.0 Pro is [921600, 4624220], the lower limit for 5.0 Lite / 4.5 is 3,686,400, and the lower limit for 4.0 is 921,600).
  • sequential_image_generation: Image group: generates a group of content-related images based on the content you enter. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 support this parameter, with the default being disabled.
  • stream: Controls whether to enable streaming output mode. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 support this parameter, with the default being false.
  • response_format: Specifies the return format of the generated image. The default is url, and b64_json is also supported.
  • watermark: Whether to add a watermark to the generated image. The 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-pro-260628 and doubao-seedream-5-0-lite-260128.
  • tools: Configures the tools to be called by the model. Currently supports web_search (web search). Only supported by Seedream 5.0 Lite.
  • optimize_prompt_options: Prompt optimization configuration. 5.0 Pro supports standard/fast; 5.0 Lite and 4.5 only support standard; 4.0 supports standard/fast.
  • background: Only supported for 5.0 Pro single-image editing. transparent requires inputting a PNG with an alpha channel, and output_format must be png; opaque is a standard opaque background.
  • layer_decomposition: Only supported by 5.0 Pro. When set to true, a PNG/JPEG must be input. You can omit prompt for automatic decomposition, or specify elements using natural language/<bbox>; size supports auto/1K/1.5K/2K. This mode cannot be used together with image groups, streaming, web search, or background.
  • callback_url: The URL that requires callback results.
  • async: Whether to process in asynchronous mode. When set to true, the API immediately returns a task_id; there is no need to provide callback_url, and then retrieve the result by polling through /seedream/tasks.

After selection, you can find that the corresponding code is also generated on the right, as shown in the image:

Click the “Try” button to test. As shown in the image above, we obtained the following result here:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/db93b46e-c302-4676-8a11-63f0ba638a27.jpg"
    }
  ]
}

There are multiple fields in the returned result, 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 of the image generation task at this time.
    • prompt, the prompt.
    • size: the pixels of the generated image

It can be seen that we have obtained satisfactory image information. We only need to obtain the generated SeeDream image according to the image link address in data in the result.

In addition, if you want to generate the corresponding integration code, you can directly copy and generate it. For example, the CURL code is as follows:

curl -X POST 'https://xapi.zhishuyun.com/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Image Editing Task

If you want to edit an image, first, the parameter image must pass in the link of the image that needs to be edited.

  • model: the model used for this image editing task. doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 all support image input.
  • image: upload one or more images that need to be edited

An example is as follows:

The corresponding code:

import requests

url = "https://xapi.zhishuyun.com/seedream/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)

Click Run, and you can find that a result is obtained immediately, as follows:

{
    "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 an edit of the original image, and the result is similar to the above.

Layer Decomposition (Seedream 5.0 Pro)

Layer decomposition splits one input image into 1 base image and up to 16 independently editable transparent PNG layers. The following request lets the model automatically identify the main elements; if you need to specify elements, you can add prompt, and you can also use normalized <bbox> coordinates in the prompt.

curl -X POST 'https://xapi.zhishuyun.com/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

The returned data is arranged from bottom to top by z_index. The z_index of the base image is 0; layers also include name, description, and bounding_box.absolute/normalized. When recomposing using absolute coordinates, scale the layer to [right-left, bottom-top], place it at [left, top], and then stack them in ascending order of z_index. If any layer fails to generate, the entire decomposition fails.

Streaming Output

When Lite/4.x sets stream: true, use accept: application/x-ndjson for the request header. The interface returns image_generation.partial_succeeded or image_generation.partial_failed line by line, and finally returns the only image_generation.completed event and the final usage; only the completion event triggers billing once. Streaming mode cannot be used together with async or callback_url.

Asynchronous Callback

Since the generation time of the SeeDream Images Generation API is relatively long, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, resulting in additional system resource consumption, so this API also provides support for asynchronous callbacks.

The overall process is: when the client initiates a request, it additionally specifies a callback_url field. After the client initiates the API request, the API immediately returns a result containing a task_id field, representing the current task ID. After the task is completed, the result of the generated image will be sent in the form of POST JSON to the callback_url specified by the client, 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 network address available for callbacks, you can also omit callback_url and instead 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 and obtain the final result.

Below, we will learn about the specific operation through an example.

Click Run, and you can find that a result is obtained immediately, as follows:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

The content is as follows:

{
    "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 there is a task_id field in the result. The other fields are similar to those above, and task association can be achieved 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

{
  "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 entering prompts. 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.