AsyncOpenAI Client

The async client class for interacting with the OpenAI API asynchronously using async/await.

Constructor

from openai import AsyncOpenAI
import asyncio

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

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

asyncio.run(main())

Parameters

api_key · str | Callable[[], Awaitable[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 an async 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.AsyncClient | None · default: "None"

Custom httpx.AsyncClient instance to use for making requests.

You can use DefaultAsyncHttpxClient 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

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

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

asyncio.run(main())

Streaming responses

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    stream = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Tell me a story"}],
        stream=True
    )
    
    async for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")

asyncio.run(main())

Concurrent requests

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def get_completion(prompt: str):
    response = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

async def main():
    prompts = [
        "What is Python?",
        "What is JavaScript?",
        "What is Rust?"
    ]
    
    # Run all requests concurrently
    results = await asyncio.gather(*[
        get_completion(prompt) for prompt in prompts
    ])
    
    for prompt, result in zip(prompts, results):
        print(f"{prompt}\n{result}\n")

asyncio.run(main())

Custom timeout configuration

import httpx
from openai import AsyncOpenAI

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

# Fine-grained timeout control
client = AsyncOpenAI(
    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 = AsyncOpenAI(max_retries=0)

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

Custom HTTP client with connection pooling

import httpx
from openai import AsyncOpenAI, DefaultAsyncHttpxClient

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

Using an async callable for dynamic API key

import asyncio
from openai import AsyncOpenAI

async def get_api_key():
    # Fetch API key from async secure storage
    return await fetch_from_vault_async("openai_api_key")

client = AsyncOpenAI(api_key=get_api_key)

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

asyncio.run(main())

Context manager for automatic cleanup

import asyncio
from openai import AsyncOpenAI

async def main():
    async with AsyncOpenAI() as client:
        response = await client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "Hello!"}]
        )
        print(response)

asyncio.run(main())

Using with_options for per-request configuration

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

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

asyncio.run(main())

Methods

copy()

Create a new client instance with the same configuration, optionally overriding specific options.

base_client = AsyncOpenAI()

# 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:

await client.with_options(timeout=10).chat.completions.create(...)

Differences from Sync Client

The AsyncOpenAI client is functionally identical to the synchronous OpenAI client, with the following key differences:

1. All API methods are async - Use await when calling API methods
2. Async HTTP client - Accepts httpx.AsyncClient instead of httpx.Client
3. Async API key callable - The api_key parameter can be an async function returning Awaitable[str]
4. AsyncStream - Streaming responses return AsyncStream objects that are iterated with async for
5. Context manager support - Can be used with async with for automatic cleanup