Skip to main content
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 API, you need to first apply for the corresponding service on the SeeDream Images Generation API 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 involves inputting the prompt prompt, the 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 API key for calling the API, which can be directly selected after application.
Additionally, we have set the Request Body, including:
  • prompt: The prompt.
  • model: The generation model, defaulting to doubao-seedream-4.0.
  • image: The input image information, supporting URL or Base64 encoding. Among them, doubao-seedream-4.5, doubao-seedream-4.0 support single or multiple image inputs, while doubao-seededit-3.0-i2i only supports single image input, and doubao-seededit-3.0-t2i 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 image aspect ratio, shape, or purpose in natural language in the prompt, with the model ultimately determining the size of the generated image. Method 2 | Specify the pixel values for the width and height of the generated image: default value: 2048x2048, which varies based on the model.
  • seed: Random number seed used to control the randomness of the content generated by the model. The range is [-1, 2147483647]. Only doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i support this parameter.
  • sequential_image_generation: Group images: a set of related images generated based on your input. Only doubao-seedream-4.5, doubao-seedream-4.0 support this parameter, defaulting to disabled.
  • stream: Controls whether to enable streaming output mode. Only doubao-seedream-4.5, doubao-seedream-4.0 support this parameter, defaulting to false.
  • guidance_scale: The degree of consistency between the model output and the prompt, the degree of freedom in generating images, also known as text weight; the larger the value, the smaller the model’s degree of freedom, and the stronger the correlation with the user’s input prompt. The range is [1, 10]. doubao-seedream-3.0-t2i default value is 2.5, doubao-seededit-3.0-i2i default value is 5.5, others do not support.
  • response_format: Specifies the return format of the generated image. The default is url, and it also supports b64_json.
  • watermark: Whether to add a watermark to the generated image. The default is true.
  • callback_url: The URL to which the result needs to be sent back.
After selection, you can see that the corresponding code is generated on the right side, as shown in the image below:

Click the “Try” button to test, as shown in the image above, and we get the following result: 
{
  "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.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
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 image generation task at this time.
    • image_url: The link to the image generation task at this time.
    • prompt: The prompt.
    • size: The pixel size of the generated image.
We can see that we have obtained satisfactory image information, and we only need to retrieve the generated SeeDream image using the image link address from the data in the result. Additionally, if you want to generate the corresponding integration code, you can directly copy the generated code, 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-4-0-250828",
  "prompt": "a white siamese cat"
}'

​
Edit Image Task

If you want to edit a specific 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, which currently supports doubao-seedream-4.5, doubao-seedream-4.0 for single or multiple image inputs, and doubao-seededit-3.0-i2i only supports single image input.
  • image: Upload the image(s) that need to be edited, either one or multiple.
The sample input 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 will find that a result will be 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 edited effect of the original image, and the result is similar to the above text.

​
Asynchronous Callback

Due to the relatively long generation time of the SeeDream Images Generation API, which takes 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. Therefore, 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, 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 a POST JSON, which also includes the task_id field, allowing the task result to be associated by ID. 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. 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 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.