OpenAI Python Library

The chat.completions.parse() method imposes stricter constraints than the standard chat.completions.create() method:

1. Error Handling: If the completion finishes due to length or content_filter, the SDK will raise LengthFinishReasonError or ContentFilterFinishReasonError instead of returning a standard completion object.
2. Tool Strictness: Only strict function tools are supported (e.g., tools where "strict": True is explicitly set).

In API responses, a field might be explicitly null in JSON or missing entirely. Both result in None in Python. To distinguish them, check the .model_fields_set attribute on the response object.

if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.')
  else:
    print('Got json like {"my_field": null}.')

The library uses TypedDict for nested request parameters to provide autocomplete and type safety. Responses are returned as Pydantic models, which include helper methods:

• model.to_json(): Serializes the model to a JSON string.
• model.to_dict(): Converts the model to a dictionary.

List methods in the OpenAI API return paginated results. The library provides two ways to handle this:

1. Auto-pagination: Use the returned iterator to automatically fetch successive pages as you iterate. This works for both synchronous (OpenAI) and asynchronous (AsyncOpenAI) clients.
2. Manual pagination: For granular control, use the following methods on the page object:
   • .has_next_page(): Returns a boolean indicating if more data exists.
   • .next_page_info(): Returns the cursor/details needed for the next page.
   • .get_next_page(): Fetches the next page of results.

You can also access the cursor directly via the .after property on the page object.

from openai import OpenAI

client = OpenAI()

# Auto-pagination: fetches more pages as needed
for job in client.fine_tuning.jobs.list(limit=20):
    print(job)

Every object response provides a public _request_id property, which corresponds to the x-request-id header. This is useful for logging and reporting issues to OpenAI.

Important: For failed requests, you must catch the openai.APIStatusError exception to access the request_id property on the exception object itself.

# From a successful response
response = await client.responses.create(model="gpt-5.5", input="...")
print(response._request_id)

# From a failed request
import openai
try:
    await client.chat.completions.create(model="gpt-5.5", messages=[...])
except openai.APIStatusError as exc:
    print(exc.request_id)  # Access ID from the exception
    raise exc

The Responses API is the primary API for interacting with OpenAI models. You can instantiate the OpenAI client and use client.responses.create() to generate text. By default, the client looks for an OPENAI_API_KEY environment variable.

import os
from openai import OpenAI

client = OpenAI(
    # This is the default and can be omitted
    api_key=os.environ.get("OPENAI_API_KEY"),
)

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are a coding assistant that talks like a pirate.",
    input="How do I check if a Python object is an instance of a class?",
)

print(response.output_text)

You can stream responses by setting stream=True in the create method. This returns an iterator that yields events. This works for both synchronous and asynchronous clients.

# Synchronous streaming
from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
    model="gpt-5.5",
    input="Write a story.",
    stream=True,
)
for event in stream:
    print(event)

# Asynchronous streaming
import asyncio
from openai import AsyncOpenAI
async def main():
    client = AsyncOpenAI()
    stream = await client.responses.create(
        model="gpt-5.5",
        input="Write a story.",
        stream=True,
    )
    async for event in stream:
        print(event)

asyncio.run(main())

Install the OpenAI library from PyPI using pip. This library requires Python 3.10 or higher.

# install from PyPI
pip install openai

If you require support for httpx2, install the httpx2 extra. You can then use httpx_aiohttp.httpx2.Httpx2AiohttpClient or httpx_aiohttp.httpx2.AiohttpTransport within your application.

uv pip install httpx-aiohttp[httpx2]

The library closes underlying HTTP connections when the client is garbage collected. To manage resources explicitly, use a context manager or call the .close() method.

from openai import OpenAI

with OpenAI() as client:
  # make requests here
  ...

# HTTP client is now closed