docs: clarify file upload metadata

README.md

@@ -82,6 +82,8 @@ end
 
 Request parameters that correspond to file uploads can be passed as raw contents, a [`Pathname`](https://rubyapi.org/3.3/o/pathname) instance, [`StringIO`](https://rubyapi.org/3.3/o/stringio), or more.
 
+Raw `String` and `StringIO` values, and `IO` objects without a path, do not carry format-identifying metadata. The SDK sends them using the fallback filename `upload`; raw `String` values default to `text/plain`, while `StringIO` and pathless `IO` values default to `application/octet-stream`. For format-sensitive endpoints, such as audio transcriptions, wrap each value in `OpenAI::FilePart` and provide an extension-bearing filename and content type.
+
 ```ruby
 require "pathname"
 
@@ -93,12 +95,25 @@ file_object = openai.files.create(file: File.read("input.jsonl"), purpose: "fine
 
 puts(file_object.id)
 
-# Or, to control the filename and/or content type:
-image = OpenAI::FilePart.new(Pathname('dog.jpg'), content_type: 'image/jpeg')
+# For format-sensitive uploads, provide the filename and content type:
+audio_data = StringIO.new(File.binread("audio.wav"))
+audio = OpenAI::FilePart.new(
+  audio_data,
+  filename: "audio.wav",
+  content_type: "audio/wav"
+)
+transcription = openai.audio.transcriptions.create(
+  model: "gpt-4o-transcribe",
+  file: audio
+)
+puts(transcription.text)
+
+# FilePart also accepts a Pathname:
+image = OpenAI::FilePart.new(Pathname("dog.jpg"), content_type: "image/jpeg")
 edited = openai.images.edit(
   prompt: "make this image look like a painting",
   model: "gpt-image-1",
-  size: '1024x1024',
+  size: "1024x1024",
   image: image
 )
 

lib/openai/models/audio/transcription_create_params.rb

@@ -12,7 +12,13 @@ class TranscriptionCreateParams < OpenAI::Internal::Type::BaseModel
 
         # @!attribute file
         #   The audio file object (not file name) to transcribe, in one of these formats:
-        #   flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+        #   flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include
+        #   enough format metadata for the file to be identified. We recommend an
+        #   extension-bearing filename and an appropriate content type.
+        #
+        #   `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        #   metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        #   content type.
         #
         #   @return [Pathname, StringIO, IO, String, OpenAI::FilePart]
         required :file, OpenAI::Internal::Type::FileInput

lib/openai/models/audio/translation_create_params.rb

@@ -10,7 +10,13 @@ class TranslationCreateParams < OpenAI::Internal::Type::BaseModel
 
         # @!attribute file
         #   The audio file object (not file name) translate, in one of these formats: flac,
-        #   mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+        #   mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include enough
+        #   format metadata for the file to be identified. We recommend an extension-bearing
+        #   filename and an appropriate content type.
+        #
+        #   `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        #   metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        #   content type.
         #
         #   @return [Pathname, StringIO, IO, String, OpenAI::FilePart]
         required :file, OpenAI::Internal::Type::FileInput

lib/openai/resources/audio/transcriptions.rb

@@ -16,6 +16,10 @@ class Transcriptions
         # Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
         # format, or a stream of transcript events.
         #
+        # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        # content type.
+        #
         # @overload create(file:, model:, chunking_strategy: nil, include: nil, keywords: nil, known_speaker_names: nil, known_speaker_references: nil, language: nil, languages: nil, prompt: nil, response_format: nil, temperature: nil, timestamp_granularities: nil, request_options: {})
         #
         # @param file [Pathname, StringIO, IO, String, OpenAI::FilePart] The audio file object (not file name) to transcribe, in one of these formats: fl
@@ -77,6 +81,10 @@ def create(params)
         # Returns a transcription object in `json`, `diarized_json`, or `verbose_json`
         # format, or a stream of transcript events.
         #
+        # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        # content type.
+        #
         # @overload create_streaming(file:, model:, chunking_strategy: nil, include: nil, keywords: nil, known_speaker_names: nil, known_speaker_references: nil, language: nil, languages: nil, prompt: nil, response_format: nil, temperature: nil, timestamp_granularities: nil, request_options: {})
         #
         # @param file [Pathname, StringIO, IO, String, OpenAI::FilePart] The audio file object (not file name) to transcribe, in one of these formats: fl

lib/openai/resources/audio/translations.rb

@@ -10,6 +10,10 @@ class Translations
         #
         # Translates audio into English.
         #
+        # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        # content type.
+        #
         # @overload create(file:, model:, prompt: nil, response_format: nil, temperature: nil, request_options: {})
         #
         # @param file [Pathname, StringIO, IO, String, OpenAI::FilePart] The audio file object (not file name) translate, in one of these formats: flac,

rbi/openai/models/audio/transcription_create_params.rbi

@@ -16,7 +16,13 @@ module OpenAI
           end
 
         # The audio file object (not file name) to transcribe, in one of these formats:
-        # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+        # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include
+        # enough format metadata for the file to be identified. We recommend an
+        # extension-bearing filename and an appropriate content type.
+        #
+        # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        # content type.
         sig { returns(OpenAI::Internal::FileInput) }
         attr_accessor :file
 
@@ -202,7 +208,13 @@ module OpenAI
         end
         def self.new(
           # The audio file object (not file name) to transcribe, in one of these formats:
-          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include
+          # enough format metadata for the file to be identified. We recommend an
+          # extension-bearing filename and an appropriate content type.
+          #
+          # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+          # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+          # content type.
           file:,
           # ID of the model to use. The options are `gpt-transcribe`, `gpt-4o-transcribe`,
           # `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `whisper-1`

rbi/openai/models/audio/translation_create_params.rbi

@@ -16,7 +16,13 @@ module OpenAI
           end
 
         # The audio file object (not file name) translate, in one of these formats: flac,
-        # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+        # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include enough
+        # format metadata for the file to be identified. We recommend an extension-bearing
+        # filename and an appropriate content type.
+        #
+        # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+        # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+        # content type.
         sig { returns(OpenAI::Internal::FileInput) }
         attr_accessor :file
 
@@ -78,7 +84,13 @@ module OpenAI
         end
         def self.new(
           # The audio file object (not file name) translate, in one of these formats: flac,
-          # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include enough
+          # format metadata for the file to be identified. We recommend an extension-bearing
+          # filename and an appropriate content type.
+          #
+          # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+          # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+          # content type.
           file:,
           # ID of the model to use. Only `whisper-1` (which is powered by our open source
           # Whisper V2 model) is currently available.

rbi/openai/resources/audio/transcriptions.rbi

@@ -44,7 +44,13 @@ module OpenAI
         end
         def create(
           # The audio file object (not file name) to transcribe, in one of these formats:
-          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include
+          # enough format metadata for the file to be identified. We recommend an
+          # extension-bearing filename and an appropriate content type.
+          #
+          # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+          # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+          # content type.
           file:,
           # ID of the model to use. The options are `gpt-transcribe`, `gpt-4o-transcribe`,
           # `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `whisper-1`
@@ -159,7 +165,13 @@ module OpenAI
         end
         def create_streaming(
           # The audio file object (not file name) to transcribe, in one of these formats:
-          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          # flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include
+          # enough format metadata for the file to be identified. We recommend an
+          # extension-bearing filename and an appropriate content type.
+          #
+          # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+          # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+          # content type.
           file:,
           # ID of the model to use. The options are `gpt-transcribe`, `gpt-4o-transcribe`,
           # `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `whisper-1`

rbi/openai/resources/audio/translations.rbi

@@ -19,7 +19,13 @@ module OpenAI
         end
         def create(
           # The audio file object (not file name) translate, in one of these formats: flac,
-          # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          # mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. The request must include enough
+          # format metadata for the file to be identified. We recommend an extension-bearing
+          # filename and an appropriate content type.
+          #
+          # `String`, `StringIO`, and pathless `IO` inputs are sent with generic upload
+          # metadata. Use `OpenAI::FilePart` when you need to override the filename or
+          # content type.
           file:,
           # ID of the model to use. Only `whisper-1` (which is powered by our open source
           # Whisper V2 model) is currently available.