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 Mai 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, without needing 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 have 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 (also accepts the official alias doubao-seedream-5-0-lite-260128), doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. 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), or 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, supports URL or Base64 encoding. 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.
  • size: specifies the size information of the generated image, supports 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/1.5K/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. Method 2 | Specify the pixel values for the width and height of the generated image: default is 2048x2048, the total pixel and aspect ratio value range varies by model (for example, 5.0 Pro total pixel range [921600, 4624220], 5.0 Lite / 4.5 total pixel lower limit 3,686,400, 4.0 lower limit 921,600).
  • sequential_image_generation: group images: a set of related images generated based on your input. 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.
  • 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 doubao-seedream-5-0-pro-260628 and doubao-seedream-5-0-260128 support.
  • tools: configure the tools to be called by the model, currently supports web_search (online search). Only SeeDream 5.0 Lite supports.
  • 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 5.0 Pro single image editing supports. transparent requires input of a PNG with a transparent channel, and output_format must be png; opaque is a normal opaque background.
  • layer_decomposition: only 5.0 Pro supports. When set to true, a PNG/JPEG must be input, and prompt can be omitted for automatic decomposition, or elements can be specified in natural language/<bbox>; size supports auto/1K/1.5K/2K. This mode cannot be used with group images, streaming, online search, or background.
  • callback_url: the URL to receive callback results.
  • async: whether to process in asynchronous mode. When set to true, the interface immediately returns task_id, and there is no need to provide callback_url, then the result can be obtained by polling through /seedream/tasks.

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

Click the "Try" button to test, as shown in the above figure, we obtained the following result:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "一张真实感的工作室产品照片，展示一个磨砂玻璃香水瓶放在湿黑色板岩上，单个软箱主光源，水滴，黑暗阴郁的背景，85mm微距。",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

返回结果一共有多个字段，介绍如下：

  • success，当前视频生成任务的状态情况。
  • task_id，当前视频生成任务 ID。
  • trace_id，当前视频生成跟踪 ID。
  • data，当前图像生成任务的结果列表。
    • image_url，当前图片生成任务的链接。
    • prompt，提示词。
    • size: 生成图的像素

可以看到我们得到了满意的图片信息，我们只需要根据结果中 data 的图片链接地址获取生成的 SeeDream 图片即可。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

curl -X POST 'https://api.ai.moses.day/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": "一张真实感的工作室产品照片，展示一个磨砂玻璃香水瓶放在湿黑色板岩上，单个软箱主光源，水滴，黑暗阴郁的背景，85mm微距。"
}'

编辑图片任务

如果想对某张图片进行编辑的话， 首先参数image必须传入需要编辑的图片链接

  • model：此次编辑图片任务所采用的模型，doubao-seedream-5-0-pro-260628、doubao-seedream-5-0-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 均支持图片输入。
  • image：上传需要编辑的图片，一张或者多张

填写样例如下：

对应的代码：

import requests

url = "https://api.ai.moses.day/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "保持模型姿势和液体服装流动形状不变。将衣物材料从银色金属更改为完全透明的水（或玻璃）。通过液体流动，模型皮肤的细节可见。光影效果从反射转变为折射。",
  "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)

点击运行，可以发现会立即得到一个结果，如下：

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "保持模型姿势和液体服装流动形状不变。将衣物材料从银色金属更改为完全透明的水（或玻璃）。通过液体流动，模型皮肤的细节可见。光影效果从反射转变为折射。",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

可以看到，生成的效果是对原图片进行编辑的效果，结果与上文类似。

图层拆分（Seedream 5.0 Pro）

图层拆分会把一张输入图拆为 1 张底图和最多 16 个可独立编辑的透明 PNG 图层。以下请求让模型自动识别主要元素；如需指定元素，可增加 prompt，也可以在提示词中使用归一化 <bbox> 坐标。

curl -X POST 'https://api.ai.moses.day/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
}'

返回的 data 按 z_index 从底到顶排列。底图的 z_index 为 0；图层还包含 name、description 和 bounding_box.absolute/normalized。使用绝对坐标重组时，将图层缩放到 [right-left, bottom-top]，放到 [left, top]，再按 z_index 升序叠放。任一图层生成失败时整次拆分失败。

流式输出

Lite/4.x 设置 stream: true 时，请求头使用 accept: application/x-ndjson。接口逐行返回 image_generation.partial_succeeded 或 image_generation.partial_failed，最后返回唯一的 image_generation.completed 事件及最终 usage；只有完成事件触发一次计费。流式模式不能与 async 或 callback_url 同用。

异步回调

由于 SeeDream Images Generation API 生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

如果你没有可供回调的公网地址，也可以不指定 callback_url，而是在请求中设置 async 字段为 true。此时接口同样会立即返回 task_id，但不会推送结果，你需要携带该 task_id 调用 /seedream/tasks 接口轮询任务状态来获取最终结果。

下面我们通过示例来了解下具体怎样操作。

点击运行，可以发现会立即得到一个结果，如下：

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

内容如下：

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

You can see that the result contains a task_id field, and other fields are similar to the above text. This field can be used to associate tasks.

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 helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team.