Skip to main content
The main client class for interacting with the OpenAI API synchronously.

​
Constructor

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    organization="org-xxx",
    project="proj-xxx"
)

​
Parameters

​
api_key
str | Callable[[], str] | None
default:"None"
Your OpenAI API key. If not provided, the client will attempt to read it from the OPENAI_API_KEY environment variable. Required.Can also be a callable that returns a string, which will be called to refresh the API key when needed.
​
organization
str | None
default:"None"
Your OpenAI organization ID. If not provided, the client will attempt to read it from the OPENAI_ORG_ID environment variable.When provided, this will be sent as the OpenAI-Organization header on all requests.
​
project
str | None
default:"None"
Your OpenAI project ID. If not provided, the client will attempt to read it from the OPENAI_PROJECT_ID environment variable.When provided, this will be sent as the OpenAI-Project header on all requests.
​
webhook_secret
str | None
default:"None"
Secret key for validating webhook signatures. If not provided, the client will attempt to read it from the OPENAI_WEBHOOK_SECRET environment variable.
​
base_url
str | httpx.URL | None
default:"None"
Override the default base URL for the API. If not provided, the client will attempt to read it from the OPENAI_BASE_URL environment variable, otherwise defaults to https://api.openai.com/v1.
​
websocket_base_url
str | httpx.URL | None
default:"None"
Base URL for WebSocket connections (used for Realtime API).If not specified, the default base URL will be used with the scheme changed to wss://. For example, https://api.openai.com becomes wss://api.openai.com.
​
timeout
float | Timeout | None
default:"600 seconds"
Request timeout configuration. Can be:
  • A float representing timeout in seconds
  • An httpx.Timeout object for fine-grained control
  • None to disable timeouts
Default is 600 seconds (10 minutes) for the overall timeout and 5 seconds for connect timeout.
​
max_retries
int
default:"2"
Maximum number of retries for failed requests. Set to 0 to disable retries.The client will automatically retry requests that fail due to network errors or certain HTTP status codes (429, 500, 502, 503, 504).
​
default_headers
Mapping[str, str] | None
default:"None"
Additional HTTP headers to include on all requests.
​
default_query
Mapping[str, object] | None
default:"None"
Default query parameters to include on all requests.
​
http_client
httpx.Client | None
default:"None"
Custom httpx.Client instance to use for making requests.You can use DefaultHttpxClient to retain the default values for limits, timeout, and follow_redirects while customizing other options.

​
Properties

The client provides access to various API resources through properties:
  • client.chat - Chat completions
  • client.completions - Text completions
  • client.embeddings - Embeddings
  • client.files - File operations
  • client.images - Image generation
  • client.audio - Audio transcription and generation
  • client.moderations - Content moderation
  • client.models - Model information
  • client.fine_tuning - Fine-tuning operations
  • client.batches - Batch API
  • client.uploads - Multipart file uploads
  • client.beta - Beta features (Assistants, Threads, etc.)
  • client.vector_stores - Vector store operations
  • client.realtime - Realtime API
  • client.webhooks - Webhook utilities

​
Examples

​
Basic usage

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

​
With explicit API key

client = OpenAI(api_key="sk-...")

​
With organization and project

client = OpenAI(
    organization="org-xxx",
    project="proj-xxx"
)

​
Custom timeout configuration

import httpx

# Simple timeout (in seconds)
client = OpenAI(timeout=30.0)

# Fine-grained timeout control
client = OpenAI(
    timeout=httpx.Timeout(
        timeout=60.0,  # Total request timeout
        connect=5.0,   # Connection timeout
        read=30.0,     # Read timeout
        write=10.0     # Write timeout
    )
)

​
Custom retry configuration

# No retries
client = OpenAI(max_retries=0)

# More aggressive retries
client = OpenAI(max_retries=5)

​
Custom HTTP client with connection pooling

import httpx
from openai import OpenAI, DefaultHttpxClient

# Custom connection limits
client = OpenAI(
    http_client=DefaultHttpxClient(
        limits=httpx.Limits(
            max_connections=100,
            max_keepalive_connections=20
        )
    )
)

​
Using a callable for dynamic API key

def get_api_key():
    # Fetch API key from secure storage
    return fetch_from_vault("openai_api_key")

client = OpenAI(api_key=get_api_key)

​
Custom headers

client = OpenAI(
    default_headers={
        "X-Custom-Header": "value"
    }
)

​
Using with_options for per-request configuration

client = OpenAI()

# Make a single request with custom timeout
response = client.with_options(timeout=30.0).chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

​
Methods

​
copy()

Create a new client instance with the same configuration, optionally overriding specific options. 
base_client = OpenAI()

# Create a copy with different timeout
new_client = base_client.copy(timeout=30.0)

# Create a copy with different organization
org_client = base_client.copy(organization="org-different")

​
with_options()

Alias for copy(), useful for inline usage: 
client.with_options(timeout=10).chat.completions.create(...)

Build docs developers (and LLMs) love

Get started for freeTalk to us