Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us