From 11f6ecff0e76bd6d622bd81b3de8e88c160b4059 Mon Sep 17 00:00:00 2001 From: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com> Date: Mon, 21 Sep 2026 05:51:14 +0000 Subject: [PATCH] chore(api): clarify image fidelity and legacy image guidance Castiron-Internal-PR: https://github.com/openai/openai-python-internal/pull/124 Castiron-Source-SHA: d84f221f4059cad13dcd92d937dd0570cecc8abc Castiron-Public-Base-SHA: 69a2c1db6feacf32be6693809e7cab1c3b49cad7 --- .castiron.stats.yml | 14 +- api_reference/openapi.transformed.yml | 123 +--- src/openai/resources/images.py | 628 +++++++++--------- src/openai/types/beta/beta_tool.py | 16 +- src/openai/types/beta/beta_tool_param.py | 16 +- src/openai/types/image.py | 18 +- .../types/image_create_variation_params.py | 24 +- src/openai/types/image_edit_params.py | 42 +- src/openai/types/image_generate_params.py | 48 +- src/openai/types/responses/tool.py | 16 +- src/openai/types/responses/tool_param.py | 16 +- 11 files changed, 476 insertions(+), 485 deletions(-) diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 944ef561cc..8b0a1be3d0 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,8 +1,8 @@ schema_version: 1 -generation_id: feaf88e6-0c6a-4d57-95a5-0bcc23d7105c -openapi_spec_hash: ce912f79d7f8cb19a7a515513c214b8a -openapi_transformed_spec_hash: 352b5a7a028f990b6475b6593e381eee -config_hash: dde98d9c41cd6f4163320f92c70f83e6 -codegen_sha: 799a1f4d5f6b415088641ca4d3bbb804443ec30e -codegen_hash: 7d4da50897149f4eab2fa63ac3dbc972694c6dfeb79a01531da408010bff5dcd -public_codegen_sha: 4b121f228fc198913ea2a56404f38d8f18ca0e86 +generation_id: 020d333d-d28c-4d7e-a052-5b21d994e342 +openapi_spec_hash: 9463cd81496b22aea083ca5d0487c9b4 +openapi_transformed_spec_hash: bf0bde503e128caf8f16da77c0f068a3 +config_hash: 96c2739e5fb89fed6c7777e5a4e74294 +codegen_sha: f21ac14db9442967c5387cdafa517d1a329d93e9 +codegen_hash: 0e5e3e41c83f120632c83994944b00b361a8972da264992ff644c537a43e536f +public_codegen_sha: 6722853c7594ce63eecd5e111032b947cda68513 diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index 30f3e65810..f1e6a23cb1 100644 --- a/api_reference/openapi.transformed.yml +++ b/api_reference/openapi.transformed.yml @@ -7723,7 +7723,7 @@ paths: tags: - Images summary: Create image edit - description: Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models and `dall-e-2`. + description: Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models. DALL·E 2 was retired from the API on May 12, 2026; see [deprecations](https://developers.openai.com/api/docs/deprecations). requestBody: required: true content: @@ -8041,7 +8041,7 @@ paths: tags: - Images summary: Create image variation - description: Creates a variation of a given image. This endpoint only supports `dall-e-2`. + description: Legacy endpoint for creating variations with DALL·E 2, which was retired from the API on May 12, 2026. See [deprecations](https://developers.openai.com/api/docs/deprecations). For new integrations, use image edits with a supported GPT Image model; see the [image generation guide](https://developers.openai.com/api/docs/guides/image-generation). requestBody: required: true content: @@ -8057,62 +8057,6 @@ paths: $ref: '#/components/schemas/ImagesResponse' x-oaiMeta: group: images - examples: - request: - curl: | - curl https://api.openai.com/v1/images/variations \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -F image="@otter.png" \ - -F n=2 \ - -F size="1024x1024" - python: | - from openai import OpenAI - client = OpenAI() - - response = client.images.create_variation( - image=open("image_edit_original.png", "rb"), - n=2, - size="1024x1024" - ) - javascript: |- - import fs from "fs"; - import OpenAI from "openai"; - - const openai = new OpenAI(); - - async function main() { - const image = await openai.images.createVariation({ - image: fs.createReadStream("otter.png"), - }); - - console.log(image.data); - } - main(); - csharp: | - using System; - - using OpenAI.Images; - - ImageClient client = new( - model: "dall-e-2", - apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") - ); - - GeneratedImage image = client.GenerateImageVariation(imageFilePath: "otter.png"); - - Console.WriteLine(image.ImageUri); - response: | - { - "created": 1589478378, - "data": [ - { - "url": "https://..." - }, - { - "url": "https://..." - } - ] - } /live/sessions: post: operationId: create-live @@ -37120,13 +37064,10 @@ components: `gpt-image-2.5-flare-2026-09-08`, and `chatgpt-image-latest`), each image should be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - - For `dall-e-2`, you can only provide one image, and it should be a square - `png` file less than 4MB. x-oaiMeta: exampleFilePath: otter.png prompt: - description: A text description of the desired image(s). The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for the GPT image models. + description: A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models. type: string example: A cute baby sea otter wearing a beret mask: @@ -37173,7 +37114,7 @@ components: - dall-e-2 x-stainless-const: true x-oaiTypeLabel: string - description: The model to use for image generation. One of `dall-e-2` or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. + description: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from the API on May 12, 2026; see [deprecations](https://developers.openai.com/api/docs/deprecations). nullable: true example: gpt-image-2 n: @@ -37195,7 +37136,7 @@ components: - 1536x1024 - 1024x1536 - auto - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. Legacy sizes for the retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. nullable: true response_format: type: string @@ -37204,7 +37145,7 @@ components: - b64_json example: url nullable: true - description: The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter is only supported for `dall-e-2` (default is `url` for `dall-e-2`), as GPT image models always return base64-encoded images. + description: Legacy response-format parameter (`url` or `b64_json`) for the retired `dall-e-2` model. GPT Image models always return base64-encoded images. output_format: type: string enum: @@ -37236,7 +37177,7 @@ components: anyOf: - $ref: '#/components/schemas/InputFidelity' - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Models that accept both `high` and `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, and other models that do not support it. See the [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) for model-specific guidance. stream: type: boolean default: false @@ -37269,7 +37210,7 @@ components: type: object properties: prompt: - description: A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. + description: A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models. Legacy limits for the retired models were 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. type: string example: A cute baby sea otter model: @@ -37291,7 +37232,7 @@ components: - dall-e-3 x-stainless-nominal: false x-oaiTypeLabel: string - description: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used. + description: The GPT Image model to use for image generation. Specify a supported model explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 (`dall-e-3`) were retired from the API on May 12, 2026; see [deprecations](https://developers.openai.com/api/docs/deprecations). nullable: true example: gpt-image-2 n: @@ -37301,7 +37242,7 @@ components: default: 1 example: 1 nullable: true - description: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. + description: The number of images to generate. Must be between 1 and 10. The retired `dall-e-3` model only supported `n=1`. quality: type: string enum: @@ -37324,8 +37265,8 @@ components: - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. response_format: type: string enum: @@ -37334,7 +37275,7 @@ components: default: url example: url nullable: true - description: The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images. + description: 'Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and `dall-e-3` models. Returned URLs were valid for 60 minutes after image generation. This parameter is not supported for the GPT image models, which always return base64-encoded images.' output_format: type: string enum: @@ -37375,7 +37316,7 @@ components: - 512x512 - 1792x1024 - 1024x1792 - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. Legacy sizes for the retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and `1024x1792`. nullable: true moderation: type: string @@ -37414,7 +37355,7 @@ components: default: vivid example: vivid nullable: true - description: The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. + description: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. Vivid produced hyper-real and dramatic images; natural produced more natural, less hyper-real looking images. This parameter is not supported for the GPT image models. user: type: string example: user-1234 @@ -37426,7 +37367,7 @@ components: type: object properties: image: - description: The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square. + description: The input image for the legacy variations endpoint. The legacy format requires a valid PNG file, less than 4MB, and square. type: string format: binary x-oaiMeta: @@ -37439,7 +37380,7 @@ components: - dall-e-2 x-stainless-const: true x-oaiTypeLabel: string - description: The model to use for image generation. Only `dall-e-2` is supported at this time. + description: Legacy model selection for the variations endpoint, which was designed for `dall-e-2`. DALL·E 2 was retired from the API on May 12, 2026; see [deprecations](https://developers.openai.com/api/docs/deprecations). Use image edits with a supported GPT Image model for new integrations. nullable: true n: type: integer @@ -37448,7 +37389,7 @@ components: default: 1 example: 1 nullable: true - description: The number of images to generate. Must be between 1 and 10. + description: The number of images requested from the legacy variations endpoint. Must be between 1 and 10. response_format: type: string enum: @@ -37457,7 +37398,7 @@ components: default: url example: url nullable: true - description: The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. + description: 'The response format for the legacy variations endpoint: `url` or `b64_json`. Returned URLs were valid for 60 minutes after image generation.' size: type: string enum: @@ -37467,7 +37408,7 @@ components: default: 1024x1024 example: 1024x1024 nullable: true - description: The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`. + description: The requested image size for the legacy variations endpoint. Must be one of `256x256`, `512x512`, or `1024x1024`. user: type: string example: user-1234 @@ -39485,7 +39426,7 @@ components: Use `images` (array of `ImageRefParam`) instead of multipart `image` uploads. You can reference images via external URLs, data URLs, or uploaded file IDs. - JSON edits support GPT image models only; DALL-E edits require multipart (`dall-e-2` only). + JSON edits support GPT image models only. properties: model: anyOf: @@ -39557,7 +39498,7 @@ components: - high - low - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Models that accept both `high` and `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, and other models that do not support it. See the [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) for model-specific guidance. size: anyOf: - type: string @@ -42862,14 +42803,14 @@ components: properties: b64_json: type: string - description: The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`. + description: The base64-encoded image data. Returned by default for the GPT image models. For the retired `dall-e-2` and `dall-e-3` models, this field was present only when `response_format` was set to `b64_json`. url: type: string format: uri - description: When using `dall-e-2` or `dall-e-3`, the URL of the generated image if `response_format` is set to `url` (default value). Unsupported for the GPT image models. + description: 'Legacy field for the retired `dall-e-2` and `dall-e-3` models: the URL of the generated image when `response_format` was set to `url`, the legacy default. Unsupported for the GPT image models.' revised_prompt: type: string - description: For `dall-e-3` only, the revised prompt that was used to generate the image. + description: 'Legacy field for the retired `dall-e-3` model: the revised prompt that was used to generate the image.' ImageEditCompletedEvent: type: object description: | @@ -43294,7 +43235,7 @@ components: - 1024x1536 - 1536x1024 - auto - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. default: auto output_format: type: string @@ -43343,7 +43284,7 @@ components: anyOf: - $ref: '#/components/schemas/InputFidelity' - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supported models accept `high` and `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, and other models that do not support it. See the [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) for model-specific guidance. input_image_mask: type: object description: | @@ -68175,7 +68116,7 @@ components: enum: - high - low - description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supported models accept `high` and `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for models that do not support it. LocalShellToolParam: properties: type: @@ -80509,6 +80450,7 @@ components: - $ref: '#/components/schemas/ReasoningEffortParam' - type: 'null' description: Omit to keep the current effort. Null selects the model's default effort. + x-openai-go-optional-enum: true additionalProperties: false description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged. UpdateSessionAgentParam: @@ -80527,6 +80469,7 @@ components: - $ref: '#/components/schemas/ServiceTierParam' - type: 'null' description: Omit to keep the current tier. Null resets it to auto. + x-openai-go-optional-enum: true additionalProperties: false description: Model settings that can change after session creation. UpdateAgentSessionParams: @@ -85029,7 +84972,7 @@ components: - 1024x1536 - 1536x1024 - auto - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. default: auto output_format: type: string @@ -85078,7 +85021,7 @@ components: anyOf: - $ref: '#/components/schemas/BetaInputFidelity' - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supported models accept `high` and `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, and other models that do not support it. See the [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) for model-specific guidance. input_image_mask: type: object description: | @@ -85119,7 +85062,7 @@ components: enum: - high - low - description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supported models accept `high` and `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on models that support this parameter. Omit this parameter for models that do not support it. BetaProgrammaticToolCallingParam: properties: type: diff --git a/src/openai/resources/images.py b/src/openai/resources/images.py index 7c3df384d5..6608e8b199 100644 --- a/src/openai/resources/images.py +++ b/src/openai/resources/images.py @@ -63,25 +63,30 @@ def create_variation( extra_body: Body | None = None, timeout: float | httpx2.Timeout | None | NotGiven = not_given, ) -> ImagesResponse: - """Creates a variation of a given image. - - This endpoint only supports `dall-e-2`. + """ + Legacy endpoint for creating variations with DALL·E 2, which was retired from + the API on May 12, 2026. See + [deprecations](https://developers.openai.com/api/docs/deprecations). For new + integrations, use image edits with a supported GPT Image model; see the + [image generation guide](https://developers.openai.com/api/docs/guides/image-generation). Args: - image: The image to use as the basis for the variation(s). Must be a valid PNG file, - less than 4MB, and square. + image: The input image for the legacy variations endpoint. The legacy format requires a + valid PNG file, less than 4MB, and square. - model: The model to use for image generation. Only `dall-e-2` is supported at this - time. + model: Legacy model selection for the variations endpoint, which was designed for + `dall-e-2`. DALL·E 2 was retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Use image + edits with a supported GPT Image model for new integrations. - n: The number of images to generate. Must be between 1 and 10. + n: The number of images requested from the legacy variations endpoint. Must be + between 1 and 10. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. + response_format: The response format for the legacy variations endpoint: `url` or `b64_json`. + Returned URLs were valid for 60 minutes after image generation. - size: The size of the generated images. Must be one of `256x256`, `512x512`, or - `1024x1024`. + size: The requested image size for the legacy variations endpoint. Must be one of + `256x256`, `512x512`, or `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -155,7 +160,9 @@ def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -167,11 +174,8 @@ def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. background: Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, @@ -183,21 +187,27 @@ def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -221,10 +231,8 @@ def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -235,9 +243,8 @@ def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -287,7 +294,9 @@ def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -299,11 +308,8 @@ def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -319,21 +325,27 @@ def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -357,10 +369,8 @@ def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -371,9 +381,8 @@ def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -419,7 +428,9 @@ def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -431,11 +442,8 @@ def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -451,21 +459,27 @@ def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -489,10 +503,8 @@ def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -503,9 +515,8 @@ def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -628,8 +639,8 @@ def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. background: Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, @@ -641,19 +652,20 @@ def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -676,13 +688,13 @@ def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -693,18 +705,19 @@ def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) for more information. This parameter is only supported for the GPT image models. - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -756,8 +769,8 @@ def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -773,19 +786,20 @@ def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -808,13 +822,13 @@ def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -825,14 +839,15 @@ def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -884,8 +899,8 @@ def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -901,19 +916,20 @@ def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -936,13 +952,13 @@ def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -953,14 +969,15 @@ def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1080,25 +1097,30 @@ async def create_variation( extra_body: Body | None = None, timeout: float | httpx2.Timeout | None | NotGiven = not_given, ) -> ImagesResponse: - """Creates a variation of a given image. - - This endpoint only supports `dall-e-2`. + """ + Legacy endpoint for creating variations with DALL·E 2, which was retired from + the API on May 12, 2026. See + [deprecations](https://developers.openai.com/api/docs/deprecations). For new + integrations, use image edits with a supported GPT Image model; see the + [image generation guide](https://developers.openai.com/api/docs/guides/image-generation). Args: - image: The image to use as the basis for the variation(s). Must be a valid PNG file, - less than 4MB, and square. + image: The input image for the legacy variations endpoint. The legacy format requires a + valid PNG file, less than 4MB, and square. - model: The model to use for image generation. Only `dall-e-2` is supported at this - time. + model: Legacy model selection for the variations endpoint, which was designed for + `dall-e-2`. DALL·E 2 was retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Use image + edits with a supported GPT Image model for new integrations. - n: The number of images to generate. Must be between 1 and 10. + n: The number of images requested from the legacy variations endpoint. Must be + between 1 and 10. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. + response_format: The response format for the legacy variations endpoint: `url` or `b64_json`. + Returned URLs were valid for 60 minutes after image generation. - size: The size of the generated images. Must be one of `256x256`, `512x512`, or - `1024x1024`. + size: The requested image size for the legacy variations endpoint. Must be one of + `256x256`, `512x512`, or `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1172,7 +1194,9 @@ async def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -1184,11 +1208,8 @@ async def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. background: Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, @@ -1200,21 +1221,27 @@ async def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -1238,10 +1265,8 @@ async def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1252,9 +1277,8 @@ async def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -1304,7 +1328,9 @@ async def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -1316,11 +1342,8 @@ async def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -1336,21 +1359,27 @@ async def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -1374,10 +1403,8 @@ async def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1388,9 +1415,8 @@ async def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1436,7 +1462,9 @@ async def edit( """Creates an edited or extended image given one or more source images and a prompt. - This endpoint supports GPT Image models and `dall-e-2`. + This endpoint supports GPT Image models. DALL·E 2 was retired from the API on + May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Args: image: The image(s) to edit. Must be a supported image file or an array of images. @@ -1448,11 +1476,8 @@ async def edit( be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. - - prompt: A text description of the desired image(s). The maximum length is 1000 - characters for `dall-e-2`, and 32000 characters for the GPT image models. + prompt: A text description of the desired image(s). The maximum length is 32000 + characters for the GPT image models. stream: Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -1468,21 +1493,27 @@ async def edit( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - input_fidelity: Controls fidelity to the original input image(s). This parameter is supported - for GPT image models that support input fidelity. `gpt-image-2` and - `gpt-image-2-2026-04-21` ignore this parameter. + input_fidelity: Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. mask: An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. - model: The model to use for image generation. One of `dall-e-2` or a GPT image model - (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`). Defaults to - `gpt-image-1.5`. + model: The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, + `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). n: The number of images to generate. Must be between 1 and 10. @@ -1506,10 +1537,8 @@ async def edit( `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`. - response_format: The format in which the generated images are returned. Must be one of `url` or - `b64_json`. URLs are only valid for 60 minutes after the image has been - generated. This parameter is only supported for `dall-e-2` (default is `url` for - `dall-e-2`), as GPT image models always return base64-encoded images. + response_format: Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1520,9 +1549,8 @@ async def edit( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1645,8 +1673,8 @@ async def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. background: Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, @@ -1658,19 +1686,20 @@ async def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -1693,13 +1722,13 @@ async def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1710,18 +1739,19 @@ async def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) for more information. This parameter is only supported for the GPT image models. - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1773,8 +1803,8 @@ async def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -1790,19 +1820,20 @@ async def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -1825,13 +1856,13 @@ async def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1842,14 +1873,15 @@ async def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. @@ -1901,8 +1933,8 @@ async def generate( Args: prompt: A text description of the desired image(s). The maximum length is 32000 - characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 - characters for `dall-e-3`. + characters for the GPT image models. Legacy limits for the retired models were + 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. stream: Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation) @@ -1918,19 +1950,20 @@ async def generate( `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - model: The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT - image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` unless a parameter - specific to the GPT image models is used. + model: The GPT Image model to use for image generation. Specify a supported model + explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, + `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, or + `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 (`dall-e-2`) and DALL·E 3 + (`dall-e-3`) were retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). moderation: Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value). - n: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only - `n=1` is supported. + n: The number of images to generate. Must be between 1 and 10. The retired + `dall-e-3` model only supported `n=1`. output_compression: The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and @@ -1953,13 +1986,13 @@ async def generate( - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. - response_format: The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes - after the image has been generated. This parameter isn't supported for the GPT - image models, which always return base64-encoded images. + response_format: Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. size: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, @@ -1970,14 +2003,15 @@ async def generate( the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; - `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use - one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of - `1024x1024`, `1792x1024`, or `1024x1792`. - - style: The style of the generated images. This parameter is only supported for - `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean - towards generating hyper-real and dramatic images. Natural causes the model to - produce more natural, less hyper-real looking images. + `auto` is supported for models that allow automatic sizing. Legacy sizes for the + retired `dall-e-2` model were `256x256`, `512x512`, and `1024x1024`. Legacy + sizes for the retired `dall-e-3` model were `1024x1024`, `1792x1024`, and + `1024x1792`. + + style: Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. diff --git a/src/openai/types/beta/beta_tool.py b/src/openai/types/beta/beta_tool.py index 942b2b108f..051ec1e985 100644 --- a/src/openai/types/beta/beta_tool.py +++ b/src/openai/types/beta/beta_tool.py @@ -279,10 +279,14 @@ class ImageGeneration(BaseModel): """ input_fidelity: Optional[Literal["high", "low"]] = None - """Controls fidelity to the original input image(s). - - This parameter is supported for GPT image models that support input fidelity. - `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Supported models accept `high` and + `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on + models that support this parameter. Omit this parameter for `gpt-image-2`, + `gpt-image-2-2026-04-21`, and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. """ input_image_mask: Optional[ImageGenerationInputImageMask] = None @@ -354,9 +358,7 @@ class ImageGeneration(BaseModel): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. """ diff --git a/src/openai/types/beta/beta_tool_param.py b/src/openai/types/beta/beta_tool_param.py index 21558958e5..67c3e7b224 100644 --- a/src/openai/types/beta/beta_tool_param.py +++ b/src/openai/types/beta/beta_tool_param.py @@ -278,10 +278,14 @@ class ImageGeneration(TypedDict, total=False): """ input_fidelity: Optional[Literal["high", "low"]] - """Controls fidelity to the original input image(s). - - This parameter is supported for GPT image models that support input fidelity. - `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Supported models accept `high` and + `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on + models that support this parameter. Omit this parameter for `gpt-image-2`, + `gpt-image-2-2026-04-21`, and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. """ input_image_mask: ImageGenerationInputImageMask @@ -352,9 +356,7 @@ class ImageGeneration(TypedDict, total=False): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. """ diff --git a/src/openai/types/image.py b/src/openai/types/image.py index 882300d927..92cd25424a 100644 --- a/src/openai/types/image.py +++ b/src/openai/types/image.py @@ -11,18 +11,22 @@ class Image(BaseModel): """Represents the content or the URL of an image generated by the OpenAI API.""" b64_json: Optional[str] = None - """The base64-encoded JSON of the generated image. + """The base64-encoded image data. - Returned by default for the GPT image models, and only present if - `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`. + Returned by default for the GPT image models. For the retired `dall-e-2` and + `dall-e-3` models, this field was present only when `response_format` was set to + `b64_json`. """ revised_prompt: Optional[str] = None - """For `dall-e-3` only, the revised prompt that was used to generate the image.""" + """ + Legacy field for the retired `dall-e-3` model: the revised prompt that was used + to generate the image. + """ url: Optional[str] = None """ - When using `dall-e-2` or `dall-e-3`, the URL of the generated image if - `response_format` is set to `url` (default value). Unsupported for the GPT image - models. + Legacy field for the retired `dall-e-2` and `dall-e-3` models: the URL of the + generated image when `response_format` was set to `url`, the legacy default. + Unsupported for the GPT image models. """ diff --git a/src/openai/types/image_create_variation_params.py b/src/openai/types/image_create_variation_params.py index a33840d2c6..76751e922a 100644 --- a/src/openai/types/image_create_variation_params.py +++ b/src/openai/types/image_create_variation_params.py @@ -13,29 +13,33 @@ class ImageCreateVariationParams(TypedDict, total=False): image: Required[FileTypes] - """The image to use as the basis for the variation(s). + """The input image for the legacy variations endpoint. - Must be a valid PNG file, less than 4MB, and square. + The legacy format requires a valid PNG file, less than 4MB, and square. """ model: Union[str, ImageModel, None] - """The model to use for image generation. - - Only `dall-e-2` is supported at this time. + """ + Legacy model selection for the variations endpoint, which was designed for + `dall-e-2`. DALL·E 2 was retired from the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). Use image + edits with a supported GPT Image model for new integrations. """ n: Optional[int] - """The number of images to generate. Must be between 1 and 10.""" + """The number of images requested from the legacy variations endpoint. + + Must be between 1 and 10. + """ response_format: Optional[Literal["url", "b64_json"]] - """The format in which the generated images are returned. + """The response format for the legacy variations endpoint: `url` or `b64_json`. - Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the - image has been generated. + Returned URLs were valid for 60 minutes after image generation. """ size: Optional[Literal["256x256", "512x512", "1024x1024"]] - """The size of the generated images. + """The requested image size for the legacy variations endpoint. Must be one of `256x256`, `512x512`, or `1024x1024`. """ diff --git a/src/openai/types/image_edit_params.py b/src/openai/types/image_edit_params.py index 0cf8368312..cd1be35850 100644 --- a/src/openai/types/image_edit_params.py +++ b/src/openai/types/image_edit_params.py @@ -21,16 +21,12 @@ class ImageEditParamsBase(TypedDict, total=False): `gpt-image-2.5-flare-2026-09-08`, and `chatgpt-image-latest`), each image should be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. - - For `dall-e-2`, you can only provide one image, and it should be a square `png` - file less than 4MB. """ prompt: Required[str] """A text description of the desired image(s). - The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for - the GPT image models. + The maximum length is 32000 characters for the GPT image models. """ background: Optional[Literal["transparent", "opaque", "auto"]] @@ -48,10 +44,15 @@ class ImageEditParamsBase(TypedDict, total=False): """ input_fidelity: Optional[Literal["high", "low"]] - """Controls fidelity to the original input image(s). - - This parameter is supported for GPT image models that support input fidelity. - `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Models that accept both `high` and + `low` include `gpt-image-1`, `gpt-image-1.5`, and `chatgpt-image-latest`. + `gpt-image-1-mini` accepts only `low`. Defaults to `low` on models that support + this parameter. Omit this parameter for `gpt-image-2`, `gpt-image-2-2026-04-21`, + and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. """ mask: FileTypes @@ -63,13 +64,14 @@ class ImageEditParamsBase(TypedDict, total=False): """ model: Union[str, ImageModel, None] - """The model to use for image generation. - - One of `dall-e-2` or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, + """ + The GPT Image model to use for image editing (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or - `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. + `chatgpt-image-latest`). Defaults to `gpt-image-1.5`. DALL·E 2 was retired from + the API on May 12, 2026; see + [deprecations](https://developers.openai.com/api/docs/deprecations). """ n: Optional[int] @@ -109,12 +111,9 @@ class ImageEditParamsBase(TypedDict, total=False): """ response_format: Optional[Literal["url", "b64_json"]] - """The format in which the generated images are returned. - - Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the - image has been generated. This parameter is only supported for `dall-e-2` - (default is `url` for `dall-e-2`), as GPT image models always return - base64-encoded images. + """ + Legacy response-format parameter (`url` or `b64_json`) for the retired + `dall-e-2` model. GPT Image models always return base64-encoded images. """ size: Union[str, Literal["256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto"], None] @@ -129,9 +128,8 @@ class ImageEditParamsBase(TypedDict, total=False): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. Legacy sizes for the retired `dall-e-2` + model were `256x256`, `512x512`, and `1024x1024`. """ user: str diff --git a/src/openai/types/image_generate_params.py b/src/openai/types/image_generate_params.py index 339276d2c8..f41346061e 100644 --- a/src/openai/types/image_generate_params.py +++ b/src/openai/types/image_generate_params.py @@ -14,8 +14,9 @@ class ImageGenerateParamsBase(TypedDict, total=False): prompt: Required[str] """A text description of the desired image(s). - The maximum length is 32000 characters for the GPT image models, 1000 characters - for `dall-e-2` and 4000 characters for `dall-e-3`. + The maximum length is 32000 characters for the GPT image models. Legacy limits + for the retired models were 1000 characters for `dall-e-2` and 4000 characters + for `dall-e-3`. """ background: Optional[Literal["transparent", "opaque", "auto"]] @@ -33,13 +34,14 @@ class ImageGenerateParamsBase(TypedDict, total=False): """ model: Union[str, ImageModel, None] - """The model to use for image generation. + """The GPT Image model to use for image generation. - One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, - `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, + Specify a supported model explicitly, such as `gpt-image-1`, `gpt-image-1-mini`, + `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, - `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`). Defaults to `dall-e-2` - unless a parameter specific to the GPT image models is used. + `gpt-image-2.5-flare`, or `gpt-image-2.5-flare-2026-09-08`. DALL·E 2 + (`dall-e-2`) and DALL·E 3 (`dall-e-3`) were retired from the API on May 12, + 2026; see [deprecations](https://developers.openai.com/api/docs/deprecations). """ moderation: Optional[Literal["low", "auto"]] @@ -52,7 +54,7 @@ class ImageGenerateParamsBase(TypedDict, total=False): n: Optional[int] """The number of images to generate. - Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. + Must be between 1 and 10. The retired `dall-e-3` model only supported `n=1`. """ output_compression: Optional[int] @@ -88,17 +90,16 @@ class ImageGenerateParamsBase(TypedDict, total=False): - `high`, `medium` and `low` are supported for the GPT image models. - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. - - `hd` and `standard` are supported for `dall-e-3`. - - `standard` is the only option for `dall-e-2`. + - The retired `dall-e-3` model supported the legacy values `hd` and `standard`. + - The retired `dall-e-2` model only supported the legacy value `standard`. """ response_format: Optional[Literal["url", "b64_json"]] - """The format in which generated images with `dall-e-2` and `dall-e-3` are - returned. - - Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the - image has been generated. This parameter isn't supported for the GPT image - models, which always return base64-encoded images. + """ + Legacy response format: `url` or `b64_json`, for the retired `dall-e-2` and + `dall-e-3` models. Returned URLs were valid for 60 minutes after image + generation. This parameter is not supported for the GPT image models, which + always return base64-encoded images. """ size: Union[ @@ -117,18 +118,17 @@ class ImageGenerateParamsBase(TypedDict, total=False): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. Legacy sizes for the retired `dall-e-2` + model were `256x256`, `512x512`, and `1024x1024`. Legacy sizes for the retired + `dall-e-3` model were `1024x1024`, `1792x1024`, and `1024x1792`. """ style: Optional[Literal["vivid", "natural"]] - """The style of the generated images. + """Legacy style options `vivid` and `natural` for the retired `dall-e-3` model. - This parameter is only supported for `dall-e-3`. Must be one of `vivid` or - `natural`. Vivid causes the model to lean towards generating hyper-real and - dramatic images. Natural causes the model to produce more natural, less - hyper-real looking images. + Vivid produced hyper-real and dramatic images; natural produced more natural, + less hyper-real looking images. This parameter is not supported for the GPT + image models. """ user: str diff --git a/src/openai/types/responses/tool.py b/src/openai/types/responses/tool.py index 214a761d98..d1bdc6983d 100644 --- a/src/openai/types/responses/tool.py +++ b/src/openai/types/responses/tool.py @@ -284,10 +284,14 @@ class ImageGeneration(BaseModel): """ input_fidelity: Optional[Literal["high", "low"]] = None - """Controls fidelity to the original input image(s). - - This parameter is supported for GPT image models that support input fidelity. - `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Supported models accept `high` and + `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on + models that support this parameter. Omit this parameter for `gpt-image-2`, + `gpt-image-2-2026-04-21`, and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. """ input_image_mask: Optional[ImageGenerationInputImageMask] = None @@ -359,9 +363,7 @@ class ImageGeneration(BaseModel): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. """ diff --git a/src/openai/types/responses/tool_param.py b/src/openai/types/responses/tool_param.py index 8bef6cb79a..05b692c4af 100644 --- a/src/openai/types/responses/tool_param.py +++ b/src/openai/types/responses/tool_param.py @@ -284,10 +284,14 @@ class ImageGeneration(TypedDict, total=False): """ input_fidelity: Optional[Literal["high", "low"]] - """Controls fidelity to the original input image(s). - - This parameter is supported for GPT image models that support input fidelity. - `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. Supported models accept `high` and + `low`, except `gpt-image-1-mini`, which accepts only `low`. Defaults to `low` on + models that support this parameter. Omit this parameter for `gpt-image-2`, + `gpt-image-2-2026-04-21`, and other models that do not support it. See the + [image input fidelity guide](https://developers.openai.com/api/docs/guides/image-generation#image-input-fidelity) + for model-specific guidance. """ input_image_mask: ImageGenerationInputImageMask @@ -358,9 +362,7 @@ class ImageGeneration(TypedDict, total=False): resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for - models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, - `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, - or `1024x1792`. + models that allow automatic sizing. """