OpenAI Python SDK

The openai package is OpenAI’s official Python client, giving typed, generated access to the full REST API — Responses, Chat Completions, Embeddings, Files, Fine-tuning, Realtime, Vector Stores, and more — from a single OpenAI (or AsyncOpenAI) client object. Every resource ships synchronous and asynchronous variants built on HTTPX2, with Pydantic-modeled request and response objects so editors and type checkers catch mistakes before a request is even sent.

Beyond the base HTTP surface, the library adds the pieces most teams end up rebuilding by hand: automatic retries with backoff on transient errors, request-ID propagation for support tickets, cursor-based pagination helpers, streaming iterators for both the Responses and Chat Completions APIs, WebSocket-based Realtime API support, webhook signature verification, and first-party workload-identity auth (Kubernetes service accounts, Azure managed identity, GCP metadata tokens) alongside plain API keys. Azure OpenAI and Amazon Bedrock are supported through drop-in client subclasses.

What You Get

• Typed OpenAI and AsyncOpenAI clients covering every REST endpoint, generated directly from OpenAI’s OpenAPI specification
• Streaming support for the Responses and Chat Completions APIs, plus a dedicated WebSocket client for the Realtime API
• Built-in retry logic, timeout configuration, request-ID propagation, and cursor-based pagination for list endpoints
• .with_raw_response and .with_streaming_response accessors for reading headers or streaming bytes without a second client
• Workload-identity authentication providers for Kubernetes, Azure, and GCP, plus drop-in AzureOpenAI and Bedrock client subclasses
• Webhook payload parsing and signature verification helpers for handling asynchronous events (e.g. completed fine-tuning jobs)

Common Use Cases

• Calling GPT models for text generation, chat, and tool/function calling from a Python backend
• Building an async FastAPI or Django service that streams model output token-by-token to clients
• Running fine-tuning jobs and managing uploaded training files programmatically
• Building a realtime voice assistant over the WebSocket-based Realtime API
• Deploying the same codebase against OpenAI, Azure OpenAI, or Bedrock-hosted models with minimal changes

Under The Hood

Architecture

The public entry point is the OpenAI/AsyncOpenAI class pair in _client.py, which subclasses the shared SyncAPIClient/AsyncAPIClient base in _base_client.py and exposes one namespaced resource object per API surface (chat, responses, embeddings, files, fine_tuning, realtime, vector_stores, and more) mirrored under resources/. Each resource module is mechanically generated from OpenAI’s OpenAPI spec and composes three response variants per endpoint — plain, WithRawResponse, and WithStreamingResponse — via thin wrapper classes, with request/response bodies modeled as Pydantic BaseModel subclasses in _models.py and list endpoints handled by shared cursor/page classes in pagination.py. Streaming goes through a dedicated _streaming.py module plus per-feature streaming helpers under lib/. The generated resource layer is largely boilerplate and low-risk to extend; the base client’s auth, retry, and transport logic is the one piece that would ripple across every resource if changed.

Tech Stack

Built for Python 3.10+ on top of HTTPX2 (a fork/successor of httpx) for transport, Pydantic (supporting both v1 and v2, pinned 1.10–<3) for typed models, anyio for async-runtime abstraction, and jiter for fast JSON decoding. Optional extras add aiohttp as an alternate async transport, websockets for the Realtime API, numpy/pandas for the datalib helpers, sounddevice for voice helpers, and botocore for Bedrock auth. The package is built with hatchling and its dependency graph is locked via uv (uv.lock); CI runs the full pytest, mypy, and ruff suite across the supported Python matrix plus the next CPython prerelease.

Code Quality

The repository ships 159 test_*.py files spanning tests/api_resources, tests/lib, tests/compat, and tests/respx2 fixtures, run with pytest and pytest-asyncio. Source is fully type-annotated (a py.typed marker is present) and checked with mypy in strict mode; ruff enforces lint and formatting in CI. Errors are modeled as an explicit typed exception hierarchy in _exceptions.py rather than surfaced as bare exceptions, and 30 runnable example scripts back the documentation.

What Makes It Unique

Because both sync and async clients, plus Azure and Bedrock variants, are generated from one OpenAPI spec, the library keeps near-total API-surface parity across every access pattern rather than treating async or cloud-vendor support as an afterthought. The .with_raw_response/.with_streaming_response accessor pattern gives typed access to headers or a live stream without instantiating a second client, and pluggable workload-identity token providers (Kubernetes, Azure, GCP, or a custom callback) sit alongside the plain API-key path for teams that need short-lived credentials in managed environments.