How to Build a Seedream Image API Workflow (Beginner's Guide)

Generating one image from a prompt is easy; turning that call into a dependable product workflow is where the real engineering begins.

This guide builds the smallest useful Seedream image pipeline: send a request, read the returned image, and switch to asynchronous processing when a synchronous HTTP connection is the wrong trade-off. I’ll also show how the same endpoint accepts an input image for editing.

What you can build

Ace Data Cloud exposes the image operation at:

POST https://api.acedata.cloud/seedream/images

Requests use JSON and a bearer token in the authorization header. The core fields are deliberately straightforward:

• action: use generate for text-to-image generation.
• model: pass the complete model string, not an abbreviation.
• prompt: describe the image or the edit you want.
• image: provide one or more source image URLs when using a model that supports image input.
• size: choose a supported preset or an explicit width and height, depending on the model.
• response_format: url by default, or b64_json.
• async: return a task_id immediately and let your application poll for completion.
• callback_url: receive the completed result as a POST request when you have a public webhook.

For a practical starting point, this tutorial uses doubao-seedream-5-0-260128. The full identifier matters: an abbreviated value such as doubao-seedream-5.0-lite is not accepted.

Make the first generation request

Start with a narrow prompt that describes the subject, surface, lighting, background, and lens. That makes the request easier to reproduce than a vague style-only prompt.

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-260128",
    "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro."
  }'

A successful completed response includes success, task_id, trace_id, and a data list. Each result in data contains the effective prompt, the output size, and an image_url.

In application code, avoid assuming that data[0] always exists. Check success, verify that data is non-empty, and retain trace_id in your logs. That identifier is especially useful when a request succeeds at the HTTP layer but produces an unexpected API result.

Choose the model and size intentionally

The model name controls more than output quality. It also controls which parameters are valid.

For example, doubao-seedream-5-0-260128 supports image input, group-image generation through sequential_image_generation, streaming through stream, and the web_search tool. Its size presets are 2K, 3K, and 4K, and it can also return jpeg or png through output_format.

By contrast, doubao-seedream-5-0-pro-260628 is a flagship single-image model. It accepts one or multiple source images, but it does not support sequential_image_generation, stream, or tools. Its supported presets are 1K and 2K.

This distinction is worth encoding in your own validation layer. Reject an unsupported combination before sending it over the network. A small per-model capability map will produce clearer errors for your users and save unnecessary requests.

Turn generation into an async workflow

Image generation can take roughly one to two minutes. Keeping an HTTP connection open for that entire period may be acceptable in a script, but it is often a poor fit for a web request or job runner.

There are two supported patterns:

1. Add callback_url to the generation request. The API returns a task_id, then POSTs the completed JSON result to your public callback.
2. Set async to true without a callback. The API returns a task_id, and your worker polls /seedream/tasks for the final result.

A resilient implementation stores the task ID before doing anything else. If you use callbacks, make the handler idempotent: receiving the same completion twice should update the same record rather than create duplicate assets. If you poll, use a delay between checks and stop on a terminal success or error instead of polling indefinitely.

Keep trace_id alongside your internal job ID and the returned task_id. Those three values give you a clean path from a user action to your queue record and then to the upstream request.

Reuse the endpoint for image editing

Editing uses the same /seedream/images endpoint. The important change is supplying image with the source URL or URLs and writing the prompt as an instruction rather than a fresh scene description.

{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "Keep the bottle shape and camera angle unchanged. Replace the black slate with pale limestone and shift the lighting to a soft morning window light.",
  "image": ["https://example.com/source-image.png"],
  "size": "2K",
  "watermark": false
}

Use source URLs that your API worker can reach. Also validate the number of inputs against the selected model: Seedream 5.0 Lite supports multiple image inputs, while doubao-seededit-3-0-i2i-250628 accepts only one.

The practical lesson is simple: start with a synchronous curl request so you can inspect the full response, then add model-aware validation and async task handling before placing the workflow behind a user-facing endpoint. That progression keeps the first experiment small without pretending production concerns do not exist.

For the complete parameter matrix and response examples, keep the Seedream Images API integration reference beside your implementation.