SeeDream Images Generation API Integration Instructions

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 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.

📘 Complete Documentation: SeeDream Images Generation API →

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:

{
  "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:

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:

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:

{
    "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:

{
    "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

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