How to Build a Practical Image Generation and Editing Workflow with SeeDream

Image generation becomes much easier to ship when you treat it like a small workflow: validate the prompt, choose the right model, decide whether the result should be synchronous or async, and store the returned image URL with enough metadata to debug later.

What you can do

The SeeDream Images API on Ace Data Cloud exposes one main endpoint, POST https://api.acedata.cloud/seedream/images, for both image generation and image editing. The same API can return generated image URLs, accept one or more input images for editing, run longer jobs asynchronously, stream partial generation events for supported models, and perform layer decomposition with Seedream 5.0 Pro.

The most useful mental model is simple:

• Use action: generate with a text prompt when you are creating a new image from scratch.
• Add image when the task is editing or transforming an existing image.
• Use async: true when you do not want to keep an HTTP request open for a generation that may take roughly 1-2 minutes.
• Use response_format: url when your app wants a hosted image URL, or b64_json when it needs the image payload directly.

How it works

Every request should send JSON and include two headers: accept: application/json and authorization: Bearer TOKEN. For standard calls, the response contains success, task_id, trace_id, and a data list. Each item in data can include the final image_url, the resolved prompt, and the generated size.

The model value should be the full model string. The documentation calls out that abbreviations such as doubao-seedream-5.0-lite are invalid and can return a 400. Valid examples include doubao-seedream-5-0-lite-260128, doubao-seedream-5-0-pro-260628, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828.

Start with a small generation request

For a first integration, keep the payload minimal. The example below asks SeeDream 5.0 Lite to generate a simple studio object. Notice that the request does not need a callback or polling loop yet; it is the shortest useful shape for testing credentials, JSON formatting, and response parsing.

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-lite-260128",
    "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
    "response_format": "url",
    "watermark": false
  }'

A successful response follows this shape:

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

In an application, I would store task_id, trace_id, prompt, size, and image_url. The image URL is what you show to the user, while the task and trace IDs are what you want in logs when a user reports that a generation looked wrong.

Choose the model and size deliberately

The API supports several model strings, and the supported size presets differ by model. doubao-seedream-5-0-pro-260628 supports 1K, 1.5K, and 2K. doubao-seedream-5-0-lite-260128 supports 2K, 3K, and 4K. doubao-seedream-4-5-251128 supports 2K and 4K, while doubao-seedream-4-0-250828 supports 1K, 2K, and 4K.

You can also provide explicit width and height such as 2048x2048. The documented default is 2048x2048, but pixel ranges and aspect-ratio constraints vary by model. In practice, I start with a preset while prototyping, then move to explicit dimensions only after the product surface is stable.

Edit existing images with the same endpoint

For editing, add the image parameter and describe the transformation in prompt. The image field supports URL or Base64 input, and the documented models support single-image or multi-image input. Seedream 5.0 Pro supports up to 10 input images.

import requests

url = "https://api.acedata.cloud/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)

This is a useful pattern for internal tools: let a designer paste an image URL, choose a controlled transformation, and keep all generated outputs tied to the original asset.

Use async or streaming when the UX needs it

If your app cannot wait on a long-running HTTP request, set async: true. The API immediately returns a task_id, and your backend can poll /seedream/tasks for the final result. If you do have a public callback endpoint, you can pass callback_url and receive the completed result as a POST JSON payload that includes the same task_id.

For Lite and 4.x models, stream: true is another option. In that mode, the request should use accept: application/x-ndjson. The API returns line-by-line events such as image_generation.partial_succeeded, image_generation.partial_failed, and a final image_generation.completed event. Streaming cannot be combined with async or callback_url.

Know the sharp edges before production

• doubao-seedream-5-0-pro-260628 is a flagship single-image model and does not support sequential_image_generation, stream, or tools.
• tools currently supports web_search, and only Seedream 5.0 Lite supports it.
• output_format supports jpeg and png, but only for Seedream 5.0 Pro and 5.0 Lite.
• background is only for 5.0 Pro single-image editing. For transparent, the input must be a PNG with an alpha channel and output_format must be png.
• layer_decomposition: true is only supported by 5.0 Pro and returns a base image plus up to 16 transparent PNG layers arranged by z_index.

For error handling, branch on the documented error shape: success: false, an error.code, an error.message, and trace_id. Common codes include 400 token_mismatched, 400 api_not_implemented, 401 invalid_token, 429 too_many_requests, and 500 api_error.

Wrap-up

The practical path is to start with POST /seedream/images, store the returned task metadata, then add editing, async polling, streaming, or layer decomposition only when your product flow actually needs them. That keeps the integration small, testable, and easy to debug. The full reference is available in the SeeDream Images Generation API integration guide.