Skip to main content
POST

Authorizations

​
Authorization
string
header
required

All APIs require Bearer Token authentication.

Get API Key:

Visit API Key Management Page to get your API Key

Add to request header:

Body

application/json
​
model
enum<string>
default:gpt-image-2.6-sunburst
required

Image generation model name, with improved stability and control for commercial use

Both models accept exactly the same parameters. Actual token consumption at the same quality tier may differ slightly; use the returned usage as the source of truth.

Available options:
gpt-image-2.6-sunburst,
gpt-image-2.6-flare
Example:

"gpt-image-2.6-sunburst"

​
prompt
string
required

Prompt describing the image to generate or how to edit the input image

Length limits (both must be met):

  • Up to 32,000 characters (counted as Unicode code points)
  • The prompt text itself must not exceed 60,000 bytes when encoded in UTF-8

Different characters use different numbers of UTF-8 bytes. Use the actual encoded byte count.

If either limit is exceeded, shorten the prompt before resubmitting.

Recommendation: If the prompt exceeds 8000 tokens, the generated image may not match expectations; shortening the prompt is recommended.

Maximum string length: 32000
Example:

"A beautiful colorful sunset over the ocean"

​
image_urls
string<uri>[]

Reference images as public URLs, for image-to-image and image editing

Note:

  • Number of input images per request: 1~16
  • Size of a single image: not exceeding 50MB
  • Pixels of a single image: width × height not exceeding 178,956,970 px
  • Side length of a single image: width / height each not exceeding 23170 px; exceeding this may cause errors
  • Supported file formats: .jpeg, .jpg, .png, .webp
  • Image URLs must be directly accessible by the server, or the image URL should directly download when accessed (typically these URLs end with image file extensions, such as .png, .jpg)
  • In image-to-image / image editing scenarios, the reference images themselves also incur additional image input token consumption
  • With markup_url, markup applies to the first image and the others serve as references; the first image must have width × height ≤ 16,777,216 px
  • Reference images are not supported when output_format is svg
Example:
​
mask_url
string<uri>

Inpainting mask URL — marks the region of the reference image to regenerate. Only valid in image edit mode (must be combined with image_urls); the mask is silently ignored in pure text-to-image requests.

Format requirements:

  • Must be a PNG with an alpha channel: transparent pixels (alpha < 255) = regions to regenerate; opaque pixels = preserved
  • Mask dimensions must exactly match the reference image dimensions (width × height in pixels)
  • Single mask per request

Note:

  • At least one reference image is required in image_urls; a mask sent alone has no effect
  • Cannot be combined with markup_url
  • Common errors:
    • Invalid mask image format - mask image missing alpha channel: the uploaded image has no alpha channel (JPEG, opaque PNG, etc.). Re-export the mask as a PNG with transparent regions.
    • Invalid mask image format - mask size does not match image size: the mask dimensions don't match the reference image. Resize the mask to the same pixel dimensions as your reference image.
Example:

"https://example.com/mask.png"

​
markup_url
string<uri>

Public URL of a markup layer. Use circles, arrows or freehand marks to indicate what to change in the reference image, and describe the changes in prompt. Only valid in image editing mode (requires image_urls).

Format requirements:

  • Must be a PNG with transparent pixels: draw only the annotations and leave the rest transparent. Do not draw directly on the original image
  • Dimensions must exactly match the first reference image (width × height in pixels)
  • The first reference image and the markup layer must each have width × height ≤ 16,777,216 px
  • File size: no more than 50MB

Note:

  • Markup applies to the first image in image_urls; the remaining images serve as references
  • Cannot be combined with mask_url
  • Supports standard image and GIF editing, but not SVG
  • Can also be supplied as model_params.markup_url; the top-level value takes precedence when both are present
  • In prompt, also specify what to preserve, for example, "keep everything else unchanged and remove the red circle"
Example:

"https://example.com/markup.png"

​
size
string
default:auto

Generated image dimensions. Defaults to auto. Standard images and SVG reference images share the following rules; GIF uses the separate rules in section ④.

① Standard images / SVG reference images: ratio format (15 options)

  • 1:1: Square
  • 1:2 / 2:1: Extreme portrait / landscape
  • 1:3 / 3:1: Ultra portrait / landscape (3:1 limit)
  • 2:3 / 3:2: Standard portrait / landscape
  • 3:4 / 4:3: Classic portrait / landscape
  • 4:5 / 5:4: Common social media
  • 9:16 / 16:9: Mobile / desktop widescreen
  • 9:21 / 21:9: Ultra-wide

② Standard images / SVG reference images: explicit pixel format: WxH (or W×H), e.g. 1024x1024, 1536x1024, 3840×2160

  • Both width and height must be multiples of 16
  • Each edge range: [16, 3840]
  • Pixel budget: 655,360 ≤ width × height ≤ 8,294,400 (about 0.65 MP ~ 8.29 MP)
  • Aspect ratio: ≤ 3:1

③ Standard images / SVG reference images: auto: The model decides the size automatically (resolution does not apply in this mode)

④ GIF output: size specifies the dimensions of each frame. Only auto and explicit pixel dimensions are supported, not ratios.

  • With auto, each frame is 512×512
  • Explicit frame width and height must be positive multiples of 16
  • The 655,360 minimum pixel count for standard images does not apply to individual GIF frames; for example, 512x512 is valid
  • The image combining all frames must satisfy the edge, total pixel and aspect ratio limits; see model_params.frame_count for grid layouts and per-frame limits
  • resolution does not apply

Out-of-range handling:

  • For standard images / SVG reference images, a ratio + resolution combination that exceeds the budget is automatically scaled down proportionally (e.g. 4K 2:1 → 3840×1920)
  • Explicit GIF frame dimensions that exceed the limits return HTTP 400 and are not automatically scaled down
Example:

"auto"

​
resolution
enum<string>
default:1K

Resolution tier shortcut, only effective when size is a ratio; ignored in explicit pixel mode and for GIF output

Pixel budget rules (dimensions are derived from the target pixel count and the size ratio, aligned to multiples of 16):

  • 1K: ~1 MP (1024² = 1,048,576 pixels)
  • 2K: ~4 MP (2048² = 4,194,304 pixels)
  • 4K: ~8.29 MP (3840×2160 = 8,294,400 pixels, the maximum)

Landscape / square output dimensions (portrait dimensions are the landscape width/height swapped, e.g. 2:3 = 3:2 reversed):

* Marks combinations that are auto-downscaled to fit the pixel budget. Values are case-insensitive.

Available options:
1K,
2K,
4K
Example:

"1K"

​
quality
enum<string>
default:medium

Rendering quality, which directly affects output token count and cost. Defaults to medium

Note:

  • This table compares image output costs only, excluding input costs and SVG author model costs
  • Calculated for 1024×1024; output tokens vary with total pixels and aspect ratio. Use the returned usage for actual consumption
  • For GIF output, tokens are calculated for the combined image containing all frames; for SVG output, quality applies to the reference image
  • Use low for quick drafts. For final assets, compare tiers to balance detail, latency and cost
Available options:
low,
medium,
high,
xhigh,
max
Example:

"medium"

​
complexity
enum<string>
default:high

Planning depth before image generation, independent of quality. Defaults to high

  • low: Suitable for local changes such as replacing a background or changing sign text
  • medium: Balanced
  • high: Suitable for text-heavy images, complex layouts or complex relationships between objects

Note:

  • Higher levels take longer and may introduce unwanted changes; compare results for your task
  • Changing complexity does not incur an additional charge
  • For SVG output, this applies to the reference image
  • Can also be supplied as model_params.complexity; the top-level value takes precedence when both are present
Available options:
low,
medium,
high
Example:

"high"

​
background
enum<string>
default:opaque

Alpha channel of the output image. Defaults to opaque

  • opaque: Flat background, no alpha channel
  • transparent: Keeps the alpha channel

Note:

  • transparent is a Preview feature and results may be unstable
  • When using transparent, output_format must be png or webp
  • When output_format is gif or svg, only opaque is supported
Available options:
opaque,
transparent
Example:

"opaque"

​
output_format
enum<string>
default:png

Output file format. Defaults to png

  • png: Lossless, supports transparent backgrounds
  • jpeg: Lossy compression with smaller files
  • webp: Balances file size and quality; also supports transparency
  • gif: Animated GIF; see model_params for frame count and frame duration
  • svg: SVG vector image, suitable for logos, icons and other graphics that need lossless scaling

Note:

  • When background is transparent, only png or webp is allowed
  • gif supports both text-to-image and image editing
  • For gif and svg, n must be 1
  • svg supports text-to-image only
  • SVG output is created by first generating a reference image, then using an author model (model_params.svg_model) to convert it to vector graphics. Author model tokens are billed separately at that model's rates
Available options:
png,
jpeg,
webp,
gif,
svg
Example:

"png"

​
n
integer
default:1

Number of images to generate, each billed independently

Note:

  • Text input tokens scale linearly with n
  • Support for n > 1 is currently unreliable: even with a value greater than 1, only one image is often returned. The actual count is whatever results holds in the response, and billing follows the returned usage. If you need several images, send multiple single-image requests instead
  • When output_format is gif or svg, this must be 1
Required range: 1 <= x <= 10
Example:

1

​
model_params
object

Model-specific parameters. GIF frame parameters and SVG author parameters must be supplied in this object.

  • frame_count and frame_duration_ms are only allowed with output_format=gif
  • svg_model and svg_reasoning_effort are only allowed with output_format=svg
  • Parameters incompatible with the output format return HTTP 400; they are not silently ignored
​
callback_url
string<uri>

HTTPS callback address after task completion

Callback Timing:

  • Triggered when task is completed, failed, or cancelled
  • Sent after billing confirmation is completed

Security Restrictions:

  • Only HTTPS protocol is supported
  • Callback to internal IP addresses is prohibited (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.)
  • URL length must not exceed 2048 characters

Callback Mechanism:

  • Timeout: 10 seconds
  • Maximum 3 retries on failure (retries after 1 second/2 seconds/4 seconds)
  • Callback response body format is consistent with the task query API response format
  • Callback address returning 2xx status code is considered successful, other status codes will trigger retry
Example:

"https://your-domain.com/webhooks/image-task-completed"

Response

Image generation task created successfully

​
created
integer

Task creation timestamp

Example:

1757156493

​
id
string

Task ID

Example:

"task-unified-1757156493-imcg5zqt"

​
model
string

Actual model name used

Example:

"gpt-image-2.6-sunburst"

​
object
enum<string>

Specific task type

Available options:
image.generation.task
​
progress
integer

Task progress percentage (0-100)

Required range: 0 <= x <= 100
Example:

1

​
status
enum<string>

Task status. Queued and running tasks both return processing; the final status is completed or failed.

Available options:
processing,
completed,
failed
Example:

"processing"

​
task_info
object

Asynchronous task information

​
type
enum<string>

Task output type

Available options:
text,
image,
audio,
video
Example:

"image"

​
usage
object

Usage and billing information