API Reference

false

false

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

Choose one field, image or images. Either accepts a single reference or an array.

imageoptional

ImageReferences

imagesoptional

ImageReferences

{
  "not": {
    "required": [
      "image",
      "images"
    ]
  }
}

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

imageoptional

stringbinary

PNG, JPEG or WebP file. For multiple files, repeat the image[] field.

image[]optional

array

Constraints

minItems

1

maxItems

16

Array items

stringbinary

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

Choose one field, image or images. Either accepts a single reference or an array.

imageoptional

ImageReferences

imagesoptional

ImageReferences

{
  "not": {
    "required": [
      "image",
      "images"
    ]
  }
}

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

imageoptional

stringbinary

PNG, JPEG or WebP file. For multiple files, repeat the image[] field.

image[]optional

array

Constraints

minItems

1

maxItems

16

Array items

stringbinary

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

Choose one field, image or images. Either accepts a single reference or an array.

imageoptional

ImageReferences

imagesoptional

ImageReferences

{
  "not": {
    "required": [
      "image",
      "images"
    ]
  }
}

maskoptional

ImageMask

modelrequired

string

An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2.

Constraints

minLength

1

maxLength

128

promptrequired

string

Constraints

minLength

1

maxLength

32000

sizeoptional

string

Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default.

Constraints

minLength

1

maxLength

32

pattern

"^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$"

qualityoptional

string

Quality supported by the selected model. Omission uses the model default.

Constraints

minLength

1

maxLength

16

noptional

integer

Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1.

Constraints

minimum

1

maximum

10

output_formatoptional

string

enum["png","jpeg","webp"]

default"png"

backgroundoptional

string

Transparent output requires PNG or WebP.

enum["auto","opaque","transparent"]

moderationoptional

string

enum["auto","low"]

output_compressionoptional

integer

Output compression for JPEG and WebP. Accepted but not applied to PNG.

Constraints

minimum

0

maximum

100

response_formatoptional

string

Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail.

enum["b64_json","url"]

default"b64_json"

streamoptional

boolean

Set to false or omit. For background generation, use the asynchronous endpoints.

constfalse

useroptional

string

Your end-user identifier, saved with the task.

Constraints

maxLength

256

imageoptional

stringbinary

PNG, JPEG or WebP file. For multiple files, repeat the image[] field.

image[]optional

array

Constraints

minItems

1

maxItems

16

Array items

stringbinary

maskoptional

stringbinary

PNG mask with an alpha channel, matching the first reference image's dimensions. Transparent areas mark where to edit. The mask does not count toward the reference-image limit.