Reference 2026-08-11 22:59 UTC to 2026-08-12 06:59 UTC

1991 1991 

1992### Why don't you use plain `enum` classes?1992### Why don't you use plain `enum` classes?

1993 1993 

1994Java `enum` classes are not trivially [forwards compatible](https://www.stainless.com/blog/making-java-enums-forwards-compatible). Using them in the SDK could cause runtime exceptions if the API is updated to respond with a new enum value.1994Java `enum` classes are not trivially forwards compatible. Using them in the SDK could cause runtime exceptions if the API is updated to respond with a new enum value.

1995 1995 

1996### Why do you represent fields using `JsonField<T>` instead of just plain `T`?1996### Why do you represent fields using `JsonField<T>` instead of just plain `T`?

1997 1997 

5 5 

6The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.10+6The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.10+

7application. The library includes type definitions for all request params and response fields,7application. The library includes type definitions for all request params and response fields,

8and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).8and offers both synchronous and asynchronous clients powered by [HTTPX2](https://httpx2.pydantic.dev/).

9 9 

10It is generated from our [OpenAPI specification](https://github.com/openai/openai-openapi) with [Stainless](https://stainlessapi.com/).10It is generated from our [OpenAPI specification](https://github.com/openai/openai-openapi).

11 11 

12## Documentation12## Documentation

13 13 

244 244 

245### With aiohttp245### With aiohttp

246 246 

247By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.247By default, the async client uses HTTPX2. For improved concurrency performance, you may also use `aiohttp` as the HTTPX2 transport.

248 

249The `aiohttp` backend requires Python 3.10 or later.

250 248 

251You can enable this by installing `aiohttp`:249You can enable this by installing `aiohttp`:

252 250 

283asyncio.run(main())281asyncio.run(main())

284```282```

285 283 

286### Experimental HTTPX2 support284### HTTPX2 migration

287 

288To opt in to experimental HTTPX2 support, install the optional extra on Python 3.10 or later:

289 

290```sh

291pip install 'openai[httpx2]'

292```

293 

294```python

295from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

296 

297client = OpenAI(http_client=DefaultHttpx2Client())

298async_client = AsyncOpenAI(http_client=DefaultAsyncHttpx2Client())

299```

300 

301See [`examples/httpx2_client.py`](examples/httpx2_client.py) for a minimal runnable example.

302 285 

303The module-level client can be configured in the same way:286HTTPX2 is the default HTTP client. If you configure a custom HTTP client, transport, timeout, authentication handler, event hook, or request mock, see the [HTTPX2 migration guide](httpx2.md).

304 

305```python

306import openai

307 

308openai.http_client = openai.DefaultHttpx2Client()

309```

310 

311Parsed API models are unchanged, but requests, raw and streaming responses, and transport-level exceptions may be HTTPX2 objects at runtime. Code that catches HTTPX exceptions or relies on HTTPX-specific mocks, transports, authentication, hooks, or instrumentation may need to be updated. Transport-facing type annotations may still describe HTTPX.

312 287 

313## Streaming responses288## Streaming responses

314 289 

636 )611 )

637except openai.APIConnectionError as e:612except openai.APIConnectionError as e:

638 print("The server could not be reached")613 print("The server could not be reached")

639 print(e.__cause__) # an underlying Exception, likely raised within httpx.614 print(e.__cause__) # an underlying Exception, likely raised within HTTPX2.

640except openai.RateLimitError as e:615except openai.RateLimitError as e:

641 print("A 429 status code was received; we should back off a bit.")616 print("A 429 status code was received; we should back off a bit.")

642except openai.APIStatusError as e:617except openai.APIStatusError as e:

723## Timeouts698## Timeouts

724 699 

725By default requests time out after 10 minutes. You can configure this with a `timeout` option,700By default requests time out after 10 minutes. You can configure this with a `timeout` option,

726which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) object:701which accepts a float or an [`httpx2.Timeout`](https://httpx2.pydantic.dev/) object:

727 702 

728```python703```python

704import httpx2

729from openai import OpenAI705from openai import OpenAI

730 706 

731# Configure the default for all requests:707# Configure the default for all requests:

736 712 

737# More granular control:713# More granular control:

738client = OpenAI(714client = OpenAI(

739 timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),715 timeout=httpx2.Timeout(60.0, read=5.0, write=10.0, connect=2.0),

740)716)

741 717 

742# Override per-request:718# Override per-request:

849http verbs. Options on the client will be respected (such as retries) when making this request.825http verbs. Options on the client will be respected (such as retries) when making this request.

850 826 

851```py827```py

852import httpx828import httpx2

853 829 

854response = client.post(830response = client.post(

855 "/foo",831 "/foo",

856 cast_to=httpx.Response,832 cast_to=httpx2.Response,

857 body={"my_param": True},833 body={"my_param": True},

858)834)

859 835 

873 849 

874### Configuring the HTTP client850### Configuring the HTTP client

875 851 

876You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:852You can override the [HTTPX2 client](https://httpx2.pydantic.dev/) to customize proxies, transports, authentication, event hooks, and other advanced HTTP behavior. See the [HTTPX2 migration guide](httpx2.md) when updating an existing custom client.

877 

878- Support for [proxies](https://www.python-httpx.org/advanced/proxies/)

879- Custom [transports](https://www.python-httpx.org/advanced/transports/)

880- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality

881 853 

882```python854```python

883import httpx855import httpx2

884from openai import OpenAI, DefaultHttpxClient856from openai import OpenAI, DefaultHttpx2Client

885 857 

886client = OpenAI(858client = OpenAI(

887 # Or use the `OPENAI_BASE_URL` env var859 # Or use the `OPENAI_BASE_URL` env var

888 base_url="http://my.test.server.example.com:8083/v1",860 base_url="http://my.test.server.example.com:8083/v1",

889 http_client=DefaultHttpxClient(861 http_client=DefaultHttpx2Client(

890 proxy="http://my.test.proxy.example.com",862 proxy="http://my.test.proxy.example.com",

891 transport=httpx.HTTPTransport(local_address="0.0.0.0"),863 transport=httpx2.HTTPTransport(local_address="0.0.0.0"),

892 ),864 ),

893)865)

894```866```

896You can also customize the client on a per-request basis by using `with_options()`:868You can also customize the client on a per-request basis by using `with_options()`:

897 869 

898```python870```python

899client.with_options(http_client=DefaultHttpxClient(...))871client.with_options(http_client=DefaultHttpx2Client(...))

900```872```

901 873 

902#### Mutual TLS874#### Mutual TLS

913import os885import os

914import ssl886import ssl

915 887 

916from openai import OpenAI, DefaultHttpxClient888from openai import OpenAI, DefaultHttpx2Client

917 889 

918# Server trust is configured independently. Without `cafile`, this uses the890# Server trust is configured independently. Without `cafile`, this uses the

919# operating system's normal trusted certificate authorities.891# operating system's normal trusted certificate authorities.

938 ),910 ),

939 # A client certificate belongs to the HTTP client, not the base URL.911 # A client certificate belongs to the HTTP client, not the base URL.

940 # Disable redirects so it cannot follow a response to another origin.912 # Disable redirects so it cannot follow a response to another origin.

941 http_client=DefaultHttpxClient(913 http_client=DefaultHttpx2Client(

942 verify=ssl_context,914 verify=ssl_context,

943 follow_redirects=False,915 follow_redirects=False,

944 ),916 ),

951import os923import os

952import ssl924import ssl

953 925 

954from openai import AsyncOpenAI, DefaultAsyncHttpxClient926from openai import AsyncOpenAI, DefaultAsyncHttpx2Client

955 927 

956ssl_context = ssl.create_default_context(928ssl_context = ssl.create_default_context(

957 cafile=os.environ.get("OPENAI_MTLS_CA_BUNDLE"),929 cafile=os.environ.get("OPENAI_MTLS_CA_BUNDLE"),

968 "OPENAI_BASE_URL",940 "OPENAI_BASE_URL",

969 "https://mtls.api.openai.com/v1",941 "https://mtls.api.openai.com/v1",

970 ),942 ),

971 http_client=DefaultAsyncHttpxClient(943 http_client=DefaultAsyncHttpx2Client(

972 verify=ssl_context,

973 follow_redirects=False,

974 ),

975)

976```

977 

978Experimental HTTPX2 uses the same native `SSLContext`. Install the optional

979extra with `pip install 'openai[httpx2]'`, then use `DefaultHttpx2Client` or

980`DefaultAsyncHttpx2Client` in place of the corresponding HTTPX client above:

981 

982```python

983from openai import OpenAI, DefaultHttpx2Client

984 

985client = OpenAI(

986 api_key=os.environ["OPENAI_API_KEY"],

987 base_url=os.environ.get(

988 "OPENAI_BASE_URL",

989 "https://mtls.api.openai.com/v1",

990 ),

991 http_client=DefaultHttpx2Client(

992 verify=ssl_context,944 verify=ssl_context,

993 follow_redirects=False,945 follow_redirects=False,

994 ),946 ),

1001The certificate-bearing HTTP client is transport-wide. Dedicate it to the953The certificate-bearing HTTP client is transport-wide. Dedicate it to the

1002selected mTLS origin; do not reuse it for other services or pass it through954selected mTLS origin; do not reuse it for other services or pass it through

1003`with_options()` with a different `base_url`. If redirects are required, add an955`with_options()` with a different `base_url`. If redirects are required, add an

1004HTTPX request hook that rejects requests whose scheme, host, or port differs956HTTPX2 request hook that rejects requests whose scheme, host, or port differs

1005from the configured mTLS origin before enabling `follow_redirects`.957from the configured mTLS origin before enabling `follow_redirects`.

1006 958 

1007`SSLContext.load_cert_chain()` raises during setup for unreadable or malformed959`SSLContext.load_cert_chain()` raises during setup for unreadable or malformed

792 792 

793## Advanced concepts793## Advanced concepts

794 794 

795### Default request headers

796 

797Use `default_headers` to send the same custom headers with every request made by a client:

798 

799```ruby

800finance = OpenAI::Client.new(

801 default_headers: {"x-cost-center" => "finance"}

802)

803```

804 

805Explicit `default_headers` override values from `OPENAI_CUSTOM_HEADERS`. For a single request,

806`request_options[:extra_headers]` can override a client default or remove it by assigning `nil`.

807Authentication and endpoint-specific headers also take precedence over client defaults.

808 

795### BaseModel809### BaseModel

796 810 

797All parameter and response objects inherit from `OpenAI::Internal::Type::BaseModel`, which provides several conveniences, including:811All parameter and response objects inherit from `OpenAI::Internal::Type::BaseModel`, which provides several conveniences, including:

269 269 

270Verifying webhook signatures is _optional but encouraged_.270Verifying webhook signatures is _optional but encouraged_.

271 271 

272Webhook verification is asynchronous. Always `await` `unwrap()` or `verifySignature()` before trusting

273the event.

274 

272For more information about webhooks, see [the API docs](https://platform.openai.com/docs/guides/webhooks).275For more information about webhooks, see [the API docs](https://platform.openai.com/docs/guides/webhooks).

273 276 

274### Parsing webhook payloads277### Parsing webhook payloads

290 const body = await request.text();293 const body = await request.text();

291 294 

292 try {295 try {

293 const event = client.webhooks.unwrap(body, headersList);296 const event = await client.webhooks.unwrap(body, headersList);

294 297 

295 switch (event.type) {298 switch (event.type) {

296 case 'response.completed':299 case 'response.completed':

330 const body = await request.text();333 const body = await request.text();

331 334 

332 try {335 try {

333 client.webhooks.verifySignature(body, headersList);336 await client.webhooks.verifySignature(body, headersList);

334 337 

335 // Parse the body after verification338 // Parse the body after verification

336 const event = JSON.parse(body);339 const event = JSON.parse(body);