Connect

To connect to the OpenAI API:

Populate an OPENAI_API_KEY environment variable with your OpenAI API key
Create a synchronous or asynchronous OpenAI client object.

Tip

To reduce the risk of committing your OpenAI API key to source control, you can use python-dotenv and add OPENAI_API_KEY="YOUR_API_KEY_HERE" to your .env file.

Synchronous client

Create an instance of the OpenAI client:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"), # (1)
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "Say this is a test",
        }
    ],
    model="gpt-3.5-turbo",
)

You can omit this parameter if the OPENAI_API_KEY environment variable is set and contains a valid key. By default, the OpenAI() client attempts to read the OPENAI_API_KEY env var upon instantiation.

Streaming helpers

The SDK also includes helpers to process streams and handle the incoming events.

with client.beta.threads.runs.create_and_stream(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
) as stream:
    for event in stream:
        # Print the text from text delta events
        if event.type == "thread.message.delta" and event.data.delta.content:
            print(event.data.delta.content[0].text)

More information on streaming helpers can be found in the dedicated documentation: helpers.md

Asynchronous client

Create an instance of the AsyncOpenAI client and await each API call. Functionality between the synchronous and asynchronous clients is otherwise identical.

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"), # (1)
)


async def main() -> None:
    chat_completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Say this is a test",
            }
        ],
        model="gpt-3.5-turbo",
    )


asyncio.run(main())

You can omit this parameter if the OPENAI_API_KEY environment variable is set and contains a valid key. By default, the AsyncOpenAI() client attempts to read the OPENAI_API_KEY env var upon instantiation.

You can enable response streaming in the async client by including stream=True to the AsyncCompletions.create() method:

from openai import AsyncOpenAI

client = AsyncOpenAI()


async def main():
    stream = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Say this is a test"}],
        stream=True, # (1)
    )
    async for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="")


asyncio.run(main())

This enables response streaming through Server Side Events (SSE).

Module-level global client

Similar to pre-v1 versions of the library, there is also a module-level client available for use in REPLs, notebooks, and other scenarios requiring quick "local loop" iteration.

Do NOT use the module-level global client in production application code. Instead, create instances of OpenAI or AsyncOpenAI client objects as described earlier rather than relying on the global client.

# WARNING: Use this client instantiation technique **only** in REPLs, notebooks,
#          or other scenarios requiring quick local-loop iteration.

import openai

# optional; defaults to `os.environ['OPENAI_API_KEY']`
openai.api_key = '...'

# all client options can be configured just like the `OpenAI` instantiation counterpart
openai.base_url = "https://..."
openai.default_headers = {"x-foo": "true"}

completion = openai.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "user",
            "content": "How do I output all files in a directory using Python?",
        },
    ],
)
print(completion.choices[0].message.content)

We recommend you avoid using this module-level client your application code because:

It can be difficult to reason about where client options are configured.
It's impossible to change certain client options without causing the potential for race conditions.
It's harder to mock for testing purposes.
It's impossible to control cleanup of network connections.

Examples

#!/usr/bin/env -S poetry run python

from openai import OpenAI

# gets API Key from environment variable OPENAI_API_KEY
client = OpenAI()

# Non-streaming:
print("----- standard request -----")
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test",
        },
    ],
)
print(completion.choices[0].message.content)

# Streaming:
print("----- streaming request -----")
stream = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "user",
            "content": "How do I output all files in a directory using Python?",
        },
    ],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:
        continue

    print(chunk.choices[0].delta.content, end="")
print()