OpenAI Python

The OpenAI Python library gives you programmatic access to the OpenAI REST API from any Python 3.10+ application. It's built for developers integrating GPT models, embeddings, fine-tuning, file uploads, or realtime audio/text conversations into their own Python code, whether that's a backend service, a CLI tool, or a data pipeline.

The library is generated from OpenAI's OpenAPI specification using Stainless, so its method signatures and types track the API surface closely. It ships both a synchronous OpenAI client and an asynchronous AsyncOpenAI client with identical interfaces, backed by httpx (with optional aiohttp or experimental httpx2 transports).

Key features

• Typed requests and responses: request params are TypedDicts and responses are Pydantic models, giving autocomplete, validation, and .to_json()/.to_dict() helpers.
• Sync and async clients: OpenAI and AsyncOpenAI expose the same API surface, so switching between blocking and asyncio code is a matter of swapping the class and adding await.
• Responses and Chat Completions APIs: supports the newer Responses API (client.responses.create) and the long-supported Chat Completions API (client.chat.completions.create).
• Streaming: server-sent events let you stream model output token by token for both sync and async clients.
• Realtime API: WebSocket-based client for low-latency, multi-modal (text and audio) conversations with function calling support.
• Workload identity authentication: short-lived token providers for Kubernetes service accounts, Azure managed identity, and GCP metadata, as an alternative to long-lived API keys.
• Auto-paginating iterators: list endpoints (like fine-tuning jobs) can be iterated directly without manually managing page cursors.
• File uploads: pass bytes, PathLike objects, or (filename, contents, media type) tuples for endpoints that accept file input.
• Webhook verification: client.webhooks.unwrap() verifies and parses incoming webhook payloads from OpenAI.
• Vision input: send image URLs or base64-encoded images alongside text prompts to multi-modal models.

Ideal use cases

• Building a Python backend or CLI that calls GPT models for text generation, chat, or structured output.
• Adding streaming chat responses to a web app or bot, using either the sync or async client depending on your framework.
• Building realtime voice or text assistants over WebSockets, such as push-to-talk apps.
• Automating fine-tuning workflows or bulk file uploads to the OpenAI API.
• Running in cloud environments (Kubernetes, Azure, GCP) where you want to avoid storing static API keys and instead use workload identity tokens.
• Handling OpenAI webhook events in a server, with signature verification built in.

This library is not a good fit if you need a non-Python language binding (OpenAI maintains separate SDKs for other languages), if you're looking for a client for a different LLM provider, or if you want a higher-level agent/orchestration framework rather than a direct API client. It's also not meant for offline or local model inference; it only talks to OpenAI's hosted API.

Installation

Install from PyPI:

pip install openai

Set your API key as an environment variable (recommended over hardcoding it):

export OPENAI_API_KEY="your-api-key"

Or load it from a .env file using python-dotenv. Then use the client:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

response = client.responses.create(
    model="gpt-5.5",
    input="Hello, world",
)
print(response.output_text)

For improved async concurrency, install the optional aiohttp backend (requires Python 3.10+):

pip install openai[aiohttp]

For experimental HTTPX2 transport support:

pip install 'openai[httpx2]'

Requires Python 3.10 or later in all cases.