Create Doubao Image

API Reference

Gateway path: POST /doubao/v1/images/generations
Upstream capability: Volcano Engine Ark Seedream image generation (/api/v3/images/generations)
Channel type: Doubao Image (ChannelTypeDoubaoImage = 61)
Official reference: Volcano Engine Ark — Image Generation API

Overview

Doubao Image is a dedicated image channel type newly added by the gateway, used to fully interface with 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" }])

Dedicated Route

Item	Description
Gateway path	`POST https://www.maasunion.com/doubao/v1/images/generations`
Routing policy	Only dispatched to channels of type "Doubao Image"; never hits VolcEngine or other channels
Request/Response format	Consistent with the Volcano Engine Ark official API; the gateway transparently forwards and parses billing fields
Upstream address	`{channel base_url}/api/v3/images/generations` (default `https://ark.cn-beijing.volces.com`)

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

Supported Models (Built-in Reference)

Administrators can configure the model name or Endpoint ID on the channel. The list below is the built-in reference:

model	Description
`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`	Endpoint ID example
`doubao-seedream-4-0-250828`	Endpoint ID example

Model Capability Matrix

Model	Text-to-Image	Image-to-Image	Multi-image Fusion	Series	Stream	Web Search	Custom Output Format
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
Single image to image: 1 reference image + text → single image
Text to image: pure text → single image

Authentication

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

On the upstream channel side, the Volcano Engine Ark API Key is used; the gateway automatically injects Authorization: Bearer {ARK_API_KEY} on forwarding. Clients do not need to (and should not) pass the upstream key.

Request Parameters

Request Body

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	Model ID or Endpoint ID (must be configured on a Doubao Image channel)
`prompt`	string	Yes	—	Prompt, ≤ 300 Chinese characters / 600 English words is recommended
`image`	string / array	No	—	Input image (URL or Base64), at most 14
`size`	string	No	`2048x2048`	`2K` / `3K` / `4K` or custom WxH (e.g. `2048x2048`)
`sequential_image_generation`	string	No	`disabled`	`auto` (series) / `disabled` (single)
`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
`stream`	boolean	No	`false`	Whether to stream the output (SSE)
`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)

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 gateway 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
  }'

Billing

The gateway parses the billing info from the usage field in the upstream response:

Field	Gateway Usage
`usage.generated_images`	Written into `n` multiplier for per-image billing (the actual number returned upstream is used for series)
`usage.output_tokens` / `usage.total_tokens`	Used by Token-based billing models
`usage.tool_usage.web_search`	Web search additional usage (if supported by model/multiplier config)

The actual deduction rules depend on the administrator's configuration in Model Multiplier / Price, consistent with channel-group strategy.

Differences vs. VolcEngine Channel

Comparison	Doubao Image (61)	VolcEngine (45)
Gateway path	`/doubao/v1/images/generations`	`/v1/images/generations` (shared with other OpenAI image interfaces)
Channel scope	Image only, dedicated Seedream adapter	General: chat, embedding, TTS, image, video, etc.
Route isolation	Dedicated route only hits type=61 channels	Distributed by model name, may be mixed with LLM channels
Doubao-specific parameters	Fully transparent (series, stream, tools, etc.)	Relies on transparent mode in some scenarios
Suitable for	Seedream image API only	Reusing the same Ark Key for multiple capabilities

Both can coexist: it is recommended to use the Doubao Image dedicated route for new integrations; existing VolcEngine configurations can be migrated gradually.

Notes

Image URL validity: Valid for 24 hours after generation; please download or persist in time.
model is required: The dedicated route does not auto-fill placeholder model names like dall-e.
Channel type match: When calling /doubao/v1/images/generations, the model must be configured on a "Doubao Image" channel.
Streaming vs non-streaming: For series, streaming is recommended to get each image as it is generated; non-streaming waits for all to complete.
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).