Create / edit images

POST/v1/images/generations

Generate images from a prompt, or provide reference images in image within the same JSON request to edit them.

Authorization

bearerAuth

AuthorizationBearer <token>

Use a platform API key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Platform model ID.

prompt?string

Image generation or editing instructions. May be omitted only for layer decomposition.

Length1 <= length

image?|array<>

Reference images. Omit for text-to-image generation. Each image must be at most 30 MB. See the model differences page for image limits. Layer decomposition accepts one image only.

size?string

Resolution preset or WIDTHxHEIGHT. See the model differences page for values and defaults.

optimize_prompt_options?

output_format?string

Image file format. For layer decomposition, this controls the base image only. Layers are always PNG.

Default"jpeg"

Value in

"png"
"jpeg"

background?string

Transparent mode requires one input image with an alpha channel and produces PNG.

Default"opaque"

Value in

"opaque"
"transparent"

response_format?string

Return image URLs or Base64 data.

Default"url"

Value in

"url"
"b64_json"

watermark?boolean

Whether to add an AI-generated watermark.

Defaulttrue

layer_decomposition?boolean

Split one image into a base image and separate layers. Supported by selected models only.

Defaultfalse

sequential_image_generation?string

Image series mode. With auto, the model decides whether to generate a series.

Default"disabled"

Value in

"disabled"
"auto"

sequential_image_generation_options?

stream?boolean

Return generated images individually. Supported by selected models only.

Defaultfalse

tools?array<>

Web search tool. Supported by selected models only.

Response Body

`application/json`

type*string

model?string

Model ID actually used.

created?integer

Unix timestamp in seconds.

Range0 <= value

image_index*integer

Zero-based image index.

Range0 <= value

url?string

Temporary download URL. Save the image within 24 hours.

Formaturi

b64_json?string

Base64 image data.

size?string

Actual output dimensions in WIDTHxHEIGHT format.

curl -X POST "https://example.com/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "Create a photo of a white mug on a wooden desk, with soft window light from the left."
  }'

{
  "created": 1793980674,
  "data": [
    {
      "url": "https://example.com/result.jpeg"
    }
  ]
}

Replace the editing example URL with the image URL generated in the previous step. For Base64, replace BASE64_BYTES with actual image data and retain the Data URL prefix matching its format.

Volcengine image generation APIAPI fields, responses and feature guides.

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

Streaming response events

`application/json`

`application/json`

`application/json`