Python SDK for OpenAI API v2.31 providing type-safe access to Responses API, Chat Completions, embeddings, audio transcription/synthesis, image generation, assistants, fine-tuning, and batch operations with sync/async clients. Use when building Python applications that integrate with OpenAI models for text generation, vision, audio processing, or automated assistants.
Python SDK for OpenAI API v2.31 providing type-safe access to Responses API, Chat Completions, embeddings, audio transcription/synthesis, image generation, assistants, fine-tuning, and batch operations with sync/async clients. Use when building Python applications that integrate with OpenAI models for text generation, vision, audio processing, or automated assistants.
The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.9+ application. Generated from the official OpenAPI specification with Stainless, it includes type definitions for all request parameters and response fields, and offers both synchronous and asynchronous clients powered by httpx (with optional aiohttp backend).
The primary API is the Responses API, with the previous Chat Completions API supported indefinitely. Additional capabilities include embeddings, audio transcription and synthesis, image generation, fine-tuning, batch processing, assistants, vector stores, real-time WebSocket conversations, moderations, and more.
When to Use
Building Python applications that call OpenAI models (GPT-4, GPT-5, o-series, etc.)
Generating text via the Responses API or Chat Completions API
Creating embeddings for semantic search or RAG pipelines
Transcribing audio, translating speech, or generating speech from text
Generating images with DALL·E models
Building automated assistants with threads, runs, and tool use
Fine-tuning models on custom datasets
Processing requests in batch for cost efficiency
Implementing real-time conversational experiences via WebSocket
Installation / Setup
Install from PyPI:
pip install openai
For aiohttp backend support (improved async concurrency):
pip install "openai[aiohttp]"
Configuration
Set the OPENAI_API_KEY environment variable or pass it directly:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("OPENAI_API_KEY"),
)
Recommended: use a .env file with python-dotenv to avoid storing keys in source control. Get an API key at platform.openai.com.
Default timeout is 10 minutes (600s). Default max retries is 2 with exponential backoff starting at 0.5s (max 8s).
Core Concepts
Two API Paradigms
Responses API — the current primary interface. Uses input (array of messages) and instructions instead of messages and system. Returns structured Response objects with output_text, output, and usage metadata.
response = client.responses.create(
model="gpt-5.2",
instructions="You are a coding assistant.",
input="How do I check if a Python object is an instance of a class?",
)
print(response.output_text)
Chat Completions API — the previous standard, supported indefinitely. Uses messages array with role/content pairs.
completion = client.chat.completions.create(
model="gpt-5.2",
messages=[
{"role": "developer", "content": "You are a coding assistant."},
{"role": "user", "content": "How do I check if a Python object is an instance of a class?"},
],
)
print(completion.choices[0].message.content)
Sync and Async Clients
OpenAI is synchronous. AsyncOpenAI is asynchronous — identical API surface with await:
