An excerpt from the repository, fetched Nov 13, 2026.
Read the project’s introduction
OpenAI Python API library
The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.10+
application. The library includes type definitions for all request params and response fields,
and offers both synchronous and asynchronous clients powered by HTTPX2.
It is generated from our OpenAPI specification.
Documentation
The REST API documentation can be found on platform.openai.com. The full API of this library can be found in api.md.
Installation
# install from PyPI
pip install openai
Usage
The full API of this library can be found in api.md.
The primary API for interacting with OpenAI models is the Responses API. You can generate text from the model with the code below.
import os
from openai import OpenAI
client = OpenAI(
# This is the default and can be omitted
api_key=os.environ.get("OPENAI_API_KEY"),
)
response = client.responses.create(
model="gpt-5.5",
instructions="You are a coding assistant that talks like a pirate.",
input="How do I check if a Python object is an instance of a class?",
)
print(response.output_text)
The previous standard (supported indefinitely) for generating text is the Chat Completions API. You can use that API to generate text from the model with the code below.
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "developer", "content": "Talk like a pirate."},
{
"role": "user",
"content": "How do I check if a Python object is an instance of a class?",
},
],
)
print(completion.choices[0].message.content)
While you can provide an api_key keyword argument,
we recommend using python-dotenv
to add OPENAI_API_KEY="My API Key" to your .env file
so that your API key is not stored in source control.
Get an API key here.
Workload Identity Authentication
For secure, automated environments like cloud-managed Kubernetes, Azure, and Google Cloud Platform, you can use workload identity authentication with short-lived tokens from cloud identity providers instead of long-lived API keys.
Kubernetes (service account tokens)
from openai import OpenAI
from openai.auth import k8s_service_account_token_provider
client = OpenAI(
workload_identity={
"identity_provider_id": "idp-123",
"service_account_id": "sa-456",
"provider": k8s_service_account_token_provider("/var/run/secrets/kubernetes.io/serviceaccount/token"),
},
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Hello!"}],
)
Azure (managed identity)
from openai import OpenAI
from openai.auth import azure_managed_identity_token_provider
client = OpenAI(
workload_identity={
"identity_provider_id": "idp-123",
"service_account_id": "sa-456",
"provider": azure_managed_identity_token_provider(
resource="https://management.azure.com/",
),
},
)
Google Cloud Platform (compute engine metadata)
from openai import OpenAI
from openai.auth import gcp_id_token_provider
client = OpenAI(
workload_identity={
"identity_provider_id": "idp-123",
"service_account_id": "sa-456",
"provider": gcp_id_token_provider(audience="https://api.openai.com/v1"),
},
)
Custom subject token provider
from openai import OpenAI
def get_custom_token() -> str:
return "your-jwt-token"
client = OpenAI(
workload_identity={
"identity_provider_id": "idp-123",
"service_account_id": "sa-456",
"provider": {
"token_type": "jwt",
"get_token": get_custom_token,
},
}
)
You can also customize the token refresh buffer (default is 1200 seconds (20 minutes) before expiration):
from openai import OpenAI
from openai.auth import k8s_service_account_token_provider
client = OpenAI(
workload_identity={
"identity_provider_id": "idp-123",
"service_account_id": "sa-456",
"provider": k8s_service_account_token_provider("/var/token"),
"refresh_buffer_seconds": 120.0,
}
)
X.509 workload identity (mutual TLS)
For X.509 workload identity federation, configure the client certificate and
server trust on an HTTPX2 client, then pass only the identity-provider and
service-account IDs to the SDK:
import os
import ssl
from openai import OpenAI, DefaultHttpx2Client
from openai.auth import x509_workload_identity
tls_context = ssl.create_default_context(
cafile=os.getenv("OPENAI_MTLS_CA_BUNDLE"),
)
tls_context.load_cert_chain(
certfile=os.environ["OPENAI_MTLS_CERTIFICATE_CHAIN"],
keyfile=os.environ["OPENAI_MTLS_PRIVATE_KEY"],
password=os.getenv("OPENAI_MTLS_PRIVATE_KEY_PASSWORD"),
)
client = OpenAI(
workload_identity=x509_workload_identity(
identity_provider_id=os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
service_account_id=os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
# refresh_buffer_seconds=120.0,
),
http_client=DefaultHttpx2Client(
verify=tls_context,
follow_redirects=False,
),
)
X.509 mode defaults to https://mtls.api.openai.com/v1 when neither base_url
nor OPENAI_BASE_URL is set. The same configured HTTP client presents its
certificate to the fixed mTLS token-exchange endpoint and to the API. Tokens
are exchanged lazily, cached, and refreshed automatically. Certificate files,
private keys, passwords, server trust, proxies, and rotation remain application
and transport concerns.
X.509 API requests require HTTPS and must stay on the configured API origin.
The effective HTTP Host authority must match that origin.
Provider API-key and proxy-only headers cannot be sent to the API alongside
X.509 authentication.
Token exchanges do not inherit API request hooks, authentication, or cookies.
Identity settings are captured when the client is constructed; create a new
client to change the identity. Azure clients do not support X.509 workload
identity.
For asynchronous req
Read the full README on GitHub
