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 or low. Enabled per model: on models where it is not enabled, any moderation value returns 400 (code: unsupported_parameter, param: moderation); omitting moderation is always valid. On enabled models, unknown or empty values return 400. |
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 or low. Enabled per model: on models where it is not enabled, any moderation value returns 400 (code: unsupported_parameter, param: moderation); omitting moderation is always valid. On enabled models, unknown or empty values return 400. |
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) |
temperature | number | No | Sampling temperature for the model's planning step (prompt writing and refinement), between 0 and 2. It does not change how the image itself is sampled. Omit it to keep the model default. (minimum: 0, maximum: 2) |
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) |
temperature | number | No | Sampling temperature for the model's planning step (prompt writing and refinement), between 0 and 2. It does not change how the image itself is sampled. Omit it to keep the model default. (minimum: 0, maximum: 2) |
moderation | string | No | Moderation level for the safety pipeline. One of auto or low. Enabled per model: on models where it is not enabled, any moderation value returns 400 (code: unsupported_parameter, param: moderation); omitting moderation is always valid. On enabled models, unknown or empty values return 400. |
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. |
| 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. |
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. |
Mirrored from dev.meta.ai/docs/api-reference/images/schemas (synced Oct 30, 2026). Text and examples © Meta. Live demos run on Muse Muse's key.