fix(api): clarify audio upload metadata requirements (#3596)

## Summary

Regenerates the Python SDK from the latest OpenAPI input for the audio
upload documentation change.

- Clarifies that transcription and translation uploads must include
enough metadata for the file format to be identified.
- Recommends an extension-bearing filename and an appropriate content
type.
- Updates generated resource docstrings, request parameter docs, the
transformed OpenAPI document, and Castiron provenance.

This is documentation-only; runtime behavior and exported type shapes
are unchanged.

## Source

- Originating API change:
[openai/openai#1270941](openai/openai#1270941)
- OpenAPI input:
[openai/openai-openapi@577fa922](openai/openai-openapi@577fa92)

## Validation

- Rebased directly onto the current public `main`
- Every changed file matches the Castiron-generated candidate
- `git diff --check`
- `./scripts/lint`
- Thermo-nuclear code-quality review

Author: jbeckwith-oai

.castiron.stats.yml

@@ -1,6 +1,6 @@
 schema_version: 1
-generation_id: e3616fd3-9690-4581-bbd3-5c06423abf6d
-openapi_spec_hash: 8d5c14d02f8cc28de343933fae3a9c28
-openapi_transformed_spec_hash: cc042503b90491f4f162ce95fae87c36
+generation_id: e1943695-9da0-4ac1-ae5a-cc763f5d90be
+openapi_spec_hash: 1faf0319c407c6534ef7c381614afbb6
+openapi_transformed_spec_hash: 53eff50caa9d18046e4ff0615bc7512d
 config_hash: 4617b0962f16d328804312ac81aac630
-codegen_sha: ea10a4f6b22f3fb9f72208589a3e8258c640479d
+codegen_sha: b97c76f867d26f99d0de01d6283fa6d511044141

api_reference/openapi.transformed.yml

@@ -34062,6 +34062,7 @@ components:
         file:
           description: |
             The audio file object (not file name) to transcribe, in one of these formats: 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.
           type: string
           x-oaiTypeLabel: file
           format: binary
@@ -34369,7 +34370,7 @@ components:
       properties:
         file:
           description: |
-            The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+            The audio file object (not file name) translate, in one of these formats: 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.
           type: string
           x-oaiTypeLabel: file
           format: binary

src/openai/resources/audio/transcriptions.py

@@ -94,9 +94,10 @@ def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`
@@ -260,9 +261,10 @@ def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`
@@ -380,9 +382,10 @@ def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`
@@ -593,9 +596,10 @@ async def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`
@@ -754,9 +758,10 @@ async def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`
@@ -874,9 +879,10 @@ async def create(
         format, or a stream of transcript events.
 
         Args:
-          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.
+          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. The request must include
+              enough format metadata for the file to be identified. We recommend an
+              extension-bearing filename and an appropriate content type.
 
           model: 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`

src/openai/resources/audio/translations.py

@@ -120,7 +120,9 @@ def create(
 
         Args:
           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.
 
           model: ID of the model to use. Only `whisper-1` (which is powered by our open source
               Whisper V2 model) is currently available.
@@ -270,7 +272,9 @@ async def create(
 
         Args:
           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.
 
           model: ID of the model to use. Only `whisper-1` (which is powered by our open source
               Whisper V2 model) is currently available.

src/openai/types/audio/transcription_create_params.py

@@ -23,7 +23,9 @@ class TranscriptionCreateParamsBase(TypedDict, total=False):
     file: Required[FileTypes]
     """
     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.
     """
 
     model: Required[Union[str, AudioModel]]

src/openai/types/audio/translation_create_params.py

@@ -15,7 +15,9 @@ class TranslationCreateParams(TypedDict, total=False):
     file: Required[FileTypes]
     """
     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.
     """
 
     model: Required[Union[str, AudioModel]]