Image Generation and Editing

Generate and edit images through OpenAI-compatible JSON and multipart endpoints.

Endpoints

POST /v1/images/generations
POST /v1/images/edits
Authorization: Bearer $API_KEY

These endpoints serve OpenAI gpt-image, xAI Grok Imagine, compatible Seedream image models, and QwenCloud image models. Gemini-native image models instead use Generate Content.

For QwenCloud, both text-to-image and image-to-image use POST /v1/images/generations. Put the source image in the top-level image field (as a string or array); do not use multipart /v1/images/edits. Qwen result URLs are temporary and should be downloaded if they need to be retained.

Generate an image

POST /v1/images/generations accepts JSON.

Field	Type	Required	Description
`model`	string	Yes	Complete public image model ID.
`prompt`	string	Yes, except layer decomposition	Generation instruction.
`n`	integer	No	Requested output count; defaults to `1` for admission estimates.
`size`	string	No	OpenAI gpt-image-2 and GPT Image 2.5 Sunburst/Flare models (including 2026-09-08 snapshots) support any `WIDTHxHEIGHT` within upstream limits; other models use model-specific sizes.
`quality`	string	No	GPT Image models support `auto` (default), `low`, `medium`, and `high`; both GPT Image 2.5 Sunburst/Flare series (including 2026-09-08 snapshots) additionally support `xhigh` and `max`.
`background`	`transparent`, `opaque`, or `auto`	No	GPT Image background behavior. Transparent output requires PNG or WebP.
`moderation`	`low` or `auto`	No	GPT Image moderation level.
`output_format`	`png`, `jpeg`, or `webp`	No	GPT Image output encoding.
`output_compression`	integer	No	JPEG/WebP compression from 0–100.
`partial_images`	integer	No	Number of streaming previews, from 0–3.
`response_format`	`url` or `b64_json`	No	xAI result representation. Do not send it to GPT Image models.
`stream`	boolean	No	Request image SSE events when supported.
`user`	string	No	Stable end-user identifier.
`image` or `images`	model-specific	No	Seedream reference URL/data URI input.
`resolution`	`1k` or `2k`	No	xAI-compatible resolution tier when supported.
`aspect_ratio`	string	No	xAI-compatible requested aspect ratio.
`sequential_image_generation`	string	No	Seedream-compatible sequential generation mode.
`sequential_image_generation_options.max_images`	integer	No	Maximum sequential outputs.
`layer_decomposition`	boolean	No	Seedream layer decomposition; requires exactly one input image.

curl "http://127.0.0.1:11113/v1/images/generations" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "openai/gpt-image-1.5",
  "prompt": "A minimal cloud icon on a transparent background",
  "size": "1024x1024",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}'

Edit an image

POST /v1/images/edits accepts either JSON references or multipart file uploads. In addition to model, prompt, and source images, compatible edit requests can use background, input_fidelity, mask, moderation, n, output_compression, output_format, partial_images, quality, size, stream, and user. xAI JSON edits can also use aspect_ratio, resolution, and response_format.

JSON editing requires model, prompt, and either an image object or a non-empty images array. Image items can carry compatible URL, data URI, or file-reference fields.

curl "http://127.0.0.1:11113/v1/images/edits" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "xai/grok-imagine-image-2.0",
  "prompt": "Change the sky to sunset",
  "image": {"type": "image_url", "url": "https://example.com/source.png"},
  "quality": "medium",
  "resolution": "1k",
  "response_format": "url"
}'

Synchronous response

A compatible response contains one item per generated image. GPT Image models always return base64; xAI models can return a URL or base64 according to response_format.

{
  "created": 1767225600,
  "data": [{ "b64_json": "..." }],
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

If an upstream includes model, the gateway rewrites it to the public model ID. Copy URL results you need to keep; they can be temporary.

Streaming response

When both endpoint and model support streaming, send stream: true and consume text/event-stream. OpenAI-compatible providers emit image_generation.* or image_edit.* progress and completion events. A completion event carries final image data and usage. Event extensions are preserved on same-protocol routes.

Model-specific fields and limits

The gateway forwards compatible unknown fields rather than maintaining a provider schema allowlist. Closed pricing or capability dimensions, such as xAI quality and resolution tiers, must still be supported by the selected model. OpenAI size remains an upstream-validated value rather than a gateway allowlist.

The following fields are rejected:

style, because DALL-E models are not exposed by this deployment.
Non-null storage_options, because the gateway does not manage upstream file ownership or lifecycle.
Client routing controls or paid service-tier selections.

JSON responses can contain large base64 payloads. The image request and synchronous response safety limit is 100 MiB. Media bytes are returned unchanged but replaced by placeholders in stored request and response bodies.