OpenAI Image Format (Image)

Official Documentation

📝 Introduction

Given a text prompt and/or input image, the model will generate new images. OpenAI provides multiple powerful image generation models that can create, edit, and modify images based on natural language descriptions.

🤖 Supported Models

Currently supported models include:

Model	Description
gpt-image-1	GPT-Image-1 image generation model
gpt-image-1.5	GPT-Image-1.5 image generation and editing model
gpt-image-2	GPT-Image-2 image generation and editing model, supporting multi-image editing capabilities, able to create new composite images based on multiple input images
gpt-image-2.5-sunburst	Most capable GPT-Image-2.5 model, optimized for precise image generation and editing. The dated snapshot `gpt-image-2.5-sunburst-2026-09-08` is also supported.
gpt-image-2.5-flare	Fast GPT-Image-2.5 model for high-quality everyday image generation and editing. The dated snapshot `gpt-image-2.5-flare-2026-09-08` is also supported.

💡 Request Examples

Create Image ✅

# Generate an image and return a temporary URL
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute little sea otter",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

# Maximum-quality GPT Image 2.5 generation
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A cute little sea otter",
    "quality": "max",
    "size": "1024x1024"
  }'

# Transparent background with WebP output
curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute little sea otter",
    "background": "transparent",
    "output_format": "webp"
  }'

Response Example:

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://cdn.example.com/generated-images/...?...",
      "revised_prompt": "A cute little sea otter playing in the water, with round eyes and fluffy fur"
    }
  ],
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "total_tokens": 100,
    "input_tokens": 50,
    "output_tokens": 50,
    "input_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 40
    }
  }
}

Edit Image ✅

# GPT Image 2.5 image editing
curl https://www.unodetech.xyz/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F image="@otter.png" \
  -F mask="@mask.png" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="A cute little sea otter wearing a beret" \
  -F size="1024x1024" \
  -F response_format="url"

# gpt-image-2 multi-image editing example
curl https://www.unodetech.xyz/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F "prompt=Create an elegant gift basket containing these four items" \
  -F "quality=high"

Response Example:

{
  "created": 1713833628,
  "data": [
    {
      "url": "https://cdn.example.com/generated-images/...?..."
    }
  ],
  "usage": {
    "total_tokens": 100,
    "input_tokens": 50,
    "output_tokens": 50,
    "input_tokens_details": {
      "text_tokens": 10,
      "image_tokens": 40
    }
  }
}

📮 Request

Endpoints

Create Image

POST /v1/images/generations

Create images based on text prompts.

Edit Image

POST /v1/images/edits

Create edited or extended images based on one or more original images and prompts.

JSON image-edit requests

Image editing supports both multipart/form-data uploads and application/json request bodies. For JSON requests, provide source images in the images array. Each image reference must contain either an image_url (a URL or Base64 data URL) or a file_id. A mask can use the same reference format. All other allowed edit parameters remain the same.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "A cute little sea otter wearing a beret",
  "images": [{ "image_url": "https://example.com/otter.png" }],
  "mask": { "file_id": "file-mask" },
  "quality": "max"
  // ...other image-edit parameters
}

Authentication Method

Include the following in the request header for API key authentication:

Authorization: Bearer $API_KEY

Where $API_KEY is your API key.

Request Body Parameters

Create Image (`/v1/images/generations`)

Parameter	Type	Required	Description
`prompt`	string	Yes	Text description of the desired image. Maximum 32000 characters.
`model`	string	Yes	Image generation model, such as `gpt-image-1`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2.5-sunburst`, or `gpt-image-2.5-flare`. Dated GPT Image 2.5 snapshots ending in `-2026-09-08` are also supported.
`n`	integer	No	Number of images to generate (1–10). Default: `1`.
`size`	string	No	Size of the generated image. Standard options: `1024x1024`, `1536x1024` (horizontal), `1024x1536` (vertical), `auto`. `gpt-image-2` and both GPT Image 2.5 variants also accept custom `WIDTHxHEIGHT` strings; see Custom dimensions. Default: `auto`.
`quality`	string	No	Quality of the generated image. Options for GPT Image models: `low`, `medium`, `high`, `auto`. GPT Image 2.5 Sunburst and Flare additionally support `xhigh` and `max`. Default: `auto`.
`background`	string	No	Background of the generated image. Options: `transparent`, `opaque`, `auto`. Transparent requires `output_format` of `png` or `webp`. Default: `auto`.
`output_format`	string	No	File format of the returned image. Options: `png`, `jpeg`, `webp`. Default: `png`.
`output_compression`	integer	No	Compression level (0–100) for `jpeg` and `webp` output. Default: `100`.
`moderation`	string	No	Content-moderation strictness for generated images. Options: `low`, `auto`. Default: `auto`.
`response_format`	string	No	Image response format. Use `url` for an image URL or `b64_json` for Base64 data. When omitted, the model or upstream provider's default behavior is preserved.
`stream`	boolean	No	Generate the image in streaming mode. Default: `false`.
`partial_images`	integer	No	Number of partial images to emit during streaming (0–3). Only valid when `stream` is `true`.
`user`	string	No	Unique identifier for the end user to help OpenAI monitor and detect abuse.

URL responses

For GPT Image models that only return Base64, the API stores the generated image and returns a temporary signed URL when URL delivery is available. This parameter is handled by the API compatibility layer and does not require native upstream support for response_format.

Before use, a platform administrator must enable image URL delivery in the current environment and include the current API key or traffic in its rollout. Otherwise, response_format=url returns 503. Clients do not configure or receive Bunny credentials.

Edit Image (`/v1/images/edits`)

Parameter	Type	Required	Description
`image`	file or file[]	Yes	Image(s) to edit. Each must be a PNG, WEBP, or JPG file, less than 25MB. Up to 16 images can be provided as an array.
`prompt`	string	Yes	Text description of the desired edit. Maximum 32000 characters.
`mask`	file	No	PNG image whose transparent areas (alpha = 0) indicate the positions to edit. Must be less than 4MB and the same size as the image.
`model`	string	Yes	Image editing model, such as `gpt-image-1`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2.5-sunburst`, or `gpt-image-2.5-flare`. Dated GPT Image 2.5 snapshots ending in `-2026-09-08` are also supported.
`n`	integer	No	Number of images to generate (1–10). Default: `1`.
`size`	string	No	Size of the generated image. Standard options: `1024x1024`, `1536x1024` (horizontal), `1024x1536` (vertical), `auto`. `gpt-image-2` and both GPT Image 2.5 variants also accept custom `WIDTHxHEIGHT` strings; see Custom dimensions. Default: `auto`.
`quality`	string	No	Quality of the generated image. Options for GPT Image models: `low`, `medium`, `high`, `auto`. GPT Image 2.5 Sunburst and Flare additionally support `xhigh` and `max`. Default: `auto`.
`background`	string	No	Background of the generated image. Options: `transparent`, `opaque`, `auto`. Transparent requires `output_format` of `png` or `webp`. Default: `auto`.
`output_format`	string	No	File format of the returned image. Options: `png`, `jpeg`, `webp`. Default: `png`.
`output_compression`	integer	No	Compression level (0–100) for `jpeg` and `webp` output. Default: `100`.
`input_fidelity`	string	No	Controls how closely the output adheres to the input image(s). Options: `high`, `low`.
`moderation`	string	No	Content-moderation strictness for generated images. Options: `low`, `auto`. Default: `auto`.
`response_format`	string	No	Image response format. Use `url` for an image URL or `b64_json` for Base64 data. When omitted, the model or upstream provider's default behavior is preserved.
`stream`	boolean	No	Generate the image in streaming mode. Default: `false`.
`partial_images`	integer	No	Number of partial images to emit during streaming (0–3). Only valid when `stream` is `true`.
`user`	string	No	Unique identifier for the end user to help OpenAI monitor and detect abuse.

Custom dimensions

For gpt-image-2, gpt-image-2.5-sunburst, and gpt-image-2.5-flare (including their dated snapshots), size can be a custom WIDTHxHEIGHT value such as 1536x864. Custom dimensions must meet all of these constraints:

Width and height must be multiples of 16.
The aspect ratio must be between 1:3 and 3:1.
Neither edge can exceed 3840 pixels.
The total pixel count must be between 655,360 and 8,294,400 pixels.

Resolutions above 2560x1440 are experimental.

📥 Response

Successful Response

Both endpoints return a response containing a list of image objects.

Field	Type	Description
`created`	integer	Unix timestamp (in seconds) of when the image was created
`data`	array	List of generated image objects
`background`	string	The actual background setting used (`transparent` or `opaque`)
`output_format`	string	The actual output format used (`png`, `webp`, or `jpeg`)
`quality`	string	The actual quality level used (`low`, `medium`, `high`, `xhigh`, or `max`, depending on the model)
`size`	string	The actual dimensions of the generated image
`usage`	object	Token usage for the API call

`usage` Fields

Field	Type	Description
`total_tokens`	integer	Total tokens used
`input_tokens`	integer	Tokens used for input
`output_tokens`	integer	Tokens used for output
`input_tokens_details`	object	Detailed breakdown of input tokens: `text_tokens` and `image_tokens`

Image Object

Each object in the data array contains:

Field	Type	Description
`url`	string	Image URL returned for `response_format=url`; it may be an upstream-native URL or a temporary signed URL created after Base64 storage.
`b64_json`	string	Base64-encoded image data. Returned for `response_format=b64_json`, an upstream Base64 default, or an allowed URL-delivery fallback.
`revised_prompt`	string	The modified prompt used for generation, if the prompt was revised

Each image object contains either url or b64_json; clients must not assume that both fields are present. URL response example:

{
  "url": "https://cdn.example.com/generated-images/...?...",
  "revised_prompt": "A cute little sea otter playing in the water, with round eyes and fluffy fur"
}

Response Format and URL Delivery

`response_format`	Behavior
Omitted	Preserves the model or upstream provider's default response format. GPT Image models usually return `b64_json`.
`b64_json`	Requests Base64 image data in the response.
`url`	Requests an image URL. Native URLs pass through; eligible Base64 results are stored and replaced with temporary signed URLs.

Temporary URLs expire. Download or transfer the image soon after receiving the response instead of treating the URL as permanent. If a recoverable URL-delivery failure occurs, the API may return Base64 and set X-Image-Delivery-Fallback: base64. Clients requesting response_format=url should inspect both the response field and this header.

The returned URL includes its access signature and can be downloaded directly with HTTP GET; do not attach the API Authorization header. Keep the complete query string because it is part of the signature:

IMAGE_URL=$(jq -r '.data[0].url // empty' response.json)
test -n "$IMAGE_URL" && curl --fail --location "$IMAGE_URL" --output generated.png

URL delivery applies to non-streaming requests that return one complete JSON response. Do not combine response_format=url with stream=true; process streaming image requests using the selected model's streaming event format.

URL Delivery Errors

HTTP status	Error code	Recommended action
`400`	Invalid request	Ensure `response_format` is the lowercase value `url` or `b64_json`.
`502`	`image_url_delivery_failed`	The image was generated, but storage or URL signing failed in strict mode. Retry later without aggressive immediate retries.
`502`	`image_response_too_large`	The generated response exceeded the server processing limit. Reduce the image count or dimensions.
`503`	`image_url_delivery_unavailable`	URL delivery is not enabled for the current model, API key, or environment. Use `b64_json` or wait for an administrator to enable it.
`503`	Other `image_delivery_*` errors	URL-delivery capacity or runtime state is temporarily unavailable. Retry with backoff.

🌟 Best Practices

Prompt Writing Tips

Use clear and specific descriptions
Specify important visual details
Describe expected artistic style and atmosphere
Pay attention to composition and perspective instructions

Parameter Selection Tips

Size Selection
- 1024x1024: General scene best choice
- 1536x1024/1024x1536: Suitable for horizontal/vertical scenes
Quality
- quality=high: For images requiring fine details
- quality=xhigh or quality=max: GPT Image 2.5 only; use for higher-detail final assets when increased latency and cost are acceptable
- quality=auto: Let the model choose the optimal quality

Common Questions

Image generation failed
- Check if the prompt complies with content policies
- Confirm file format and size limits
- Verify API key permissions
Results do not match expectations
- Optimize prompt description
- Adjust quality and style parameters
- Consider using image editing or variation features

OpenAI Image Format (Image)

On this page