A Practical Guide to Building Image Generation and Editing Workflows with Seedream

Image generation APIs are easy to demo and surprisingly easy to misuse in production: the hard part is choosing the right request shape, handling long-running jobs, and keeping your output pipeline predictable.

What you can do

The Seedream Images API on Ace Data Cloud exposes one main image endpoint, POST https://api.acedata.cloud/seedream/images. With the same endpoint you can generate an image from text, edit one or more input images, request URL or Base64 output, stream partial events for supported models, or run longer jobs asynchronously and poll the task later.

The main fields are model, prompt, image, size, response_format, watermark, output_format, stream, callback_url, and async. For basic text-to-image generation, the documentation also shows action with the value generate.

How it works

A basic call sends JSON to /seedream/images with accept: application/json, a bearer token, and content-type: application/json. The response includes success, task_id, trace_id, and a data list. Each generated image item can include prompt, size, and image_url.

Model choice matters. The default model in the documentation is doubao-seedream-5-0-lite-260128. Supported model strings include doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828. Use the full model string exactly; abbreviations such as doubao-seedream-5.0-lite return a 400.

Start with a minimal text-to-image request

For a first integration, keep the request deterministic and small. Pick a model, write a concrete prompt, and let the API return a hosted image URL before adding callbacks or streaming.

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"
  }'

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

Choose size and output deliberately

The size field accepts preset labels or pixel dimensions. 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. doubao-seedream-4-0-250828 supports 1K, 2K, and 4K.

If you use explicit dimensions, the default shown in the documentation is 2048x2048, but the valid pixel range varies by model. For output, response_format defaults to url and also supports b64_json. The output_format field supports jpeg and png on Seedream 5.0 Pro and 5.0 Lite, with jpeg as the default.

Edit images with the same endpoint

For editing, include image. The field supports URL or Base64 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)

Async, callbacks, and streaming

Generation can take around 1-2 minutes. With callback_url, the API returns task_id and later sends POST JSON to the callback. Without a public callback endpoint, pass async: true and poll /seedream/tasks with the returned task_id.

For supported Lite and 4.x models, stream: true uses accept: application/x-ndjson. Events include image_generation.partial_succeeded, image_generation.partial_failed, and one final image_generation.completed. Streaming cannot be combined with async or callback_url.

Advanced model paths

Seedream 5.0 Pro does not support sequential_image_generation, stream, or tools. It supports background for single-image editing; transparent requires PNG input with an alpha channel and output_format as png.

With layer_decomposition: true, Seedream 5.0 Pro can split one input image into one base image and up to 16 transparent PNG layers. Returned layers are ordered by z_index and can include name, description, bounding_box.absolute, and bounding_box.normalized.

A practical integration shape

In a real app, I would wrap the endpoint with three small pieces: a request builder that knows the selected model capabilities, a task store keyed by task_id, and a result reader that accepts either callback payloads or polling responses. The UI submits a prompt and optional image inputs, then watches your own job record until an image_url is available.

This makes failure handling less surprising. If a user chooses Seedream 5.0 Pro and asks for stream, your request builder can reject it before the API call. If a worker receives 429 too_many_requests, it can retry later without losing the prompt, model, or trace metadata.

Error handling

Plan for 400 token_mismatched, 400 api_not_implemented, 401 invalid_token, 429 too_many_requests, and 500 api_error. A useful client logs trace_id, stores task_id, validates model-specific fields before sending, and keeps long jobs outside synchronous request handlers.

Read the full source documentation here: Seedream Images API integration guide.