Implementation:Openai Openai python Legacy Response

Knowledge Sources	Openai_Openai_python
Domains	SDK_Infrastructure, Python
Last Updated	2026-02-15 00:00 GMT

Overview

⚠️ DEPRECATED: This implementation contains deprecated methods. See Heuristic:Openai_Openai_python_Warning_Deprecated_Legacy_Response.

Concrete tool for legacy HTTP response wrapping and binary content handling provided by the openai-python SDK.

Description

The _legacy_response.py module (489 lines) implements the legacy response wrapper that will be superseded by APIResponse and AsyncAPIResponse in the next major release. It contains three main components:

1. LegacyAPIResponse[R] (line 45): A generic class that wraps an httpx.Response and provides typed parsing of response data. Key characteristics:
   • Stores the raw httpx.Response in http_response and tracks retries_taken
   • parse() method (line 100) returns the rich Python representation, supporting custom target types via a to parameter. Results are cached per target type in _parsed_by_type
   • The internal _parse() method (line 197) handles type dispatch: streams (via _stream_cls), NoneType, primitives (str, int, float, bool), HttpxBinaryResponseContent, httpx.Response passthrough, and Pydantic BaseModel deserialization from JSON
   • Convenience properties expose headers, status_code, url, method, content (bytes), text (str), elapsed, and request_id (from x-request-id header)
   • Note: In the legacy response, content and text are properties; in the new APIResponse, they become methods

1. HttpxBinaryResponseContent (line 386): A wrapper for binary response data. Provides synchronous access via content, text, read(), iter_bytes(), iter_text(), iter_lines(), iter_raw(), and write_to_file(). Also provides async counterparts: aread(), aiter_bytes(), aiter_text(), aiter_lines(), aiter_raw(). The deprecated stream_to_file() and astream_to_file() methods contain a known bug where content is not actually streamed.

1. Higher-order wrapper functions:
   • to_raw_response_wrapper(func) (line 352): Wraps a sync API method to return LegacyAPIResponse[R] by injecting the RAW_RESPONSE_HEADER
   • async_to_raw_response_wrapper(func) (line 369): Async counterpart of the above

Usage

This module is used internally when legacy API methods return raw response objects. End users encounter HttpxBinaryResponseContent (re-exported as openai.HttpxBinaryResponseContent) when working with binary endpoints like audio and image generation. New code should prefer APIResponse from _response.py.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/_legacy_response.py
• Lines: 1-489

Signature

class LegacyAPIResponse(Generic[R]):
    http_response: httpx.Response
    retries_taken: int

    def __init__(
        self,
        *,
        raw: httpx.Response,
        cast_to: type[R],
        client: BaseClient[Any, Any],
        stream: bool,
        stream_cls: type[Stream[Any]] | type[AsyncStream[Any]] | None,
        options: FinalRequestOptions,
        retries_taken: int = 0,
    ) -> None: ...

    def parse(self, *, to: type[_T] | None = None) -> R | _T: ...

class HttpxBinaryResponseContent:
    response: httpx.Response

    def __init__(self, response: httpx.Response) -> None: ...
    def write_to_file(self, file: str | os.PathLike[str]) -> None: ...
    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]: ...

def to_raw_response_wrapper(func: Callable[P, R]) -> Callable[P, LegacyAPIResponse[R]]: ...
def async_to_raw_response_wrapper(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[LegacyAPIResponse[R]]]: ...

Import

from openai._legacy_response import LegacyAPIResponse
from openai import HttpxBinaryResponseContent

I/O Contract

Inputs

Name	Type	Required	Description
raw	httpx.Response	Yes	The raw httpx response object to wrap
cast_to	type[R]	Yes	Target type to parse the response into
client	BaseClient[Any, Any]	Yes	The client instance that made the request
stream	bool	Yes	Whether the response is a streaming SSE response
stream_cls	type[Stream] or type[AsyncStream] or None	Yes	Stream class to use for SSE stream parsing
options	FinalRequestOptions	Yes	The request options used for this request
retries_taken	int	No	Number of retries performed; defaults to 0

Outputs

Name	Type	Description
parse() return	R or _T	Parsed response data of the specified type
content	bytes	Raw binary response body (property)
text	str	Decoded response body string (property)
headers	httpx.Headers	Response headers
status_code	int	HTTP status code
request_id	str or None	Value of x-request-id response header

Usage Examples

Binary Response Content

from openai import OpenAI

client = OpenAI()

# Speech generation returns HttpxBinaryResponseContent
response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello world!",
)
response.write_to_file("output.mp3")

Accessing Raw Response

from openai import OpenAI

client = OpenAI()
response = client.chat.completions.with_raw_response.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.headers)
print(response.request_id)
completion = response.parse()

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus
• Implementation:Openai_Openai_python_HTTP_Response_Handler
• Implementation:Openai_Openai_python_HTTP_Base_Client
• Implementation:Openai_Openai_python_SDK_Package_Exports
• Heuristic:Openai_Openai_python_Warning_Deprecated_Legacy_Response