Client Initialization

Learn how to initialize and configure OpenAI and AsyncOpenAI clients

Overview

The OpenAI Python SDK provides two client classes for interacting with the API:

• OpenAI - Synchronous client for blocking operations
• AsyncOpenAI - Asynchronous client for concurrent operations

Both clients automatically infer credentials from environment variables and provide the same interface for API operations.

Basic Initialization

Synchronous Client

from openai import OpenAI

client = OpenAI()

The client automatically reads the OPENAI_API_KEY environment variable. You can also pass the API key explicitly:

client = OpenAI(api_key="your-api-key-here")

Asynchronous Client

from openai import AsyncOpenAI

client = AsyncOpenAI()

The AsyncOpenAI client provides the same initialization options as OpenAI. All API methods return awaitable coroutines.

Configuration Options

The client accepts several configuration parameters to customize behavior:

api_key · str | Callable[[], str]

Your OpenAI API key. Can be a string or a callable that returns a string (for dynamic key rotation).

Environment variable: OPENAI_API_KEY

organization · str | None · default: "None"

Your organization ID for API requests.

Environment variable: OPENAI_ORG_ID

project · str | None · default: "None"

Your project ID for API requests.

Environment variable: OPENAI_PROJECT_ID

base_url · str | httpx.URL | None · default: "https://api.openai.com/v1"

Override the default API base URL.

Environment variable: OPENAI_BASE_URL

timeout · float | Timeout | None · default: "600 seconds"

Request timeout in seconds. Can be a float or an httpx.Timeout object for granular control.

See Timeouts for detailed configuration.

max_retries · int · default: "2"

Maximum number of retry attempts for failed requests.

See Retries for retry behavior details.

default_headers · Mapping[str, str] | None · default: "None"

Additional headers to include with every request.

default_query · Mapping[str, object] | None · default: "None"

Additional query parameters to include with every request.

http_client · httpx.Client | httpx.AsyncClient | None · default: "None"

Custom HTTP client instance. Use DefaultHttpxClient or DefaultAsyncHttpxClient to preserve SDK defaults.

webhook_secret · str | None · default: "None"

Secret for webhook signature verification.

Environment variable: OPENAI_WEBHOOK_SECRET

websocket_base_url · str | httpx.URL | None · default: "None"

Base URL for WebSocket connections. If not specified, the default base URL is used with ‘wss://’ scheme.

Advanced Configuration

Custom Headers and Query Parameters

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

Organization and Project IDs

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

Organization and Project IDs are sent as OpenAI-Organization and OpenAI-Project headers with each request.

Dynamic API Keys

For scenarios requiring API key rotation, you can provide a callable:

def get_api_key() -> str:
    # Fetch API key from secure storage
    return fetch_from_vault()

client = OpenAI(api_key=get_api_key)

For async clients, the callable can be async:

async def get_api_key() -> str:
    # Fetch API key asynchronously
    return await fetch_from_vault_async()

client = AsyncOpenAI(api_key=get_api_key)

Custom HTTP Client

Customize the underlying HTTP client for advanced use cases like proxies or custom transports:

import httpx
from openai import OpenAI, DefaultHttpxClient

client = OpenAI(
    http_client=DefaultHttpxClient(
        proxy="http://proxy.example.com:8080",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

When providing a custom http_client, use DefaultHttpxClient or DefaultAsyncHttpxClient to preserve the SDK’s default timeout, connection limits, and redirect behavior.

Context Manager Usage

Both clients support context managers for automatic resource cleanup:

with OpenAI() as client:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
# Client is automatically closed

Async client:

async with AsyncOpenAI() as client:
    response = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
# Client is automatically closed

Per-Request Configuration

Override client settings for individual requests using with_options():

client = OpenAI()

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

# Override max_retries for a single request
response = client.with_options(max_retries=5).chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
)

Client Lifecycle

Manual Cleanup

If not using a context manager, manually close the client when done:

client = OpenAI()
try:
    # Use client
    pass
finally:
    client.close()

Async client:

client = AsyncOpenAI()
try:
    # Use client
    pass
finally:
    await client.close()

The client automatically closes when garbage collected, but explicit cleanup is recommended for long-running applications.

Related

• Async Operations - Using AsyncOpenAI for concurrent requests
• Timeouts - Configuring request timeouts
• Retries - Understanding retry behavior
• Error Handling - Handling API errors