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 theOPENAI_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 theOPENAI_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()