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

When an app needs images on demand, the hard part is usually not writing a prompt; it is turning generation, editing, long-running jobs, and error handling into a predictable workflow. The Seedream Images API on Ace Data Cloud gives you one endpoint for prompt-based generation and image editing, with optional asynchronous completion when requests may take longer than a normal HTTP round trip.

What you can do

The core endpoint is POST https://api.acedata.cloud/seedream/images. According to the integration document, it accepts a prompt for generation, can take one or more input images for editing, and returns either hosted image URLs or Base64 image data depending on response_format.

• Generate images from a prompt by setting action to generate.
• Edit an existing image by passing an image URL or Base64 input together with a transformation prompt.
• Choose a full model string such as doubao-seedream-5-0-260128; abbreviated model names are documented as invalid and may return a 400.
• Control output using size, watermark, output_format, and response_format.
• Use callback_url or async for long-running jobs, then associate results with the returned task_id.

How it works

A basic request uses JSON and standard bearer-token authentication. The documented headers are accept: application/json, authorization: Bearer ${token}, and content-type: application/json. For regular, non-streaming calls, the response contains success, task_id, trace_id, and a data array. Each item in data includes the returned prompt, size, and image_url.

The endpoint supports multiple model families documented in the guide, including doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828. The practical detail that matters for builders is that not every model supports every mode. For example, the 5.0 Pro model is described as a flagship single-image model and does not support group images through sequential_image_generation, streaming through stream, or online search through tools.

Start with a minimal generation request

For the first integration test, keep the payload small. Use a full model name, a clear prompt, and let the API default the rest where appropriate.

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 realistic studio product photo of a frosted glass perfume bottle on wet black slate, one softbox key light, water droplets, dark moody background, 85mm macro."
  }'

A successful response follows this shape:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "...",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/example.jpg"
    }
  ]
}

In production code, store both task_id and trace_id. The former lets you correlate asynchronous work; the latter is useful when you need to debug a failed or unexpected request.

Edit an existing image

Editing uses the same endpoint. The main difference is that image must contain the input image information, either as a URL or Base64. The guide shows that the supported Seedream models can accept image input, and the image field may be one image or multiple images depending on the selected model and mode.

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 subject pose and flowing garment shape unchanged. Change the material from silver metal to transparent water or glass, shifting the lighting 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 the pattern I would use for a CMS tool, product mockup editor, or internal creative review app: upload or reference the source asset, send a narrow edit instruction, then persist the returned image_url with the original asset ID.

Handle long-running jobs intentionally

The document notes that image generation can take about one to two minutes. Holding a client request open for that long is fragile, so the API supports two asynchronous patterns.

• Pass callback_url to receive the finished result as a POSTed JSON payload.
• Pass async: true without a callback, receive a task_id immediately, and poll /seedream/tasks for the final result.

Use callbacks when your backend has a stable public endpoint. Use polling when you are prototyping locally, running a worker, or building a queue processor where outbound polling is simpler than exposing an inbound webhook.

Know the model-specific switches before exposing them

Several parameters are powerful but should be surfaced carefully in a user-facing UI. size can be set as presets such as 1K, 1.5K, 2K, 3K, or 4K, but support varies by model. response_format defaults to url and also supports b64_json. output_format supports jpeg and png only on the documented 5.0 Pro and 5.0 Lite models.

There are also advanced modes. layer_decomposition is documented for Seedream 5.0 Pro and can split an input image into a base image plus up to 16 transparent PNG layers ordered by z_index. Streaming is available on Lite and 4.x models with stream: true, using accept: application/x-ndjson, and cannot be combined with async or callback_url.

Error handling

Do not treat failures as generic image-generation failures. The documented error shape includes 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. Log the trace_id, show users a retryable message only when appropriate, and avoid automatically resubmitting requests that may create duplicate work.

Putting it together

A good first production workflow is simple: validate the model string, keep generation and editing payloads explicit, store task_id and trace_id, and move long-running work to callbacks or polling. That gives you a stable foundation before you add UI controls for streaming, layer decomposition, transparent backgrounds, or multiple image inputs.

If you want the full parameter reference and examples, read the Seedream Images API integration guide.