Images schemas
The full schema and model definitions referenced by the Images endpoints. Each endpoint page links here for the detailed shape of its request and response objects.
Schemas
Create Image Edit Request
| Field | Type | Required | Description |
|---|---|---|---|
image | string (binary) | No | Image to edit. PNG format. |
prompt | string | Yes | Text description of the edits to apply. |
model | string | Yes | Model ID. |
n | integer | No | Number of edited images to generate. Range: 1-10. Defaults to 1. (minimum: 1, maximum: 10, default: 1) |
size | string | No | Requested image shape as width x height (e.g., '1024x1024'). The values set the aspect ratio; the image is produced at the generator's own resolution, so the returned pixel dimensions will not necessarily match the numbers supplied. |
response_format | enum ('url', 'b64_json') | No | Format for the edited images. One of url or b64_json. Default: b64_json. (default: b64_json) |
reasoning_strength | enum ('low', 'high') | No | How much reasoning the image generator applies before producing the edited image. One of low or high. low returns after a single generation pass (no self-refinement); high (the default) lets the generator iteratively refine. (default: high) |
moderation | string | No | Moderation level for the safety pipeline. One of auto, low, or none. Supported only on models that accept this parameter; other models reject it with a 400. An unrecognized value is rejected with a 400. none additionally requires per-application access. |
stream | boolean | No | If true, streams the response as server-sent events. Defaults to false. (default: false) |
partial_images | integer | No | Number of partial images to generate during streaming. Range: 0-3. Accepted but ignored. (minimum: 0, maximum: 3, default: 0) |
tool_enablement | ImageToolEnablement | No | Per-tool controls for the image generator's planner. Omit to keep the default (all tools available). |
Create Image Request
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID for image generation. |
prompt | string | Yes | Text description of the images to generate. |
n | integer | No | Number of images to generate. Range: 1-10. Defaults to 1. (minimum: 1, maximum: 10, default: 1) |
size | string | No | Requested image shape as width x height (e.g., '1024x1024'). The value is converted into an aspect ratio only; the image is produced at the generator's own fixed output resolution, so the returned pixel dimensions stay constant regardless of the numbers supplied — only the aspect ratio changes. |
response_format | enum ('url', 'b64_json') | No | Format for returned images. One of: url, b64_json. Defaults to b64_json. (default: b64_json) |
moderation | string | No | Moderation level for the safety pipeline. One of auto, low, or none. Supported only on models that accept this parameter; other models reject it with a 400. An unrecognized value is rejected with a 400. none additionally requires per-application access. |
output_format | string | No | Requested file type for the generated images. One of png, jpeg, or webp. Defaults to webp when omitted; any other value is rejected. |
reasoning_strength | enum ('low', 'high') | No | How much reasoning the image generator applies before producing the image. One of low or high. low returns after a single generation pass (no self-refinement); high (the default) lets the generator iteratively refine. (default: high) |
user | string | No | A stable end-user identifier that helps detect and mitigate abuse. Use it on the images endpoints; on the Responses and Chat Completions endpoints, use safety_identifier instead. |
stream | boolean | No | If true, streams the response as server-sent events. Defaults to false. (default: false) |
tool_enablement | ImageToolEnablement | No | Per-tool controls for the image generator's planner. Omit to keep the default (all tools available). |
Edit Image Body Json Param
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID. |
prompt | string | Yes | Text description of the edits to apply. |
images | array of ImageInputItem | Yes | Images to edit. (minItems: 1) |
n | integer | No | Number of edited images to generate. Range: 1-10. Defaults to 1. (minimum: 1, maximum: 10, default: 1) |
size | string | No | Requested image shape as width x height (e.g., '1024x1024'). The value is converted into an aspect ratio only; the image is produced at the generator's own fixed output resolution, so the returned pixel dimensions stay constant regardless of the numbers supplied — only the aspect ratio changes. |
response_format | enum ('url', 'b64_json') | No | Format for the edited images. One of url or b64_json. Default: b64_json. (default: b64_json) |
output_format | string | No | Requested file type for the edited images. One of png, jpeg, or webp. Defaults to webp when omitted; any other value is rejected. |
reasoning_strength | enum ('low', 'high') | No | How much reasoning the image generator applies before producing the edited image. One of low or high. low returns after a single generation pass (no self-refinement); high (the default) lets the generator iteratively refine. (default: high) |
moderation | string | No | Moderation level for the safety pipeline. One of auto, low, or none. Supported only on models that accept this parameter; other models reject it with a 400. An unrecognized value is rejected with a 400. none additionally requires per-application access. |
stream | boolean | No | If true, streams the response as server-sent events. Defaults to false. (default: false) |
user | string | No | A stable end-user identifier that helps detect and mitigate abuse. Use it on the images endpoints; on the Responses and Chat Completions endpoints, use safety_identifier instead. |
tool_enablement | ImageToolEnablement | No | Per-tool controls for the image generator's planner. Omit to keep the default (all tools available). |
Image Edit Completed Event
Image edit completed event.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('image_edit.completed') | Yes | Event type; always image_edit.completed. |
b64_json | string | Yes | Base64-encoded edited image data. |
created_at | integer | Yes | Unix timestamp (seconds) for when the event was created. |
output_index | integer (int64) | Yes | Zero-based index of the edited image in the response. |
size | string | No | Requested image shape as width x height. The values set the aspect ratio; the image is produced at the generator's own resolution, so the returned pixel dimensions will not necessarily match the numbers supplied. |
quality | string | No | Quality setting for the edited images. Accepted but ignored. |
background | string | No | Background setting for the edited images. Accepted but ignored. |
output_format | string | No | Output format for the edited images. |
usage | ImageGenUsage | No | Aggregate token usage for the image edit request. Present only on the final completed event. |
Image Edit Partial Image Event
Image edit partial image event.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('image_edit.partial_image') | Yes | Event type; always image_edit.partial_image. |
b64_json | string | Yes | Base64-encoded partial image data. |
created_at | integer | Yes | Unix timestamp (seconds) for when the event was created. |
size | string | No | Requested image shape as width x height. The values set the aspect ratio; the image is produced at the generator's own resolution, so the returned pixel dimensions will not necessarily match the numbers supplied. |
quality | string | No | Quality setting for the edited images. Accepted but ignored. |
background | string | No | Background setting for the edited images. Accepted but ignored. |
output_format | string | No | Output format for the edited images. Accepted but ignored. |
partial_image_index | integer | Yes | Zero-based index for the partial image. |
Image Edit Stream Event
Type: ImageEditPartialImageEvent | ImageEditCompletedEvent
Image Gen Completed Event
Image generation completed event.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('image_generation.completed') | Yes | Event type; always image_generation.completed. |
b64_json | string | Yes | Base64-encoded image data. |
created_at | integer | Yes | Unix timestamp (seconds) for when the event was created. |
output_index | integer (int64) | Yes | Zero-based index of the generated image in the response. |
size | string | No | Requested image shape as width x height. The values set the aspect ratio; the image is produced at the generator's own resolution, so the returned pixel dimensions will not necessarily match the numbers supplied. |
quality | string | No | Quality setting for the generated images. Accepted but ignored. |
background | string | No | Background setting for the generated images. Accepted but ignored. |
output_format | string | No | Output format for the generated images. |
usage | ImageGenUsage | No | Aggregate token usage for the image generation request. Present only on the final completed event. |
Image Gen Partial Image Event
Image generation partial image event.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('image_generation.partial_image') | Yes | Event type; always image_generation.partial_image. |
b64_json | string | Yes | Base64-encoded partial image data. |
created_at | integer | Yes | Unix timestamp (seconds) for when the event was created. |
size | string | No | Requested image shape as width x height. The values set the aspect ratio; the image is produced at the generator's own resolution, so the returned pixel dimensions will not necessarily match the numbers supplied. |
quality | string | No | Quality setting for the generated images. Accepted but ignored. |
background | string | No | Background setting for the generated images. Accepted but ignored. |
output_format | string | No | Output format for the generated images. Accepted but ignored. |
partial_image_index | integer | Yes | Zero-based index of the partial image in the streaming sequence. |
Image Gen Stream Event
Type: ImageGenPartialImageEvent | ImageGenCompletedEvent
Image Gen Usage
| Field | Type | Required | Description |
|---|---|---|---|
input_tokens | integer | No | Number of input tokens. |
input_tokens_details | object | No | Breakdown of input tokens by modality. |
input_tokens_details.image_tokens | integer | No | Number of image tokens in the input. |
input_tokens_details.text_tokens | integer | No | Number of text tokens in the input. |
output_tokens | integer | No | Number of output tokens. |
total_tokens | integer | No | Total number of tokens. |
Image Input Item
| Field | Type | Required | Description |
|---|---|---|---|
image_url | string | No | Image URL. |
file_id | string | No | File ID. |
Image Object
| Field | Type | Required | Description |
|---|---|---|---|
b64_json | string | No | Base64-encoded image data. |
url | string | No | Image URL. |
revised_prompt | string | No | Revised prompt used for the image. |
Image Tool Enablement
Per-tool controls for the image generator's agentic planner. Omit to keep the default (all tools available); set a field to false to disable that tool for the request.
| Field | Type | Required | Description |
|---|---|---|---|
enable_image_search | boolean | No | Whether the image generator may search the web for visual references. false disables it. |
enable_web_search | boolean | No | Whether the image generator may search the web for facts. false disables it (also drops the browser tools). |
enable_shell | boolean | No | Whether the image generator may run code to build layouts and charts. false disables it. |
Images Response
| Field | Type | Required | Description |
|---|---|---|---|
created | integer | Yes | Unix timestamp (seconds) for when the images were created. |
data | array of ImageObject | Yes | Array of generated images. |
output_format | string | No | File type of the generated images. Echoes the requested output_format (png, jpeg, or webp); webp when omitted. |
background | string | No | Background setting for the generated images. Accepted but ignored. |
usage | ImageGenUsage | No | Token usage for the image generation request. |