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

[markstuart-oai]

Clarifies image fidelity guidance for image edits and image tools: the low default applies to models that support the parameter, mini retains its low-only exception, and unsupported models require omission. Identifies retired DALL·E settings and variations as legacy, and directs callers to supported image workflows with an explicit model choice.

No Ruby runtime behavior, signatures, enums, defaults, nullability, serialization, or exported names change.

Validation: the Ruby 3.3/3.4/4.0 test matrix, Bedrock tests, lint, RBI type checks, RBS validation and package checks pass. Token comparison confirms all Ruby and signature changes are documentation-only.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

70 mixed files remain; 0 existing customizations changed; 1 generated baselines changed.

Compared 33435479c2d9 → ccd88da67dbf. Generated baselines verified.

File	Result	Current custom patch
lib/openai/models/responses/tool.rb	Generated baseline changed	+2 / −0

69 existing customizations unchanged

• lib/openai.rb
• lib/openai/client.rb
• lib/openai/models/audio/transcription_create_response.rb
• lib/openai/models/beta/agents/vault_status_filter.rb
• lib/openai/models/chat/chat_completion_message.rb
• lib/openai/models/chat/chat_completion_message_function_tool_call.rb
• lib/openai/models/chat/completion_create_params.rb
• lib/openai/models/image_edit_completed_event.rb
• lib/openai/models/image_edit_partial_image_event.rb
• lib/openai/models/image_gen_completed_event.rb
• lib/openai/models/image_gen_partial_image_event.rb
• lib/openai/models/images_response.rb
• lib/openai/models/response_format_json_schema.rb
• lib/openai/models/responses/function_tool.rb
• lib/openai/models/responses/response.rb
• lib/openai/models/responses/response_create_params.rb
• lib/openai/models/responses/response_format_text_config.rb
• lib/openai/models/responses/response_format_text_json_schema_config.rb
• lib/openai/models/responses/response_function_tool_call.rb
• lib/openai/models/responses/response_function_web_search.rb
• lib/openai/models/responses/response_output_text.rb
• lib/openai/models/webhooks/webhook_endpoint_with_secret.rb
• lib/openai/resources/beta/agents/sessions.rb
• lib/openai/resources/beta/threads.rb
• lib/openai/resources/chat/completions.rb
• lib/openai/resources/containers/files.rb
• lib/openai/resources/files.rb
• lib/openai/resources/responses.rb
• lib/openai/resources/vector_stores/file_batches.rb
• lib/openai/resources/vector_stores/files.rb
• lib/openai/resources/webhooks.rb
• rbi/openai/client.rbi
• rbi/openai/models/beta/agents/vault_status_filter.rbi
• rbi/openai/models/chat/chat_completion_message.rbi
• rbi/openai/models/chat/chat_completion_message_function_tool_call.rbi
• rbi/openai/models/chat/completion_create_params.rbi
• rbi/openai/models/image_edit_completed_event.rbi
• rbi/openai/models/image_edit_partial_image_event.rbi
• rbi/openai/models/image_gen_completed_event.rbi
• rbi/openai/models/image_gen_partial_image_event.rbi

29 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 35566528413 --repo openai/openai-ruby \
  --name castiron-custom-code-35566528413-1 --dir /tmp/castiron-custom-code-35566528413-1
git apply --stat /tmp/castiron-custom-code-35566528413-1/custom-code.patch
cat /tmp/castiron-custom-code-35566528413-1/custom-code.patch

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

git fetch --no-tags origin 33435479c2d98603b93c810183d314bc55cd1ee7 ccd88da67dbf3d7f504b141243b0e50dcadb0574
python3 scripts/castiron/custom_code_report.py report \
  --base 33435479c2d98603b93c810183d314bc55cd1ee7 \
  --head ccd88da67dbf3d7f504b141243b0e50dcadb0574 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-ccd88da67dbf
cat /tmp/castiron-custom-code-ccd88da67dbf/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

[markstuart-oai]

@codex review

[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-09-21T05:58:46.567947Z	ccd88da	New commits
🔒 Security Review	✅ Completed 2026-09-21T06:00:17.513375Z	ccd88da	New commits

ℹ️ 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.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 2306a54774

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

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 2306a54774

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[openai-sdks]

OkTest Summary

✅ 236/236 SDK tests passed in 6.835s for Ruby SDK PR #730.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	119ms
tests/chat-completions-create.test.ts	✅ Passed	93ms
tests/chat-completions-stream.test.ts	✅ Passed	103ms
tests/files-content-binary.test.ts	✅ Passed	102ms
tests/files-create-multipart.test.ts	✅ Passed	122ms
tests/files-list-pagination.test.ts	✅ Passed	128ms
tests/initialize-config.test.ts	✅ Passed	75ms
tests/instance-isolation.test.ts	✅ Passed	137ms
tests/models-list.test.ts	✅ Passed	126ms
tests/responses-background-lifecycle.test.ts	✅ Passed	114ms
tests/responses-body-method-errors.test.ts	✅ Passed	258ms
tests/responses-cancel-timeout.test.ts	✅ Passed	167ms
tests/responses-cancel.test.ts	✅ Passed	153ms
tests/responses-compact-retries.test.ts	✅ Passed	111ms
tests/responses-compact.test.ts	✅ Passed	97ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	115ms
tests/responses-create-advanced.test.ts	✅ Passed	134ms
tests/responses-create-disconnect.test.ts	✅ Passed	105ms
tests/responses-create-errors.test.ts	✅ Passed	209ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	97ms
tests/responses-create-retries.test.ts	✅ Passed	112ms
tests/responses-create-stream-failures.test.ts	✅ Passed	99ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	193ms
tests/responses-create-stream-wire.test.ts	✅ Passed	1.517s
tests/responses-create-stream.test.ts	✅ Passed	74ms
tests/responses-create-terminal-states.test.ts	✅ Passed	194ms
tests/responses-create-timeout.test.ts	✅ Passed	167ms
tests/responses-create.test.ts	✅ Passed	149ms
tests/responses-delete.test.ts	✅ Passed	250ms
tests/responses-input-items-errors.test.ts	✅ Passed	125ms
tests/responses-input-items-list.test.ts	✅ Passed	153ms
tests/responses-input-items-options.test.ts	✅ Passed	100ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	196ms
tests/responses-input-tokens-count.test.ts	✅ Passed	108ms
tests/responses-malformed-inputs.test.ts	✅ Passed	1.729s
tests/responses-not-found-errors.test.ts	✅ Passed	196ms
tests/responses-parse.test.ts	✅ Passed	67ms
tests/responses-retrieve-retries.test.ts	✅ Passed	160ms
tests/responses-retrieve.test.ts	✅ Passed	140ms
tests/responses-stored-method-errors.test.ts	✅ Passed	489ms
tests/retry-behavior.test.ts	✅ Passed	3.246s
tests/sdk-error-shape.test.ts	✅ Passed	260ms

View OkTest run #35566437101

_{SDK merge (d86597192fa4) · head (ccd88da67dbf) · base (33435479c2d9) · OkTest (a0be4375e02d)}