docs: clarify file upload metadata

[jbeckwith-oai]

Summary

• Explain the fallback filename and MIME metadata used for raw file-upload values.
• Show the idiomatic OpenAI::FilePart workaround for format-sensitive audio uploads.
• Update generated transcription and translation documentation from the linked Castiron/OpenAPI change.

Compatibility

Documentation only. There are no changes to public Ruby methods, keyword arguments, return types, RBI signatures, serializers, retries, authentication, or exceptions.

Validation

• bundle exec rake lint (Sorbet clean, 1,211 RBS files valid, 2,600 RuboCop files with no offenses)
• bundle exec rake test against the mock API (552 runs, 1,863 assertions, 0 failures)
• Gem and YARD documentation builds
• Thermo-nuclear code-quality review, including Ruby idiom and compatibility checks, with no remaining findings

Upstream generator/OpenAPI change: https://github.com/openai/openai/pull/1270941

Closes #243

[HAYDEN-OAI]

Reviewed the generated docs and README example against FileInput.dump, FilePart, and multipart encoding behavior. No substantive issues found.

[jbeckwith-oai]

Generator parity verification:

• Reran api/castiron/scripts/run.sh --local --dry-run --language ruby from the Castiron PR branch.
• Byte-compared all eight changed generated model/resource artifacts (Ruby, RBI) against the generated openai-ruby-internal worktree.
• Corrected six comment-wrapping differences; all eight artifacts now match generator output exactly.
• Revalidated with RuboCop/Sorbet/RBS lint, documentation build, and the full SDK test suite (552 runs, 1,863 assertions, 0 failures).
• Fresh GitHub CI is green.

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 9.931s for Ruby SDK PR #358.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	201ms
tests/chat-completions-create.test.ts	✅ Passed	254ms
tests/chat-completions-stream.test.ts	✅ Passed	156ms
tests/files-content-binary.test.ts	✅ Passed	211ms
tests/files-create-multipart.test.ts	✅ Passed	286ms
tests/files-list-pagination.test.ts	✅ Passed	219ms
tests/initialize-config.test.ts	✅ Passed	242ms
tests/instance-isolation.test.ts	✅ Passed	238ms
tests/models-list.test.ts	✅ Passed	259ms
tests/responses-background-lifecycle.test.ts	✅ Passed	214ms
tests/responses-body-method-errors.test.ts	✅ Passed	522ms
tests/responses-cancel-timeout.test.ts	✅ Passed	338ms
tests/responses-cancel.test.ts	✅ Passed	238ms
tests/responses-compact-retries.test.ts	✅ Passed	286ms
tests/responses-compact.test.ts	✅ Passed	225ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	229ms
tests/responses-create-advanced.test.ts	✅ Passed	213ms
tests/responses-create-disconnect.test.ts	✅ Passed	164ms
tests/responses-create-errors.test.ts	✅ Passed	276ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	158ms
tests/responses-create-retries.test.ts	✅ Passed	277ms
tests/responses-create-stream-failures.test.ts	✅ Passed	162ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	223ms
tests/responses-create-stream-wire.test.ts	✅ Passed	2.176s
tests/responses-create-stream.test.ts	✅ Passed	211ms
tests/responses-create-terminal-states.test.ts	✅ Passed	436ms
tests/responses-create-timeout.test.ts	✅ Passed	367ms
tests/responses-create.test.ts	✅ Passed	309ms
tests/responses-delete.test.ts	✅ Passed	231ms
tests/responses-input-items-errors.test.ts	✅ Passed	181ms
tests/responses-input-items-list.test.ts	✅ Passed	196ms
tests/responses-input-items-options.test.ts	✅ Passed	294ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	312ms
tests/responses-input-tokens-count.test.ts	✅ Passed	257ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.398s
tests/responses-not-found-errors.test.ts	✅ Passed	385ms
tests/responses-parse.test.ts	✅ Passed	201ms
tests/responses-retrieve-retries.test.ts	✅ Passed	305ms
tests/responses-retrieve.test.ts	✅ Passed	239ms
tests/responses-stored-method-errors.test.ts	✅ Passed	1.051s
tests/retry-behavior.test.ts	✅ Passed	2.008s
tests/sdk-error-shape.test.ts	✅ Passed	451ms

View OkTest run #31456438379

_{SDK merge (ad381c7c7a1a) · head (757fcbdd4b42) · base (66359a090767) · OkTest (91635c6a2723)}