A Practical Guide to Building Image Workflows with the Seedream Images API

When you add AI image generation to a product, the hard part is rarely the first prompt. The real work is deciding how a user request becomes a reproducible API call, how edits are represented, and how long-running jobs are handled without blocking your app.

What you can do

The Seedream Images API gives builders one endpoint for several common image workflows: text-to-image generation, image editing with one or more input images, optional asynchronous processing, streaming output for supported models, and layer decomposition for Seedream 5.0 Pro.

The core endpoint is POST https://api.acedata.cloud/seedream/images. Requests use JSON, and the basic headers are accept: application/json, authorization: Bearer YOUR_API_TOKEN, and content-type: application/json. The key request fields are prompt, model, image, size, response_format, watermark, async, and callback_url.

How it works

A minimal generation request passes action as generate, uses a full model string, and includes a natural-language prompt. The model name must be complete, for example doubao-seedream-5-0-lite-260128; shortened names such as doubao-seedream-5.0-lite return a 400.

The response includes success, task_id, trace_id, and a data list. Each item can contain the final image_url, the prompt, and the generated size. That shape is practical: save task_id for job state, keep trace_id for debugging, and expose image_url to the user.

Choosing a model and size

The API supports doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828. Their capabilities differ, so choose the model based on workflow.

• doubao-seedream-5-0-pro-260628 is a flagship single-image model. It only generates single images and does not support sequential_image_generation, stream, or tools.
• doubao-seedream-5-0-lite-260128 supports tools with web_search, plus image groups and streaming.
• response_format defaults to url, with b64_json also supported.
• watermark defaults to true.

For size, you can use named resolution options or explicit pixel dimensions. Seedream 5.0 Pro supports 1K, 1.5K, and 2K; Seedream 5.0 Lite supports 2K, 3K, and 4K; Seedream 4.5 supports 2K and 4K; Seedream 4.0 supports 1K, 2K, and 4K.

A minimal generation request

Here is a small request you can paste into a terminal once your token is available. It uses the documented Lite model and asks the API to return JSON containing a URL.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_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",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }'

A successful response follows this pattern:

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

Editing existing images

For image editing, include the image field with a URL or an array of URLs. The documented models support single-image or multi-image input, and Seedream 5.0 Pro supports up to 10 input images. A useful product pattern is to store the original image URL, collect the edit instruction as prompt, and persist both the original and generated image_url so the user can compare versions.

import requests

url = "https://api.acedata.cloud/seedream/images"
headers = {
    "accept": "application/json",
    "authorization": "Bearer YOUR_API_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)

Handling long-running jobs

Image generation can take about 1–2 minutes. If you do not want a client request to stay open, pass callback_url and the API immediately returns a task_id, then POSTs the final JSON result to your callback when the task completes. If you do not have a public callback endpoint, use async as true and poll /seedream/tasks with the returned task_id.

For streaming, supported Lite and 4.x models can use stream: true and accept: application/x-ndjson. The API returns line-by-line events such as image_generation.partial_succeeded or image_generation.partial_failed, followed by one final image_generation.completed event and final usage. Streaming cannot be used together with async or callback_url.

What to log before shipping

At minimum, log task_id, trace_id, model, size, and the final image_url. For failures, the documented error format is success: false with an error.code, 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.

If you are building an image feature rather than a one-off demo, start with one model, one size option, and one synchronous request. Then add async polling or callbacks once you know where the generated image should live in your own product flow. The full reference is available in the Seedream Images API integration guide.