Image Generation API

POST https://ark.cn-beijing.volces.com/api/v3/images/generations

This document describes the API for calling image generation models such as the Seedream series, including input/output parameters, value ranges, notes, and other information for reference when using the API.

Image Generation Capabilities

Overview of image generation capabilities supported by different models:

• seedream 5.0 pro (new)
  • Layer Decomposition: Supports decomposing a single image into a base image (1) + multiple layers (up to 16 layers).
  • Interactive Editing: Supports specifying edit positions via coordinates, bounding boxes, arrows, and other methods to precisely edit images.
  • Single Image Generation (sequential_image_generation is not supported)
    • Multi-Image-to-Image: Generate a single image based on your multiple reference images (2-10) + text prompt.
    • Single-Image-to-Image: Generate a single image based on your single reference image + text prompt.
    • Text-to-Image: Generate a single image based on your text prompt.
  • Does not support group image generation, web search, or streaming output.
• seedream 5.0 lite, seedream 4.5/4.0
  • Group Image Generation (Group Image: A set of content-related images generated based on your input; configure sequential_image_generation as auto)
    • Multi-Image-to-Group-Image: Generate a set of content-related reference images based on your multiple reference images (2-14) + text prompt (Number of input reference images + number of final generated images ≤ 15).
    • Single-Image-to-Group-Image: Generate a set of content-related images based on your single reference image + text prompt (up to 14 images).
    • Text-to-Group-Image: Generate a set of content-related images based on your text prompt (up to 15 images).
  • Single Image Generation (configure sequential_image_generation as disabled)
    • Multi-Image-to-Image: Generate a single image based on your multiple reference images (2-14) + text prompt.
    • Single-Image-to-Image: Generate a single image based on your single reference image + text prompt.
    • Text-to-Image: Generate a single image based on your text prompt.

---

Request Parameters

Request Body

model string (required)

The ID (Model ID) of the model you want to call.

You can also call the model via Endpoint ID to obtain advanced capabilities such as rate limiting, billing type (pre-paid/post-paid), running status query, monitoring, and security.

prompt string (required)

The prompt used for image generation, supporting Chinese and English. (See Prompt Guide: Seedream 4.0-5.0 Prompt Guide)

Prompt Language Support: All models support Chinese and English prompts; Seedream 5.0 pro additionally supports Russian, Arabic, Filipino, Thai, Turkish, Korean, Malay, Spanish, Portuguese, Indonesian, French, German, Vietnamese, and Japanese.

It is recommended not to exceed 300 Chinese characters or 600 English words. Excessive words may disperse information, causing the model to ignore details and focus only on key points, resulting in missing elements in the image.

Layer Decomposition Scenario (optional): When layer decomposition mode is enabled (layer_decomposition is true), prompt is optional and used to specify the layer decomposition intent. The model identifies and decomposes the specified elements based on the prompt intent. If no prompt is provided, the model will automatically identify all major elements in the image and decompose them into independent layers.

image string/array

The input image information, supporting URL or Base64 encoding. seedream-5.0-lite/4.5/4.0 supports single or multiple image inputs (See Multi-Image Fusion Example).

• Image URL: Ensure the image URL is accessible.
• Base64 Encoding: Follow this format data:image/<image format>;base64,<Base64 encoding>. Note that <image format> should be lowercase, e.g.:
  • data:image/png;base64,<base64_image>

Image Generation Scenario (optional)

• Image Format: jpeg, png (The seedream-5.0-lite/4.5/4.0 models also support webp, bmp, tiff, gif, heic, heif formats)
• Aspect Ratio (width/height) Range:
  • [1/16, 16] (Applicable models: seedream-5.0-lite/4.5/4.0)
• Width/Height Length (px): > 14
• Size: No more than 30MB
• Total Pixels: No more than 6000×6000=36000000 px (Limit on the product of width and height pixels for a single image, not individual limits on width or height)
• Reference Image Count: seedream-5.0-pro supports up to 10 reference images; seedream-5.0-lite/4.5/4.0 supports up to 14 reference images.

Layer Decomposition Scenario (required, Seedream 5.0 pro only)

When layer decomposition mode is enabled (layer_decomposition is true), image is a required parameter and only a single image is supported (passing multiple images will trigger an error).

• Image Format: png, jpeg
• Aspect Ratio: [1/16, 16]
• Size: No more than 30MB
• Total Pixel (width×height) Range: [512×512 (262144), 6000×6000 (36 million)] (Limit on the product of width and height pixels for a single image, not individual limits on width or height)

layer_decomposition boolean default: false (new, Seedream 5.0 pro only)

Controls whether to enable layer decomposition. Layer decomposition automatically decomposes the subject, background, text, etc. of a single image into 1 base image and up to 16 independently editable layers. Each layer is a PNG image with a transparent channel.

• true: Layer decomposition mode. The model decomposes the input image into one base image and multiple layers.
• false: Image generation mode. No layer decomposition is performed.

Notes

• Only a single image to be decomposed is supported; passing multiple images will trigger an error.
• If any layer fails to generate, the entire request fails; partial success is not supported.
• If the number of decompositions requested by the prompt exceeds the limit, some layer information may be lost.
• In the response data, each output layer's position and content information is returned, including layer order (z_index), bounding box (bounding_box), name (name), and description (description).

size string

• Method 1 (Recommended) | Specify a resolution tier, and describe the aspect ratio, image shape, or image purpose in natural language in the prompt. The model ultimately determines the generated image size.
  • Default value: 2K
  • Available values: 1K、1.5K、2K
• Method 2 | Specify the width and height pixel values of the generated image:
  • Total pixel range: [1280x720=921600, 2048x2048x1.1025=4624220]
  • Aspect ratio range: [1/16, 16]

Note

Pricing note: 1.5K is priced the same as 1K, with better image generation quality.

When using Method 2, both the total pixel range and the aspect ratio range must be satisfied. The total pixel is a limit on the product of the width and height of a single image, not a limit on the width or height individually.

• Valid example：2048x1024
  Total pixel value 2048×1024=2097152, meets the [921600, 4624220] range; aspect ratio 2048/1024=2, meets the [1/16, 16] range, so this value is valid.
• Invalid example：512x512
  Total pixel value 512×512=262144, below the minimum 921600, so this value is invalid.

Recommended width × height pixel values

Resolution	Aspect ratio	Width × Height (px)
1K	1:1	1024x1024
	4:3	1152x864
	3:4	864x1152
	16:9	1424x800
	9:16	800x1424
	3:2	1248x832
	2:3	832x1248
	21:9	1568x672
1.5K	1:1	1536x1536
	4:3	1792x1344
	3:4	1344x1792
	16:9	2048x1152
	9:16	1152x2048
	3:2	1872x1248
	2:3	1248x1872
	21:9	2352x1008
2K	1:1	2048x2048
	4:3	2368x1776
	3:4	1776x2368
	16:9	2816x1584
	9:16	1584x2816
	3:2	2496x1664
	2:3	1664x2496
	21:9	3136x1344

Layer Decomposition Scenario (Seedream 5.0 pro only): Only the resolution tier method is supported. size defaults to auto; available values are 1K, 1.5K, 2K, auto (output based on the input image's size and aspect ratio). Output rules: the base image resolution matches the size-specified resolution and keeps the original image's aspect ratio; each layer's resolution is close to the size-specified resolution and keeps its aspect ratio in the original image. Pricing note: 1.5K is priced the same as 1K.

sequential_image_generation string default: disabled (seedream-5.0-lite/4.5/4.0 only; Seedream 5.0 pro not supported)

Controls whether to enable group image generation.

Note: Group Image: A set of content-related images generated based on your input.

• auto: Automatic judgment mode. The model will independently determine whether to return group images and the number of images in the group based on the user's prompt.
• disabled: Disable group image generation. The model will only generate one image.

sequential_image_generation_options object

Configuration for group image generation, only effective when sequential_image_generation is auto.

Properties

sequential_image_generation_options.max_images integer default: 15

Specifies the maximum number of images that can be generated in this request.

• Value range: [1, 15]

Note: The actual number of images that can be generated is affected not only by max_images but also by the number of input reference images. Number of input reference images + number of final generated images ≤ 15.

tools array of object

Only seedream-5.0-lite supports this parameter (Seedream 5.0 pro / 4.5 / 4.0 not supported). Configure the tools to be called by the model.

Properties

• tools.type string Specifies the type of tool to use.
  • web_search: Web search function.

Notes:

• After enabling web search, the model will independently determine whether to search the internet (e.g., products, weather) based on the user's prompt to improve the timeliness of generated images, but it will also increase latency.
• The actual number of searches can be queried via the usage.tool_usage.web_search field. A value of 0 means no search was performed.

stream Boolean default: false (seedream-5.0-lite/4.5/4.0 only; Seedream 5.0 pro not supported)

Controls whether to enable streaming output mode.

• false: Non-streaming output mode. Wait for all images to be generated before returning all information at once.
• true: Streaming output mode. Return the result of each image generation immediately. Streaming output mode is effective for both single-image and group-image generation scenarios.

output_format string default: jpeg (Seedream 5.0 pro / 5.0 lite only)

Specifies the file format of the generated image. Options:

• png
• jpeg

Notes

• The seedream-4.5/4.0 models generate images in jpeg format by default and do not support custom settings.
• In layer decomposition scenarios, output_format only controls the base image's output format; layers are always output in png.

background string default: opaque (new, Seedream 5.0 pro only)

Controls whether to generate an image with a transparent channel. Options:

• transparent: Transparent background mode. Outputs an image with a transparent background.
• opaque: Opaque background mode. Generates a regular solid-background image.

Usage Limits

• Only supported in image-to-image scenarios, and only a single image with a transparent channel is supported as input.
• In transparent background mode, the output image defaults to png; if output_format is also set to jpeg, an error will be triggered.
• If a file format that does not support transparent channels (e.g., jpeg) is provided, an error will be triggered.

response_format string default: url

Specifies the return format of the generated image. Supports the following two return methods:

• url: Return image download link; The link is valid for 24 hours after image generation, please download the image promptly.
• b64_json: Return image data in JSON format as a Base64 encoded string.

watermark Boolean default: true

Whether to add a watermark to the generated image.

• false: Do not add watermark.
• true: Add a watermark with "AI Generated" text in the bottom right corner of the image.

optimize_prompt_options object

Configuration for prompt optimization.

Properties

• optimize_prompt_options.mode string default: standard Sets the mode used by the prompt optimization feature.
  • standard: Standard mode. Higher quality generated content, longer time-consuming.
  • fast: Fast mode. Shorter time-consuming, general quality; not currently supported by seedream-5.0-lite/4.5 (supported by Seedream 5.0 pro / 4.0).

---

Response Parameters

Streaming Response Parameters

See Streaming Response Documentation

Non-Streaming Response Parameters

model string

The model ID (model name-version) used for this request.

created integer

The Unix timestamp (seconds) of when this request was created.

data array

Information about the output images. Different task scenarios return different fields; url, b64_json, size, and output_format are common return fields.

Note:

• In group image generation scenarios (seedream-5.0-lite/4.5/4.0 only), when an image fails, additional error information (error) for that image is returned.
  • If the failure is due to review rejection: The next image generation task will continue, meaning it does not affect the generation process of other images in the same request.
  • If the failure is due to internal server error (500): The next image generation task will not continue.
• In layer decomposition scenarios (Seedream 5.0 pro only), each layer's stacking order (z_index), name (name), description (description), and bounding box (bounding_box) are additionally returned.

Image Information object Information about successfully generated images.

Properties

• data.url string URL of the image, returned when response_format is specified as url. The link will expire 24 hours after generation. Please save the image promptly.
• data.b64_json string Base64 information of the image, returned when response_format is specified as b64_json.
• data.size string The width and height pixel values of the image, in the format <width pixels>x<height pixels>, e.g., 2048x2048.
• data.output_format string (new, Seedream 5.0 pro / 5.0 lite only) The output image format (png or jpeg). In layer decomposition scenarios, output_format only controls the base image's output format; layers are always png.

Layer Decomposition Scenario Fields (Seedream 5.0 pro only)

• data.z_index integer (new): The stacking order index of the layer. The base image is fixed at 0; layers increment from 1, with larger values indicating higher layers.
• data.name string (new): The name/label of the current decomposed element. Auto-generated by the model based on the decomposed subject features, used to identify the layer's main content.
• data.description string (new): A detailed description of the current decomposed element. A semantic description generated by the model, providing richer layer features (e.g., color, state, material) than name.
• data.bounding_box object (new): Bounding box information of the output layer's region in the output base image coordinate system. Only layers return this field; the base image covers the entire canvas and does not return it.
  • data.bounding_box.absolute array: Absolute pixel coordinates of the output layer's bounding box in the output base image coordinate system, in the format [left, top, right, bottom], with the output base image's top-left corner at (0, 0). left/top are the distances from the layer's left/top boundary to the output base image's left/top boundary; right/bottom are the distances from the layer's right/bottom boundary to the output base image's left/top boundary.
  • data.bounding_box.normalized array: Normalized coordinates, derived from the absolute coordinates by scaling the output base image's width/height to the discrete integer interval [0, 1000], in the format [left, top, right, bottom]. 0 indicates the leftmost/topmost of the base image; 1000 indicates the rightmost/bottommost.

Error Information object Error information when an image generation fails.

Properties

• data.error object Error information structure.
  • data.error.code Error code for the image generation error. See Error Codes.
  • data.error.message Error prompt information for the image generation error.

tools array of object

The tools called by the model configured in this request.

Properties

• tools.type string The type of tool configured to be called.
  • web_search: Web search tool.

usage object

Usage information for this request.

Properties

• usage.generated_images integer The number of images successfully generated by the model, excluding failed images. Only successfully generated images are charged by the number of images.
• usage.input_images integer (new, Seedream 5.0 pro only) The number of images input to the model.
• usage.output_tokens integer The number of tokens consumed for image generation by the model. Calculation logic: sum(image width × image height)/256, then round to the nearest integer.
• usage.total_tokens integer The total number of tokens consumed by this request. Currently, input tokens are not calculated, so it is the same as output_tokens.
• usage.tool_usage object Usage information for tools used.
  • usage.tool_usage.web_search integer Number of web search tool calls. Only returned when web search is enabled.

error object

The error information corresponding to the error that occurred in this request.

Properties

• error.code string See Error Codes.
• error.message string Error prompt information.