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

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 2a4b489d-3431-49f6-b318-70589d7cee19
-openapi_spec_hash: 294e7f8dff5c3715548c61975578ba6f
-openapi_transformed_spec_hash: 6ce29339615c1a0e463408781b8205a4
-config_hash: 18f602826c88bad76c6fdf08ab67247a
-codegen_sha: ec4aba1ca9478ac09e231140c1492fda832dc073
-codegen_hash: d753f1786a9e0a78044f3a7977dad3b950cd7dfd17b575b54556e7267025031e
-public_codegen_sha: 4da9bda69aa4b5348d44d76dbf6f1fbc96304dcb
+generation_id: d883c636-9480-4315-adea-ab1984c5d4ab
+openapi_spec_hash: 095134d95b4b60377eeb716602348023
+openapi_transformed_spec_hash: 1521a437a14e0158810af55c5651aecc
+config_hash: 2f5cd30d104ab1d8c77a7832bfd55eb2
+codegen_sha: 2dc2f6b5b044dfcffd34a877b33343edf335f640
+codegen_hash: 535a8311e078833f2623fc0bfece943e43fe3dc0f62083caf77e77a35f0e82d2
+public_codegen_sha: 0d4078106d393d736277e8543253f74246d03183

lib/openai/models/beta/beta_tool.rb

@@ -632,9 +632,13 @@ class ImageGeneration < OpenAI::Internal::Type::BaseModel
           optional :background, enum: -> { OpenAI::Beta::BetaTool::ImageGeneration::Background }
 
           # @!attribute 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.
+          #   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.
           #
           #   @return [Symbol, OpenAI::Models::Beta::BetaTool::ImageGeneration::InputFidelity, nil]
           optional(
@@ -707,9 +711,7 @@ class ImageGeneration < OpenAI::Internal::Type::BaseModel
           #   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.
           #
           #   @return [String, Symbol, OpenAI::Models::Beta::BetaTool::ImageGeneration::Size, nil]
           optional :size, union: -> { OpenAI::Beta::BetaTool::ImageGeneration::Size }
@@ -732,9 +734,13 @@ class ImageGeneration < OpenAI::Internal::Type::BaseModel
           #     set the output format to `png` or `webp`.
           #
           #   @param input_fidelity [Symbol, OpenAI::Models::Beta::BetaTool::ImageGeneration::InputFidelity, nil]
-          #     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.
           #
           #   @param input_image_mask [OpenAI::Models::Beta::BetaTool::ImageGeneration::InputImageMask]
           #     Optional mask for inpainting. Contains `image_url` (string, optional) and
@@ -777,9 +783,7 @@ class ImageGeneration < OpenAI::Internal::Type::BaseModel
           #     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.
           #
           #   @param type [Symbol, :image_generation]
           #     The type of the image generation tool. Always `image_generation`.
@@ -820,9 +824,13 @@ module Background
             #   @return [Array<Symbol>]
           end
 
-          # 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.
           #
           # @see OpenAI::Models::Beta::BetaTool::ImageGeneration#input_fidelity
           module InputFidelity
@@ -976,9 +984,7 @@ module Quality
           # 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.
           #
           # @see OpenAI::Models::Beta::BetaTool::ImageGeneration#size
           module Size

lib/openai/models/image.rb

@@ -4,23 +4,24 @@ module OpenAI
   module Models
     class Image < OpenAI::Internal::Type::BaseModel
       # @!attribute b64_json
-      #   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`.
+      #   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`.
       #
       #   @return [String, nil]
       optional :b64_json, String
 
       # @!attribute revised_prompt
-      #   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.
       #
       #   @return [String, nil]
       optional :revised_prompt, String
 
       # @!attribute url
-      #   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.
       #
       #   @return [String, nil]
       optional :url, String
@@ -29,17 +30,18 @@ class Image < OpenAI::Internal::Type::BaseModel
       #   Represents the content or the URL of an image generated by the OpenAI API.
       #
       #   @param b64_json [String]
-      #     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`.
+      #     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`.
       #
       #   @param revised_prompt [String]
-      #     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.
       #
       #   @param url [String]
-      #     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.
     end
   end
 end

lib/openai/models/image_create_variation_params.rb

@@ -8,8 +8,8 @@ class ImageCreateVariationParams < OpenAI::Internal::Type::BaseModel
       include OpenAI::Internal::Type::RequestParameters
 
       # @!attribute image
-      #   The image to use as the basis for the variation(s). Must be a valid PNG file,
-      #   less than 4MB, and square.
+      #   The input image for the legacy variations endpoint. The legacy format requires a
+      #   valid PNG file, less than 4MB, and square.
       #
       #   `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
       #   metadata. Use `OpenAI::FilePart` when you need to override the filename or
@@ -19,29 +19,31 @@ class ImageCreateVariationParams < OpenAI::Internal::Type::BaseModel
       required :image, OpenAI::Internal::Type::FileInput
 
       # @!attribute model
-      #   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.
       #
       #   @return [String, Symbol, OpenAI::Models::ImageModel, nil]
       optional :model, union: -> { OpenAI::ImageCreateVariationParams::Model }, nil?: true
 
       # @!attribute n
-      #   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.
       #
       #   @return [Integer, nil]
       optional :n, Integer, nil?: true
 
       # @!attribute 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.
+      #   The response format for the legacy variations endpoint: `url` or `b64_json`.
+      #   Returned URLs were valid for 60 minutes after image generation.
       #
       #   @return [Symbol, OpenAI::Models::ImageCreateVariationParams::ResponseFormat, nil]
       optional :response_format, enum: -> { OpenAI::ImageCreateVariationParams::ResponseFormat }, nil?: true
 
       # @!attribute size
-      #   The size of the generated images. Must be one of `256x256`, `512x512`, or
-      #   `1024x1024`.
+      #   The requested image size for the legacy variations endpoint. Must be one of
+      #   `256x256`, `512x512`, or `1024x1024`.
       #
       #   @return [Symbol, OpenAI::Models::ImageCreateVariationParams::Size, nil]
       optional :size, enum: -> { OpenAI::ImageCreateVariationParams::Size }, nil?: true
@@ -56,28 +58,30 @@ class ImageCreateVariationParams < OpenAI::Internal::Type::BaseModel
 
       # @!method initialize(image:, model: nil, n: nil, response_format: nil, size: nil, user: nil, request_options: {})
       #   @param image [Pathname, StringIO, IO, String, OpenAI::FilePart]
-      #     The image to use as the basis for the variation(s). Must be a valid PNG file,
-      #     less than 4MB, and square.
+      #     The input image for the legacy variations endpoint. The legacy format requires a
+      #     valid PNG file, less than 4MB, and square.
       #
       #     `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
       #     metadata. Use `OpenAI::FilePart` when you need to override the filename or
       #     content type.
       #
       #   @param model [String, Symbol, OpenAI::Models::ImageModel, nil]
-      #     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.
       #
       #   @param n [Integer, nil]
-      #     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.
       #
       #   @param response_format [Symbol, OpenAI::Models::ImageCreateVariationParams::ResponseFormat, nil]
-      #     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.
+      #     The response format for the legacy variations endpoint: `url` or `b64_json`.
+      #     Returned URLs were valid for 60 minutes after image generation.
       #
       #   @param size [Symbol, OpenAI::Models::ImageCreateVariationParams::Size, nil]
-      #     The size of the generated images. Must be one of `256x256`, `512x512`, or
-      #     `1024x1024`.
+      #     The requested image size for the legacy variations endpoint. Must be one of
+      #     `256x256`, `512x512`, or `1024x1024`.
       #
       #   @param user [String]
       #     A unique identifier representing your end-user, which can help OpenAI to monitor
@@ -86,23 +90,24 @@ class ImageCreateVariationParams < OpenAI::Internal::Type::BaseModel
       #
       #   @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}]
 
-      # 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.
       module Model
         extend OpenAI::Internal::Type::Union
 
         variant String
 
-        # 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.
         variant enum: -> { OpenAI::ImageModel }
 
         # @!method self.variants
         #   @return [Array(String, Symbol, OpenAI::Models::ImageModel)]
       end
 
-      # 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.
+      # The response format for the legacy variations endpoint: `url` or `b64_json`.
+      # Returned URLs were valid for 60 minutes after image generation.
       module ResponseFormat
         extend OpenAI::Internal::Type::Enum
 
@@ -113,8 +118,8 @@ module ResponseFormat
         #   @return [Array<Symbol>]
       end
 
-      # The size of the generated images. Must be one of `256x256`, `512x512`, or
-      # `1024x1024`.
+      # The requested image size for the legacy variations endpoint. Must be one of
+      # `256x256`, `512x512`, or `1024x1024`.
       module Size
         extend OpenAI::Internal::Type::Enum