> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openai/openai-python/llms.txt
> Use this file to discover all available pages before exploring further.

# AsyncOpenAI Client

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

## Constructor

```python theme={null}
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

<ParamField path="api_key" type="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.
</ParamField>

<ParamField path="organization" type="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.
</ParamField>

<ParamField path="project" type="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.
</ParamField>

<ParamField path="webhook_secret" type="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.
</ParamField>

<ParamField path="base_url" type="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`.
</ParamField>

<ParamField path="websocket_base_url" type="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`.
</ParamField>

<ParamField path="timeout" type="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.
</ParamField>

<ParamField path="max_retries" type="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).
</ParamField>

<ParamField path="default_headers" type="Mapping[str, str] | None" default="None">
  Additional HTTP headers to include on all requests.
</ParamField>

<ParamField path="default_query" type="Mapping[str, object] | None" default="None">
  Default query parameters to include on all requests.
</ParamField>

<ParamField path="http_client" type="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.
</ParamField>

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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
# No retries
client = AsyncOpenAI(max_retries=0)

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

### Custom HTTP client with connection pooling

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
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