Create Doubao Image

API Reference

Gateway path: POST /doubao/v1/images/generations
Capability: Volcano Engine Ark Seedream image generation
Official reference: Volcano Engine Ark — Image Generation API

Overview

The Doubao image API calls the Seedream model family on Volcano Engine Ark, including:

Text-to-image, image-to-image, multi-image fusion
Sequential image generation (sequential_image_generation: auto)
Streaming SSE output (stream: true)
Web search (tools: [{ "type": "web_search" }])
Interactive editing and layer decomposition (Seedream 5.0 Pro only)

Dedicated Route

Item	Description
Gateway path	`POST https://www.maasunion.com/doubao/v1/images/generations`
Request/Response format	Consistent with the Volcano Engine Ark official API

API gateway base URL: https://www.maasunion.com

Supported Models

The Seedream models currently available (subject to what the platform has enabled):

model	Description
`doubao-seedream-5-0-pro-260628`	Seedream 5.0 Pro: interactive editing and layer decomposition
`doubao-seedream-5.0-lite`	5.0 lite series
`doubao-seedream-4.5`	4.5 series
`doubao-seedream-4.0`	4.0 series
`doubao-seedream-3.0-t2i`	3.0 text-to-image
`doubao-seedream-5-0-260128`	5.0 lite
`doubao-seedream-4-0-250828`	4.0

Model Capability Matrix

Model	Text-to-Image	Image-to-Image	Multi-image Fusion	Interactive Edit	Layer Split	Series	Stream	Web Search	Custom Output Format
doubao-seedream-5-0-pro-260628	✅	✅	✅	✅	✅	❌	❌	❌	❌ (default jpeg)
doubao-seedream-5.0-lite	✅	✅	✅	❌	❌	✅	✅	✅	✅ (png/jpeg)
doubao-seedream-4.5	✅	✅	✅	❌	❌	✅	✅	❌	❌ (default jpeg)
doubao-seedream-4.0	✅	✅	✅	❌	❌	✅	✅	❌	❌ (default jpeg)
doubao-seedream-3.0-t2i	✅	❌	❌	❌	❌	❌	❌	❌	❌

Series (sequential_image_generation: "auto"):

Multi-image to series: 2–14 reference images + text → correlated series (reference images + generated images ≤ 15)
Single image to series: 1 reference image + text → at most 14 images
Text to series: pure text → at most 15 images

Single image (sequential_image_generation: "disabled" or omitted):

Multi-image to image: 2–14 reference images + text → single image (Seedream 5.0 Pro: at most 10 reference images)
Single image to image: 1 reference image + text → single image
Text to image: pure text → single image

Seedream 5.0 Pro does not support sequential image generation. Use single-image mode.

Authentication

Header	Required	Description
`Authorization`	Yes	`Bearer {your_api_token}`, API token issued by the platform
`Content-Type`	Required for POST	`application/json`

Use the platform API token. Clients do not need to (and should not) pass an upstream vendor key.

Request Parameters

Request Body

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	Model ID, e.g. `doubao-seedream-5-0-pro-260628`
`prompt`	string	Yes	—	Prompt, ≤ 300 Chinese characters / 600 English words is recommended. For interactive editing, describe the region and desired change here
`image`	string / array	No	—	Input image (URL or Base64). At most 14 for 5.0-lite / 4.5 / 4.0; at most 10 for Seedream 5.0 Pro
`layer_decomposition`	boolean	No	`false`	Whether to split layers; Seedream 5.0 Pro only
`size`	string	No	`2048x2048`	`2K` / `3K` / `4K` or custom WxH (e.g. `2048x2048`)
`sequential_image_generation`	string	No	`disabled`	`auto` (series) / `disabled` (single); Seedream 5.0 Pro does not support `auto`
`sequential_image_generation_options.max_images`	integer	No	`15`	Maximum images in the series, range [1, 15]
`tools`	array	No	—	Tool config, e.g. `[{ "type": "web_search" }]` to enable web search; Seedream 5.0 Pro does not support this
`stream`	boolean	No	`false`	Whether to stream the output (SSE); Seedream 5.0 Pro does not support this
`guidance_scale`	float	No	—	Text weight [1, 10] (5.0-lite / 4.5 / 4.0 do not support)
`output_format`	string	No	`jpeg`	`png` / `jpeg` (custom only supported by 5.0-lite)
`response_format`	string	No	`url`	`url` (24h valid) / `b64_json`
`watermark`	boolean	No	`true`	Whether to add watermark
`optimize_prompt_options.mode`	string	No	`standard`	`standard` (high quality) / `fast` (fast; 5.0-lite / 4.5 do not support)

Image Input Limits

Item	Requirement
Image format	jpeg, png; 5.0-lite / 4.5 / 4.0 additionally support webp / bmp / tiff / gif / heic / heif
Aspect ratio	[1/16, 16] (5.0-lite / 4.5 / 4.0)
Width/height	> 14px
Single file size	≤ 30 MB
Total pixels	≤ 6000×6000 = 36,000,000 px
Number of reference images	At most 14 (5.0-lite / 4.5 / 4.0); Seedream 5.0 Pro: at most 10

Response Parameters

Non-streaming Response

Field	Type	Description
`model`	string	Model ID used
`created`	integer	Created time (Unix seconds)
`data[].url`	string	Image URL (valid for 24h)
`data[].b64_json`	string	Image Base64 (when `response_format=b64_json`)
`data[].size`	string	Pixel dimensions, e.g. `2048x2048`
`data[].error.code`	string	Error code of a single image failure
`data[].error.message`	string	Error description of a single image failure
`usage.generated_images`	integer	Number of successfully generated images (billing basis)
`usage.output_tokens`	integer	Tokens ≈ sum(width×height)/256
`usage.total_tokens`	integer	Total tokens
`usage.tool_usage.web_search`	integer	Number of web search invocations
`error.code`	string	Request-level error code
`error.message`	string	Request-level error description

Series failure handling:

Moderation failed: continue generating the next image
Internal service error (500): stop generating

Streaming Response (SSE)

After setting stream: true, the response is text/event-stream, with event types:

Event	Description
`image_generation.partial_succeeded`	A single image is generated successfully
`image_generation.completed`	All complete, with `usage`
`[DONE]`	Stream end

partial_succeeded event fields example:

{
  "type": "image_generation.partial_succeeded",
  "model": "doubao-seedream-5-0-260128",
  "created": 1757396757,
  "image_index": 0,
  "url": "https://...",
  "size": "2496x1664"
}

The completed event contains the full usage; the platform uses it to complete billing.

Recommended Size Table

2K Resolution

Aspect Ratio	Pixels
1:1	2048×2048
4:3	2304×1728
3:4	1728×2304
16:9	2848×1600
9:16	1600×2848
3:2	2496×1664
2:3	1664×2496
21:9	3136×1344

3K Resolution

Aspect Ratio	Pixels
1:1	3072×3072
4:3	3456×2592
3:4	2592×3456
16:9	4096×2304
9:16	2304×4096
2:3	2496×3744
3:2	3744×2496
21:9	4704×2016

4K Resolution

Aspect Ratio	Pixels
1:1	4096×4096
3:4	3520×4704
4:3	4704×3520
16:9	5504×3040
9:16	3040×5504
2:3	3328×4992
3:2	4992×3328
21:9	6240×2656

Custom pixel values must satisfy:

Total pixels: [3,686,400, 16,777,216] (approx. 2560×1440 to 4096×4096)
Aspect ratio: [1/16, 16]

Call Examples

1. Text-to-Image

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Vibrant close-up editorial portrait, the model has a piercing gaze, wearing a sculptural hat, with rich color blocking",
    "size": "2K",
    "output_format": "png",
    "watermark": false
  }'

Response example:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1757321139,
  "data": [
    {
      "url": "https://...",
      "size": "3104x1312"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 15840,
    "total_tokens": 15840
  }
}

2. Image-to-Image

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Keep the model's pose, but change the clothing material from silver metal to fully transparent water",
    "image": "https://example.com/reference.png",
    "size": "2K",
    "output_format": "png",
    "watermark": false
  }'

3. Multi-image Fusion

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Replace the clothing in image 1 with the clothing in image 2",
    "image": [
      "https://example.com/outfit-source.png",
      "https://example.com/outfit-target.png"
    ],
    "sequential_image_generation": "disabled",
    "size": "2K",
    "watermark": false
  }'

4. Multi-reference Image to Series

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Generate 3 images of a girl and a cow plush toy riding a roller coaster happily in an amusement park, covering morning, noon, and evening",
    "image": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 3
    },
    "size": "2K",
    "watermark": false
  }'

5. Streaming Output

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Based on reference image 1, generate four images: the character wearing sunglasses, riding a motorcycle, wearing a hat, and holding a lollipop respectively",
    "image": "https://example.com/ref.png",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 },
    "size": "2K",
    "stream": true,
    "watermark": false
  }'

SSE response snippet:

event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","image_index":0,"url":"https://...","size":"2496x1664"}

event: image_generation.completed
data: {"type":"image_generation.completed","usage":{"generated_images":4,"output_tokens":48672,"total_tokens":48672}}

data: [DONE]

6. Web Search

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Create a 5-day weather forecast chart for Shanghai in a modern flat illustration style",
    "size": "2048x2048",
    "tools": [{ "type": "web_search" }],
    "output_format": "png",
    "response_format": "url",
    "watermark": false
  }'

7. Interactive Editing (Seedream 5.0 Pro)

Pass a reference image and describe the region and desired change in prompt.

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "Replace the person in the reference image with a cyberpunk style, keep the composition unchanged",
    "image": "https://example.com/input.png",
    "size": "2K",
    "watermark": false
  }'

8. Layer Decomposition (Seedream 5.0 Pro)

Set layer_decomposition: true to split the image into independent layers. Split results and metadata are returned as-is.

curl "https://www.maasunion.com/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "Split the image into three layers: subject, shadow, and background",
    "image": ["https://example.com/input.png"],
    "size": "2K",
    "layer_decomposition": true,
    "watermark": false
  }'

Seedream 5.0 Pro

doubao-seedream-5-0-pro-260628 uses the same endpoint POST /doubao/v1/images/generations. In addition to text-to-image, image-to-image, and multi-image fusion, it supports:

Interactive editing: Pass a reference image in image and describe the edit region and target in prompt (for example, box selection, point selection, arrows, or sketch marks).
Layer decomposition: Set layer_decomposition: true. Split results and metadata are returned as-is.

Limits:

At most 10 reference images
stream: true is not supported
sequential_image_generation: "auto" (series) is not supported
tools (web search) is not supported

Layer decomposition may return multiple images and is billed by the actual usage.generated_images count.

Billing

The platform parses billing info from the usage field in the response:

Field	Usage
`usage.generated_images`	Per-image billing (the actual number returned is used for series and layer decomposition)
`usage.output_tokens` / `usage.total_tokens`	Used by Token-based billing models
`usage.tool_usage.web_search`	Web search additional usage

See the platform for the actual price.

Notes

Image URL validity: Valid for 24 hours after generation; please download or persist in time.
model is required: Use a model ID provided by the platform, e.g. doubao-seedream-5-0-pro-260628.
Streaming vs non-streaming: For series, streaming is recommended to get each image as it is generated; non-streaming waits for all to complete. Seedream 5.0 Pro does not support streaming and must use non-streaming.
Prompt length: Too long can scatter the information; keep within 300 Chinese characters / 600 English words.
OpenAI SDK compatibility: The request/response format is similar to OpenAI's image interface; you may try pointing the OpenAI client to https://www.maasunion.com/doubao/v1 (verify SDK compatibility with the SSE event format yourself).