The Difference Between a Local File and an Uploaded File

Every example so far has read audio from a file already sitting on the local disk. Real applications rarely work this way. Instead, audio typically arrives as an upload: a user submits a recording through a web form, a mobile app sends a file to your backend, or a file lands in cloud storage as part of an automated pipeline. This lesson covers the practical mechanics of handling audio that arrives as an upload rather than as a pre-existing local file, which introduces a set of concerns that do not show up when you are just calling open() on a file you created yourself.

The core difference is that an uploaded file is untrusted and unvalidated by default. You do not control its format, size, encoding, or content ahead of time — the client sending it might be buggy, malicious, or simply using a browser or library that produces audio in a format you did not expect. Before that data ever reaches client.audio.transcriptions.create(), your application needs to treat it the way it would treat any other piece of user-submitted input: validate it, sanitize it, and handle it defensively.

Receiving an Upload in a Web Framework

Most Python web frameworks represent an uploaded file as a stream-like object with a filename and a content type, rather than as a path on disk. Here is a representative pattern using a generic in-memory file object, which mirrors how frameworks such as FastAPI or Flask expose uploaded files:

import io
from openai import OpenAI

client = OpenAI()


def transcribe_uploaded_file(file_stream: io.BufferedIOBase, filename: str) -> str:
    # The SDK needs a filename hint to infer the audio format correctly,
    # since a raw byte stream alone does not carry that information.
    file_stream.name = filename

    transcript = client.audio.transcriptions.create(
        model="gpt-5.6-terra",
        file=file_stream,
    )
    return transcript.text

The important detail here is file_stream.name = filename. Many upload-handling libraries hand you a file-like object that does not automatically preserve a usable filename, or that exposes it under a different attribute. The OpenAI SDK uses the file's name (specifically, its extension) to determine what audio format it is dealing with. If the object passed to file does not expose a name with a recognizable audio extension, the request can fail even though the underlying bytes are perfectly valid audio — because the format could not be inferred. Explicitly setting .name before the call sidesteps this class of failure entirely.

Note: The exact mechanism a given web framework uses to expose the uploaded filename (a .filename attribute, a .name attribute, or a separate parameter) varies by framework and by SDK version. Confirm the current expected interface in the OpenAI Python SDK's documentation and in your framework's file-upload documentation before wiring this into production code.

Validating Uploads Before Sending Them to the API

Because uploaded files are untrusted, validation needs to happen in your own code, not just rely on the API to reject bad input (which wastes a network round trip and, in adversarial cases, could be used to probe your system). A solid validation layer checks three things: declared content type, actual file size, and — where feasible — a quick sanity check that the bytes look like real audio.

import io

MAX_UPLOAD_BYTES = 25 * 1024 * 1024  # 25 MB, matching a common API ceiling
ALLOWED_CONTENT_TYPES = {
    "audio/mpeg",
    "audio/mp4",
    "audio/wav",
    "audio/x-wav",
    "audio/webm",
}


class UploadValidationError(Exception):
    """Raised when an uploaded audio file fails validation."""


def validate_audio_upload(file_bytes: bytes, content_type: str) -> None:
    if content_type not in ALLOWED_CONTENT_TYPES:
        raise UploadValidationError(f"Unsupported content type: {content_type}")

    if len(file_bytes) == 0:
        raise UploadValidationError("Uploaded file is empty")

    if len(file_bytes) > MAX_UPLOAD_BYTES:
        size_mb = len(file_bytes) / (1024 * 1024)
        raise UploadValidationError(
            f"File is {size_mb:.1f} MB, which exceeds the {MAX_UPLOAD_BYTES // (1024 * 1024)} MB limit"
        )


def load_and_validate(file_stream: io.BufferedIOBase, content_type: str) -> bytes:
    file_bytes = file_stream.read()
    validate_audio_upload(file_bytes, content_type)
    return file_bytes

Note: The 25 MB figure used here is illustrative and matches a commonly cited limit for audio transcription uploads at the time of writing, but exact size and duration limits for the transcription endpoint should always be confirmed against current official documentation — they can change, and different models or endpoint tiers may enforce different ceilings.

Validating content type is a first line of defense but is not airtight by itself, because a client can lie about the content type of a file it sends (this is just a header value the client controls). For applications with stricter security requirements, a more robust check inspects the first few bytes of the file — its "magic number" — to confirm the actual format matches what is declared, rather than trusting the declared type alone. For most internal or moderately trusted applications, checking declared content type plus size is a reasonable and pragmatic balance between safety and implementation complexity; for public-facing applications accepting uploads from anonymous users, deeper content sniffing is worth the added effort.

Handling In-Memory Bytes Versus File Objects

Once you have validated bytes, you need to hand them to the API in the shape it expects. The transcription endpoint wants a file-like object, not a raw bytes value, so if your validation step already consumed the stream into a bytes object, you need to wrap it back into a file-like object before calling the API:

import io
from openai import OpenAI

client = OpenAI()


def transcribe_bytes(audio_bytes: bytes, filename: str) -> str:
    buffer = io.BytesIO(audio_bytes)
    buffer.name = filename  # required so the SDK can infer the audio format

    transcript = client.audio.transcriptions.create(
        model="gpt-5.6-terra",
        file=buffer,
    )
    return transcript.text

io.BytesIO wraps an in-memory bytes object in a file-like interface, giving it .read() and other methods the SDK expects from a file. This pattern is especially useful when the audio arrives as bytes from somewhere other than a local file — for example, downloaded from cloud storage, decoded from a base64 payload in a JSON request body, or captured directly in memory without ever touching disk. As with the earlier example, buffer.name must be set explicitly, because io.BytesIO has no inherent concept of a filename.

Putting It Together: A Complete Upload-Handling Function

Combining validation and transcription into a single, well-structured function keeps the failure modes explicit and easy to handle at the call site:

import io
from openai import OpenAI, APIError

client = OpenAI()

MAX_UPLOAD_BYTES = 25 * 1024 * 1024
ALLOWED_CONTENT_TYPES = {"audio/mpeg", "audio/mp4", "audio/wav", "audio/x-wav", "audio/webm"}


class UploadValidationError(Exception):
    pass


class TranscriptionError(Exception):
    pass


def handle_audio_upload(file_bytes: bytes, filename: str, content_type: str) -> str:
    if content_type not in ALLOWED_CONTENT_TYPES:
        raise UploadValidationError(f"Unsupported content type: {content_type}")
    if not file_bytes:
        raise UploadValidationError("Uploaded file is empty")
    if len(file_bytes) > MAX_UPLOAD_BYTES:
        raise UploadValidationError("Uploaded file exceeds the size limit")

    buffer = io.BytesIO(file_bytes)
    buffer.name = filename

    try:
        transcript = client.audio.transcriptions.create(
            model="gpt-5.6-terra",
            file=buffer,
        )
    except APIError as exc:
        raise TranscriptionError(f"Transcription failed: {exc}") from exc

    return transcript.text

This function separates concerns clearly: validation errors (UploadValidationError) are distinguishable from API-level failures (TranscriptionError), which matters because they usually need different handling at the call site. A validation error typically means "reject this request with a 400-style client error and a specific message," while a transcription error might mean "return a 502-style server error and consider retrying." Collapsing both into a single generic exception type would force calling code to inspect error messages or exception attributes to figure out which situation it is in — brittle and easy to get wrong.

Testing Upload Handling Without Real Files or API Calls

import io


class FakeTranscript:
    def __init__(self, text: str):
        self.text = text


class FakeTranscriptions:
    def create(self, **kwargs):
        assert isinstance(kwargs["file"], io.BytesIO)
        assert kwargs["file"].name == "recording.wav"
        return FakeTranscript("this is the fake transcript")


class FakeAudio:
    def __init__(self):
        self.transcriptions = FakeTranscriptions()


class FakeClient:
    def __init__(self):
        self.audio = FakeAudio()


def handle_audio_upload_with_client(client, file_bytes: bytes, filename: str, content_type: str) -> str:
    allowed = {"audio/wav", "audio/mpeg"}
    if content_type not in allowed:
        raise ValueError("Unsupported content type")
    if not file_bytes:
        raise ValueError("Empty file")

    buffer = io.BytesIO(file_bytes)
    buffer.name = filename
    transcript = client.audio.transcriptions.create(model="gpt-5.6-terra", file=buffer)
    return transcript.text


def test_handle_audio_upload_success():
    fake_client = FakeClient()
    result = handle_audio_upload_with_client(
        fake_client, file_bytes=b"fake-audio-bytes", filename="recording.wav", content_type="audio/wav"
    )
    assert result == "this is the fake transcript"
    print("PASS: handle_audio_upload_success")


def test_handle_audio_upload_rejects_empty_file():
    fake_client = FakeClient()
    try:
        handle_audio_upload_with_client(
            fake_client, file_bytes=b"", filename="recording.wav", content_type="audio/wav"
        )
        assert False, "expected ValueError"
    except ValueError as exc:
        assert "Empty file" in str(exc)
        print("PASS: handle_audio_upload_rejects_empty_file")


test_handle_audio_upload_success()
test_handle_audio_upload_rejects_empty_file()

These two tests check the two most important behaviors independently: that a valid upload flows through to a transcription result, and that an invalid one (here, an empty file) is rejected before ever reaching the fake API client. Notice that FakeTranscriptions.create asserts on the shape of what it received (isinstance(kwargs["file"], io.BytesIO) and the correct .name), which verifies that your production code correctly wraps and names the buffer — a detail that is easy to get wrong and would otherwise only surface as a confusing failure against the real API.

Common Mistakes

Forgetting to set .name on an in-memory buffer, which causes the SDK or API to fail to infer the audio format, even when the actual audio data is completely valid. This happens because io.BytesIO objects carry no filename by default, unlike objects returned by open().

Trusting the client-declared content type as proof of the actual file format, which causes security or reliability gaps in public-facing upload endpoints. A declared Content-Type header is just a string the client sends and can be wrong or deliberately falsified; for higher-trust validation, inspect the file's actual byte signature.

Reading an upload stream more than once without resetting its position, which causes the second read to return empty data and downstream code to behave as if the file were empty. After validation reads a stream to get its bytes, either keep those bytes in a variable and construct a fresh io.BytesIO for the API call (as shown above), or explicitly call .seek(0) before reusing the original stream.

Best Practices

Validate size and content type before doing any expensive work, including before you even attempt to read the entire file into memory for very large uploads — check declared size from headers first when your framework exposes it, to avoid unnecessarily buffering huge malicious payloads.

Always wrap raw bytes in io.BytesIO and set a .name attribute before passing them to the transcription API, rather than trying to pass raw bytes directly, which the SDK does not accept as a file argument.

Keep validation and API-calling logic in separate, distinctly-typed exceptions, so calling code (a web route handler, for instance) can map each exception type to the correct HTTP status code and user-facing message without string-matching error text.