How to Build an Image Generation and Editing Workflow with the Seedream Images API

How to Build an Image Generation and Editing Workflow with the Seedream Images API

If your product needs image generation, image-to-image editing, and reliable job handling, the hard part is not writing one prompt—it is designing a workflow that survives long-running requests, model differences, and output formats.

What you can do

The Seedream Images API gives you one main endpoint, POST /seedream/images, for several practical image workflows. According to the public integration guide, you can send a text prompt for image generation, provide an image URL or Base64 input for editing, request a specific size, choose a supported model, and decide whether the response should return an image url or b64_json.

For builder workflows, the useful part is that the same endpoint also covers more advanced patterns: asynchronous jobs with async, callbacks with callback_url, streaming output with stream, and Seedream 5.0 Pro layer decomposition with layer_decomposition.

How it works

A basic request is a JSON payload sent to https://api.acedata.cloud/seedream/images. The required headers are simple: accept: application/json, authorization: Bearer YOUR_API_KEY, and content-type: application/json. For basic generation, the guide shows an action field set to generate, plus a full model string and a prompt.

One detail worth baking into your integration early: model names must be passed as the full model string. For example, doubao-seedream-5-0-lite-260128 is valid, while an abbreviated form such as doubao-seedream-5.0-lite returns a 400. Treat the model value as an exact API contract, not a display label.

Start with a minimal generation request

Here is the smallest useful curl request from the integration pattern. It uses Seedream 5.0 Lite, the default current model described in the guide, and asks for a single clean studio object:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_KEY' \
  -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 includes success, task_id, trace_id, and a data array. Each generated image item contains fields such as prompt, size, and image_url. In a real app, store both task_id and trace_id; the former helps associate the work item, while the latter is useful when debugging failures.

Choose the model and size deliberately

The guide lists several supported models: doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828. The right choice depends on the workflow.

  • doubao-seedream-5-0-pro-260628 is described as a flagship single-image model. It does not support image groups via sequential_image_generation, streaming via stream, or web search via tools.
  • doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 support sequential_image_generation, with the default set to disabled.
  • response_format defaults to url, with b64_json also supported.
  • watermark defaults to true; output_format supports jpeg by default and png for Seedream 5.0 Pro and 5.0 Lite.

Size can be specified in two ways: preset resolution labels such as 1K, 2K, 3K, or 4K, depending on the model; or explicit width-by-height values such as 2048x2048. The defaults and valid pixel ranges vary by model, so it is safer to validate these values per model in your application rather than exposing one global dropdown.

Add image editing when you have a source image

For editing, pass an image field containing one or more image URLs or Base64 inputs, and describe the transformation in prompt. The public guide shows a Python request using doubao-seedream-4-0-250828, size: 2K, and watermark: False:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer YOUR_API_KEY",
    "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 the pattern I would use for product-image iteration, visual QA tooling, or internal creative review systems: keep the source image stable, make the edit instruction explicit, and save the returned image_url next to the original asset.

Handle long-running work with async, callbacks, or streaming

The guide notes that image generation may take around one to two minutes. If you do not want to keep an HTTP connection open, use callback_url so the result is POSTed back to your service with the matching task_id. If you do not have a public callback endpoint, set async to true and poll /seedream/tasks with the returned task_id.

For interactive interfaces, streaming is another option on Lite and 4.x models. When stream: true, set accept: application/x-ndjson. The API returns line-by-line events such as image_generation.partial_succeeded or image_generation.partial_failed, then a single final image_generation.completed event with final usage. Streaming cannot be combined with async or callback_url.

Use layer decomposition for editable assets

Seedream 5.0 Pro also supports layer_decomposition. In that mode, the API can split an input PNG or JPEG into one base image and up to 16 transparent PNG layers. You can omit prompt for automatic decomposition, or specify elements in natural language and normalized <bbox> coordinates. Returned layers include z_index, name, description, and bounding_box.absolute / bounding_box.normalized. To recompose, stack layers in ascending z_index, placing each layer by its absolute bounding box.

Practical error handling

Build your client around the documented error shape:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

The guide lists common responses including 400 token_mismatched, 400 api_not_implemented, 401 invalid_token, 429 too_many_requests, and 500 api_error. In practice, log trace_id, show a retryable message for 429 and 500, and surface parameter validation clearly for 400.

The useful mental model is simple: use /seedream/images for generation, editing, streaming, callbacks, and decomposition; use task_id to connect long-running work back to your app; and keep model-specific constraints close to your UI. For the complete parameter reference, read the Seedream Images API integration guide.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more