docs: clarify image transparency and Realtime audio delta behavior (#918)

## Summary

Updates Java SDK documentation to note that transparent backgrounds are
in preview for gpt-image-2 and gpt-image-2-2026-04-21, with png or webp
required for transparent output. Also clarifies that Realtime
translation audio deltas contain variable-length PCM16 chunks that
clients should decode and queue in full. No API signatures or runtime
behavior change.

Co-authored-by: apcha-oai <228803254+apcha-oai@users.noreply.github.com>

Author: apcha-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 39f410ad-4a12-4b68-83fb-a8f8910269c3
-openapi_spec_hash: a85edbfc22ff719d064bce2705c7394e
-openapi_transformed_spec_hash: f8e7644df5aee22dfcd0ea2b70942054
-config_hash: 85382dd94c503b5d225adc7636a77c9f
-codegen_sha: 22efddac3ef54c84888af2bcaf836358ecc6c728
-codegen_hash: 2b381e76f9cb96c14cfaad5973e6f1bde237796fc22583eee2ed857e16587cb5
-public_codegen_sha: 073a9e1da881c9dce551ca447b52045c93ee161a
+generation_id: d8a1420b-a1ed-40ae-8675-e79d0e6fe5ce
+openapi_spec_hash: 92700e1a33a4f6174a01b46648c8186a
+openapi_transformed_spec_hash: e37bbe0f04caa6093f1cb5d65d23ad03
+config_hash: d13c582815d0db08c374985806be7352
+codegen_sha: 48b2b7ead2af6d92c34149aa44744f7e2ae4367a
+codegen_hash: f7d9f64ad58ebcf8291c4168c4322d6cc0c5ef1fe934f58dd7f785338920a919
+public_codegen_sha: ad61fb7c99fae3ed2d764fc4eb31db395ea44b33

api_reference/openapi.transformed.yml

@@ -33071,18 +33071,14 @@ components:
           nullable: true
           description: |
             Allows to set transparency for the background of the generated image(s).
-            This parameter is only supported for GPT image models that support
-            transparent backgrounds. Must be one of `transparent`, `opaque`, or
-            `auto` (default value). When `auto` is used, the model will
-            automatically determine the best background for the image.
-
-            `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
-            transparent backgrounds. Requests with `background` set to
-            `transparent` will return an error for these models; use `opaque` or
-            `auto` instead.
-
-            If `transparent`, the output format needs to support transparency,
-            so it should be set to either `png` (default value) or `webp`.
+            Must be one of `transparent`, `opaque`, or `auto` (default value). When
+            `auto` is used, the model will automatically determine the best
+            background for the image.
+
+            Transparent backgrounds are available for supported GPT Image models.
+            For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in
+            preview. When using `transparent`, set the output format to `png` or
+            `webp`.
         model:
           anyOf:
           - type: string
@@ -33310,18 +33306,14 @@ components:
           nullable: true
           description: |
             Allows to set transparency for the background of the generated image(s).
-            This parameter is only supported for GPT image models that support
-            transparent backgrounds. Must be one of `transparent`, `opaque`, or
-            `auto` (default value). When `auto` is used, the model will
-            automatically determine the best background for the image.
-
-            `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
-            transparent backgrounds. Requests with `background` set to
-            `transparent` will return an error for these models; use `opaque` or
-            `auto` instead.
-
-            If `transparent`, the output format needs to support transparency,
-            so it should be set to either `png` (default value) or `webp`.
+            Must be one of `transparent`, `opaque`, or `auto` (default value). When
+            `auto` is used, the model will automatically determine the best
+            background for the image.
+
+            Transparent backgrounds are available for supported GPT Image models.
+            For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in
+            preview. When using `transparent`, set the output format to `png` or
+            `webp`.
         style:
           type: string
           enum:
@@ -35512,7 +35504,7 @@ components:
           - type: 'null'
           default: auto
           example: transparent
-          description: Background behavior for generated image output.
+          description: Set the background of the generated image output. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`.
         stream:
           anyOf:
           - type: boolean
@@ -39198,18 +39190,14 @@ components:
           - auto
           description: |
             Allows to set transparency for the background of the generated image(s).
-            This parameter is only supported for GPT image models that support
-            transparent backgrounds. Must be one of `transparent`, `opaque`, or
-            `auto` (default value). When `auto` is used, the model will
-            automatically determine the best background for the image.
-
-            `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
-            transparent backgrounds. Requests with `background` set to
-            `transparent` will return an error for these models; use `opaque` or
-            `auto` instead.
-
-            If `transparent`, the output format needs to support transparency,
-            so it should be set to either `png` (default value) or `webp`.
+            Must be one of `transparent`, `opaque`, or `auto` (default value). When
+            `auto` is used, the model will automatically determine the best
+            background for the image.
+
+            Transparent backgrounds are available for supported GPT Image models.
+            For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in
+            preview. When using `transparent`, set the output format to `png` or
+            `webp`.
           default: auto
         input_fidelity:
           anyOf:
@@ -51417,8 +51405,9 @@ components:
     RealtimeTranslationServerEventSessionOutputAudioDelta:
       type: object
       description: |
-        Returned when translated output audio is available. Output audio deltas are
-        200 ms frames of PCM16 audio.
+        Returned when translated output audio is available. The `delta` contains a
+        PCM16 audio chunk whose length can vary. Clients should decode and queue the
+        complete delta instead of assuming a fixed byte or sample count.
       properties:
         event_id:
           type: string
@@ -68577,18 +68566,14 @@ components:
           - auto
           description: |
             Allows to set transparency for the background of the generated image(s).
-            This parameter is only supported for GPT image models that support
-            transparent backgrounds. Must be one of `transparent`, `opaque`, or
-            `auto` (default value). When `auto` is used, the model will
-            automatically determine the best background for the image.
-
-            `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
-            transparent backgrounds. Requests with `background` set to
-            `transparent` will return an error for these models; use `opaque` or
-            `auto` instead.
-
-            If `transparent`, the output format needs to support transparency,
-            so it should be set to either `png` (default value) or `webp`.
+            Must be one of `transparent`, `opaque`, or `auto` (default value). When
+            `auto` is used, the model will automatically determine the best
+            background for the image.
+
+            Transparent backgrounds are available for supported GPT Image models.
+            For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in
+            preview. When using `transparent`, set the output format to `png` or
+            `webp`.
           default: auto
         input_fidelity:
           anyOf:

openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaTool.kt

@@ -5110,17 +5110,13 @@ private constructor(
         fun action(): Optional<Action> = action.getOptional("action")
 
         /**
-         * Allows to set transparency for the background of the generated image(s). This parameter
-         * is only supported for GPT image models that support transparent backgrounds. Must be one
-         * of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model
-         * will automatically determine the best background for the image.
+         * 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, the model will
+         * automatically determine the best background for the image.
          *
-         * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-         * Requests with `background` set to `transparent` will return an error for these models;
-         * use `opaque` or `auto` instead.
-         *
-         * If `transparent`, the output format needs to support transparency, so it should be set to
-         * either `png` (default value) or `webp`.
+         * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2`
+         * and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set
+         * the output format to `png` or `webp`.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -5392,18 +5388,13 @@ private constructor(
             fun action(action: JsonField<Action>) = apply { this.action = action }
 
             /**
-             * Allows to set transparency for the background of the generated image(s). This
-             * parameter is only supported for GPT image models that support transparent
-             * backgrounds. Must be one of `transparent`, `opaque`, or `auto` (default value). When
-             * `auto` is used, the model will automatically determine the best background for the
-             * image.
-             *
-             * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-             * Requests with `background` set to `transparent` will return an error for these
-             * models; use `opaque` or `auto` instead.
+             * 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, the model
+             * will automatically determine the best background for the image.
              *
-             * If `transparent`, the output format needs to support transparency, so it should be
-             * set to either `png` (default value) or `webp`.
+             * Transparent backgrounds are available for supported GPT Image models. For
+             * `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using
+             * `transparent`, set the output format to `png` or `webp`.
              */
             fun background(background: Background) = background(JsonField.of(background))
 
@@ -5846,17 +5837,13 @@ private constructor(
         }
 
         /**
-         * Allows to set transparency for the background of the generated image(s). This parameter
-         * is only supported for GPT image models that support transparent backgrounds. Must be one
-         * of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model
-         * will automatically determine the best background for the image.
-         *
-         * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-         * Requests with `background` set to `transparent` will return an error for these models;
-         * use `opaque` or `auto` instead.
+         * 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, the model will
+         * automatically determine the best background for the image.
          *
-         * If `transparent`, the output format needs to support transparency, so it should be set to
-         * either `png` (default value) or `webp`.
+         * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2`
+         * and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set
+         * the output format to `png` or `webp`.
          */
         class Background @JsonCreator private constructor(private val value: JsonField<String>) :
             Enum {

openai-java-core/src/main/kotlin/com/openai/models/images/ImageEditParams.kt

@@ -68,17 +68,13 @@ private constructor(
     fun prompt(): String = body.prompt()
 
     /**
-     * Allows to set transparency for the background of the generated image(s). This parameter is
-     * only supported for GPT image models that support transparent backgrounds. Must be one of
+     * 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, the model will
      * automatically determine the best background for the image.
      *
-     * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds. Requests
-     * with `background` set to `transparent` will return an error for these models; use `opaque` or
-     * `auto` instead.
-     *
-     * If `transparent`, the output format needs to support transparency, so it should be set to
-     * either `png` (default value) or `webp`.
+     * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+     * `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the
+     * output format to `png` or `webp`.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -423,17 +419,13 @@ private constructor(
         fun prompt(prompt: MultipartField<String>) = apply { body.prompt(prompt) }
 
         /**
-         * Allows to set transparency for the background of the generated image(s). This parameter
-         * is only supported for GPT image models that support transparent backgrounds. Must be one
-         * of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model
-         * will automatically determine the best background for the image.
-         *
-         * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-         * Requests with `background` set to `transparent` will return an error for these models;
-         * use `opaque` or `auto` instead.
+         * 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, the model will
+         * automatically determine the best background for the image.
          *
-         * If `transparent`, the output format needs to support transparency, so it should be set to
-         * either `png` (default value) or `webp`.
+         * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2`
+         * and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set
+         * the output format to `png` or `webp`.
          */
         fun background(background: Background?) = apply { body.background(background) }
 
@@ -930,17 +922,13 @@ private constructor(
         fun prompt(): String = prompt.value.getRequired("prompt")
 
         /**
-         * Allows to set transparency for the background of the generated image(s). This parameter
-         * is only supported for GPT image models that support transparent backgrounds. Must be one
-         * of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model
-         * will automatically determine the best background for the image.
-         *
-         * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-         * Requests with `background` set to `transparent` will return an error for these models;
-         * use `opaque` or `auto` instead.
+         * 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, the model will
+         * automatically determine the best background for the image.
          *
-         * If `transparent`, the output format needs to support transparency, so it should be set to
-         * either `png` (default value) or `webp`.
+         * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2`
+         * and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set
+         * the output format to `png` or `webp`.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -1332,18 +1320,13 @@ private constructor(
             fun prompt(prompt: MultipartField<String>) = apply { this.prompt = prompt }
 
             /**
-             * Allows to set transparency for the background of the generated image(s). This
-             * parameter is only supported for GPT image models that support transparent
-             * backgrounds. Must be one of `transparent`, `opaque`, or `auto` (default value). When
-             * `auto` is used, the model will automatically determine the best background for the
-             * image.
+             * 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, the model
+             * will automatically determine the best background for the image.
              *
-             * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds.
-             * Requests with `background` set to `transparent` will return an error for these
-             * models; use `opaque` or `auto` instead.
-             *
-             * If `transparent`, the output format needs to support transparency, so it should be
-             * set to either `png` (default value) or `webp`.
+             * Transparent backgrounds are available for supported GPT Image models. For
+             * `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using
+             * `transparent`, set the output format to `png` or `webp`.
              */
             fun background(background: Background?) = background(MultipartField.of(background))
 
@@ -1969,17 +1952,13 @@ private constructor(
     }
 
     /**
-     * Allows to set transparency for the background of the generated image(s). This parameter is
-     * only supported for GPT image models that support transparent backgrounds. Must be one of
+     * 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, the model will
      * automatically determine the best background for the image.
      *
-     * `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds. Requests
-     * with `background` set to `transparent` will return an error for these models; use `opaque` or
-     * `auto` instead.
-     *
-     * If `transparent`, the output format needs to support transparency, so it should be set to
-     * either `png` (default value) or `webp`.
+     * Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and
+     * `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the
+     * output format to `png` or `webp`.
      */
     class Background @JsonCreator private constructor(private val value: JsonField<String>) : Enum {