chore(api): clarify image fidelity and legacy image guidance

.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

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.
     """
 
 

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.
     """
 
 

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.
     """

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`.
     """

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

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

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.
     """
 
 

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.
     """