How to Build an Image Generation Workflow with the SeeDream Images API

How to Build an Image Generation Workflow with the SeeDream Images API

When you add image generation to a product, the hard part is rarely the first prompt—it is turning prompts, image inputs, formats, async jobs, and failures into a workflow your application can trust.

What you can do

The SeeDream Images API on Ace Data Cloud is built around a single image endpoint, POST https://api.acedata.cloud/seedream/images. With it, you can generate images from text prompts, edit existing images by passing an image URL or Base64 input, choose a model string explicitly, control output size and format, and decide whether to wait for the result synchronously or handle it as an async task.

The useful mental model is simple: send a JSON request that describes the image operation, then read a response containing success, task_id, trace_id, and a data array. Each item in data can include the resolved prompt, generated size, and image_url.

How it works

The basic request needs an authorization header and a JSON body. The docs show two required headers for normal usage: accept: application/json and authorization: Bearer YOUR_API_TOKEN. In practice you will also send content-type: application/json for POST bodies.

For generation, pass action as generate, choose a complete model string, and provide a prompt. The default model in the documentation is doubao-seedream-5-0-260128. One important implementation detail: the model value must be the complete model string. Abbreviations such as doubao-seedream-5.0-lite can return a 400 error.

Choosing the right request fields

The API exposes enough fields to support both quick prototypes and production flows:

  • prompt: the instruction for the image.
  • model: a full model ID such as doubao-seedream-5-0-260128.
  • image: an input image URL or Base64 value for image editing. Some models support multiple images; doubao-seededit-3-0-i2i-250628 supports only a single image input, and doubao-seedream-3-0-t2i-250415 does not support this parameter.
  • size: either a supported resolution label such as 1K, 2K, 3K, or 4K depending on the model, or a pixel value such as 2048x2048. The two methods should not be mixed.
  • response_format: url by default, with b64_json also supported.
  • watermark: whether to add a watermark; the default is true.
  • callback_url and async: options for handling longer-running requests.

A few fields are model-specific. For example, seed is only supported by doubao-seedream-3-0-t2i-250415. guidance_scale is supported by doubao-seedream-3-0-t2i-250415 and doubao-seededit-3-0-i2i-250628. output_format, which supports jpeg and png, is supported by doubao-seedream-5-0-pro-260628 and doubao-seedream-5-0-260128.

A minimal text-to-image call

Here is the smallest useful version of the documented generation flow. Keep the token in your backend configuration, not in frontend code.

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-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 response follows this shape:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "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.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

For a product workflow, store both task_id and trace_id. The image_url is the generated artifact your application can display, download, or pass into a later edit step.

Editing an existing image

For image editing, include the image field and a prompt that describes the transformation. The documentation notes that doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, and doubao-seedream-4-0-250828 support single or multiple image inputs, while doubao-seededit-3-0-i2i-250628 supports only one. That matters when designing UI: a product-shot editor might allow multiple references, while a simple retouch tool should validate one input before sending the request.

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

Handling async jobs cleanly

The docs describe image generation as taking about 1–2 minutes. If you do not want to keep an HTTP connection open, you have two supported patterns. First, pass a callback_url; the API can POST the final JSON result back to your service with the same task_id. Second, use async with true without a callback; the API returns a task_id, and your backend polls /seedream/tasks with that task ID until the result is ready.

In either pattern, treat task_id as your join key. Save the original prompt, selected model, requested size, user ID, and task ID in your database before returning control to the user. When the callback or polling result arrives, update the record with image_url and the final status.

Errors worth planning for

The documented error codes are straightforward but useful for product behavior: 400 token_mismatched and 400 api_not_implemented indicate bad or unsupported input, 401 invalid_token means the authorization token is missing or invalid, 429 too_many_requests means you have hit a rate limit, and 500 api_error indicates a server-side failure. Return the trace_id in internal logs so support and engineering can connect a user-facing issue to the API call.

If you are building a real image workflow, start narrow: one model, one size, URL responses, and async handling. Once the lifecycle is reliable, add editing, Base64 inputs, model-specific options, and stricter validation. The full reference is available in the SeeDream Images Generation API documentation.

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