Image Generation and Editing API

Generate images, edit reference images, and receive results as URLs or Base64 data through OpenAI-compatible endpoints.

This page documents text-to-image generation and reference-image editing. Image generation uses an OpenAI-compatible JSON request and response format; image editing accepts both multipart/form-data and application/json. Generated or edited results can be returned as temporary URLs or Base64 data, depending on the target model.

Endpoint

POST /v1/images/generations

The Volcengine Ark OpenAI-compatible entry point also supports:

POST /api/v3/images/generations

Request headers

Authorization: Bearer <APIQIK_API_KEY>
Content-Type: application/json

Request parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	Image description. Must not be empty.
`model`	string	No	Image-generation model identifier. See the model catalog for available models.
`n`	integer	No	Number of images. Defaults to `1`; the supported range depends on the target model and provider.
`size`	string	No	Output size. Available sizes depend on the target model, for example `1024x1024`, `1792x1024`, or `1024x1792`.
`quality`	string	No	Quality parameter, such as `standard`, `hd`, `low`, `medium`, or `high`, when supported by the target model.
`style`	string	No	Style parameter, such as `vivid` or `natural`, when supported by the target model.
`output_format`	string	No	`png`, `jpeg`, or `webp`, when supported by the target model.
`response_format`	string	No	`url` or `b64_json`; defaults to `url`. Some models do not use this parameter.
`image`	string or string[]	No	Reference image as one value or an array. Depending on the model, this can be an HTTP(S) URL, Base64 value, or data URL; up to 16 images. Image-to-image support depends on the target model.
`negative_prompt`	string	No	Negative prompt, when supported by the target model.
`prompt_extend`	boolean	No	Qwen Image-compatible prompt expansion switch.
`watermark`	boolean	No	Qwen Image-compatible watermark switch.
`stream`	boolean	No	Requests progressive image events, when supported by the target model. Streaming cannot be used with `Idempotency-Key`.
`layer_decomposition`	boolean	No	Layer-decomposition intent; whether it takes effect depends on the provider.
`user`	string	No	Identifier for the end user.

The gateway validates output_format, response_format, and the basic reference-image shape. Data URL reference images must be JPEG, PNG, or WebP and must not exceed 10 MiB after decoding per image; the selected model may impose stricter outbound limits.

Model selection

Entries whose capabilities include image in the model catalog can be used with this endpoint. Text-to-image, image-to-image, image editing, and layer decomposition depend on the target model; the console model details are authoritative, and this page does not list a fixed set.

Call GET /v1/public/models?availableOnly=true to see currently available image models.

Request example

curl "${BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer ${APIQIK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<image-model-id>",
    "prompt": "A futuristic city in the rain at night, cinematic composition",
    "size": "1024x1024",
    "quality": "standard",
    "response_format": "url"
  }'

Response example

{
  "created": 1789987200,
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "revised_prompt": "A futuristic city in the rain at night, cinematic composition"
    }
  ]
}

data[] can contain the following fields:

Field	Description
`url`	Temporary URL for the generated image. Download or persist it promptly.
`b64_json`	Base64-encoded image content, used when `response_format: "b64_json"` is requested.
`revised_prompt`	Prompt modified or expanded by the model.

Some GPT Image models also return usage with input_tokens, output_tokens, and total_tokens.

Error handling

400: Missing required parameters, invalid parameter type or value, or a model that does not support a requested parameter.
401: Missing or invalid API key.
403: The API key is not authorized for image endpoints.
413: The request body or an uploaded file exceeds the endpoint limit.
429: Upload concurrency or request rate is limited.
500, 502, or 503: Gateway or upstream image service failure.

Clients should handle failures using the HTTP status code and structured error fields, and retain X-Request-Id from the response.

Image editing

POST /v1/images/edits

Image editing supports reference-image editing, mask editing, and multiple input images. There is currently no /api/v3/images/edits alias. The endpoint uses Authorization: Bearer <APIQIK_API_KEY> authentication and accepts both multipart/form-data and application/json request bodies.

multipart/form-data

Field	Type	Required	Description
`image[]` or `image`	file	Yes	Input image. `image[]` supports up to 16 images; multi-image support with `image` depends on the target model.
`prompt`	string	Yes	Edit instruction. It cannot be empty.
`mask`	file	No	Mask image; mask semantics depend on the target model.
`model`	string	No	Specify an image model from the catalog explicitly; when omitted the gateway falls back to a built-in default that may not be in the current catalog.
`n`	integer	No	Number of generated images; when provided, it must be at least 1.
`size`	string	No	Output size, subject to the target model.
`quality`	string	No	Output quality, subject to the target model.
`output_format`	string	No	`png`, `jpeg`, or `webp`, when supported by the target model.
`background`	string	No	Background parameter, such as `transparent`, `opaque`, or `auto`, when supported by the target model.
`moderation`	string	No	Content moderation level, such as `low` or `auto`, when supported by the target model.
`response_format`	string	No	`url` or `b64_json`; Some models do not use this parameter.
`user`	string	No	Identifier for the end user.

Per-image and mask size limits depend on the target model: some allow 4 MiB, others 50 MiB. A request can contain at most 16 input images; other limits are validated by the relevant adapter.

application/json

A JSON edit request supports the following fields:

{
  "model": "<image-model-id>",
  "image": ["data:image/png;base64,<BASE64_DATA>"],
  "mask": "data:image/png;base64,<BASE64_MASK>",
  "prompt": "Remove the background while keeping the subject",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "background": "transparent",
  "response_format": "b64_json"
}

image can be a single Base64/data URL string or an array of strings; mask is a single Base64/data URL string. JSON requests do not support having the gateway download HTTP(S) image URLs. The JSON entry point allows image or prompt to be omitted, but whether the request can run as generation without a reference image depends on the target adapter; multipart requests require both fields.

Image-editing responses use the same basic structure as image-generation responses: created, data[], and, for some GPT Image models, usage. Both endpoints require an API key with the images or compatible chat scope.

Image Generation and Editing API

EndpointCopy Anchor Link

Request headersCopy Anchor Link

Request parametersCopy Anchor Link

Model selectionCopy Anchor Link

Request exampleCopy Anchor Link

Response exampleCopy Anchor Link

Error handlingCopy Anchor Link

Image editingCopy Anchor Link

multipart/form-dataCopy Anchor Link

application/jsonCopy Anchor Link

On this page