docs: clarify image transparency and Realtime audio delta behavior

[apcha-oai]

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.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

61 mixed files remain; 0 existing customizations changed.

Compared ca9c11dd90be → ddfcc6c1deff. Generated baselines verified.

61 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/beta/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/finetuning/checkpoints/PermissionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ImageServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/ResponseServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/finetuning/checkpoints/PermissionServiceImpl.kt
• openai-java-core/src/test/kotlin/com/openai/models/beta/responses/BetaResponsesServerEventTest.kt
• openai-java-core/src/test/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParamsTest.kt
• openai-java-core/src/test/kotlin/com/openai/models/embeddings/EmbeddingTest.kt
• openai-java-core/src/test/kotlin/com/openai/models/responses/ResponsesServerEventTest.kt

21 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 32429412339 --repo openai/openai-java \
  --name castiron-custom-code-32429412339-1 --dir /tmp/castiron-custom-code-32429412339-1
git apply --stat /tmp/castiron-custom-code-32429412339-1/custom-code.patch
cat /tmp/castiron-custom-code-32429412339-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin ca9c11dd90be5b10b67797a0af6e575ce776bb6a ddfcc6c1deff03bb6866fcfc3248e00ffc849bcc
python3 scripts/castiron/custom_code_report.py report \
  --base ca9c11dd90be5b10b67797a0af6e575ce776bb6a \
  --head ddfcc6c1deff03bb6866fcfc3248e00ffc849bcc --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-ddfcc6c1deff
cat /tmp/castiron-custom-code-ddfcc6c1deff/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-20T23:38:08.615107Z	ddfcc6c	Draft marked ready
🔒 Security Review	✅ Completed 2026-08-20T23:39:09.053156Z	ddfcc6c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 17.894s for Java SDK PR #918.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	355ms
tests/chat-completions-create.test.ts	✅ Passed	872ms
tests/chat-completions-stream.test.ts	✅ Passed	437ms
tests/files-content-binary.test.ts	✅ Passed	190ms
tests/files-create-multipart.test.ts	✅ Passed	275ms
tests/files-list-pagination.test.ts	✅ Passed	300ms
tests/initialize-config.test.ts	✅ Passed	264ms
tests/instance-isolation.test.ts	✅ Passed	250ms
tests/models-list.test.ts	✅ Passed	209ms
tests/responses-background-lifecycle.test.ts	✅ Passed	323ms
tests/responses-body-method-errors.test.ts	✅ Passed	539ms
tests/responses-cancel-timeout.test.ts	✅ Passed	204ms
tests/responses-cancel.test.ts	✅ Passed	484ms
tests/responses-compact-retries.test.ts	✅ Passed	456ms
tests/responses-compact.test.ts	✅ Passed	435ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	502ms
tests/responses-create-advanced.test.ts	✅ Passed	1.433s
tests/responses-create-disconnect.test.ts	✅ Passed	1.157s
tests/responses-create-errors.test.ts	✅ Passed	418ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	335ms
tests/responses-create-retries.test.ts	✅ Passed	931ms
tests/responses-create-stream-failures.test.ts	✅ Passed	223ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	254ms
tests/responses-create-stream-wire.test.ts	✅ Passed	6.641s
tests/responses-create-stream.test.ts	✅ Passed	689ms
tests/responses-create-terminal-states.test.ts	✅ Passed	399ms
tests/responses-create-timeout.test.ts	✅ Passed	283ms
tests/responses-create.test.ts	✅ Passed	308ms
tests/responses-delete.test.ts	✅ Passed	296ms
tests/responses-input-items-errors.test.ts	✅ Passed	288ms
tests/responses-input-items-list.test.ts	✅ Passed	441ms
tests/responses-input-items-options.test.ts	✅ Passed	634ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	290ms
tests/responses-input-tokens-count.test.ts	✅ Passed	371ms
tests/responses-malformed-inputs.test.ts	✅ Passed	5.28s
tests/responses-not-found-errors.test.ts	✅ Passed	392ms
tests/responses-parse.test.ts	✅ Passed	661ms
tests/responses-retrieve-retries.test.ts	✅ Passed	348ms
tests/responses-retrieve.test.ts	✅ Passed	465ms
tests/responses-stored-method-errors.test.ts	✅ Passed	1.122s
tests/retry-behavior.test.ts	✅ Passed	3.41s
tests/sdk-error-shape.test.ts	✅ Passed	363ms

View OkTest run #32429413862

_{SDK merge (f5aa0c116957) · head (ddfcc6c1deff) · base (ca9c11dd90be) · OkTest (2b1bdfd25e98)}

[jbeckwith-oai]

The updated description removes the existing parameter-level restriction that background is supported only for GPT Image models. It now limits only transparent backgrounds, incorrectly implying dall-e-2 / dall-e-3 accept background: "opaque" or "auto". Restore the explicit GPT-Image-only restriction in the canonical OpenAPI description while retaining the new transparency preview and PNG/WebP guidance, then regenerate.

[jbeckwith-oai]

The updated description removes the existing parameter-level restriction that background is supported only for GPT Image models. It now limits only transparent backgrounds, incorrectly implying dall-e-2 / dall-e-3 accept background: "opaque" or "auto". Restore the explicit GPT-Image-only restriction in the canonical OpenAPI description while retaining the new transparency preview and PNG/WebP guidance, then regenerate.