Skip to content

chore(api): clarify image transparency and audio delta docs #2439

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
apcha-oai merged 1 commit into from
Aug 21, 2026
Merged

chore(api): clarify image transparency and audio delta docs #2439

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .castiron.stats.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
schema_version: 1
generation_id: 7793d050-80cb-4780-a86c-8946458ffcf2
openapi_spec_hash: a85edbfc22ff719d064bce2705c7394e
openapi_transformed_spec_hash: f8e7644df5aee22dfcd0ea2b70942054
config_hash: 85382dd94c503b5d225adc7636a77c9f
codegen_sha: a43cf9fdba6b38cce8895bde5325bdaeb4f0d410
codegen_hash: 513299024e9d03cd7d2e30fc3039b6f6ca0d15ba9f8ed19a2e9bf99467b01d64
public_codegen_sha: bcc959633ff60cf66571c15e55460f8f90a12191
generation_id: d0402f5b-83b7-4452-9cf9-1cdc0f123988
openapi_spec_hash: 92700e1a33a4f6174a01b46648c8186a
openapi_transformed_spec_hash: e37bbe0f04caa6093f1cb5d65d23ad03
config_hash: d13c582815d0db08c374985806be7352
codegen_sha: c63aa69f03e643fb33c7ae7af79751c51472c651
codegen_hash: 293a4d1a245e83b84b133b17b9ca4758c78abcc8b0b466595efd5f23b60db6f7
public_codegen_sha: f79c7f806e382e1057528b383c8603c8c675fe7c
87 changes: 36 additions & 51 deletions api_reference/openapi.transformed.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
17 changes: 6 additions & 11 deletions src/resources/beta/responses/responses.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12438,18 +12438,13 @@ export namespace BetaTool {
action?: 'generate' | 'edit' | 'auto';

/**
* 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`.
*/
background?: 'transparent' | 'opaque' | 'auto';

Expand Down
34 changes: 12 additions & 22 deletions src/resources/images.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -584,18 +584,13 @@ export interface ImageEditParamsBase {
prompt: string;

/**
* 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`.
*/
background?: 'transparent' | 'opaque' | 'auto' | null;

Expand Down Expand Up @@ -730,18 +725,13 @@ export interface ImageGenerateParamsBase {
prompt: string;

/**
* 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.
Comment on lines +728 to +730

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restore the GPT-only restriction for background

When callers use images.generate with dall-e-2 or dall-e-3—both still accepted by ImageGenerateParamsBase.model—this wording now suggests that opaque and auto are valid because it limits only transparent backgrounds to GPT Image models. Runtime behavior is unchanged, and the removed documentation correctly stated that the entire background parameter is GPT-only, so retain that restriction alongside the new GPT Image 2 preview guidance to prevent unsupported DALL-E requests.

AGENTS.md reference: AGENTS.md:L72-L74

Useful? React with 👍 / 👎.

*
* 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`.
*/
background?: 'transparent' | 'opaque' | 'auto' | null;

Expand Down
5 changes: 3 additions & 2 deletions src/resources/realtime/realtime.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3850,8 +3850,9 @@ export interface RealtimeTranslationInputTranscriptDeltaEvent {
}

/**
* 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.
*/
export interface RealtimeTranslationOutputAudioDeltaEvent {
/**
Expand Down
17 changes: 6 additions & 11 deletions src/resources/responses/responses.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9336,18 +9336,13 @@ export namespace Tool {
action?: 'generate' | 'edit' | 'auto';

/**
* 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`.
*/
background?: 'transparent' | 'opaque' | 'auto';

Expand Down
Loading