openai

The openai package is the core library to install in Python projects that need to call the OpenAI REST API. It includes modules for working with OpenAI resources that provide access to its AI models, including large language models (LLMs) like GPT-4 and models for working with images and audio. The openai package provides both synchronous and asynchronous API clients, options to configure their behavior, and modules that provide Python code with an API surface to interact with the OpenAI platform.

To get started, read the submodule descriptions in resources to determine which best fits your project. For example, the resources.chat submodule description indicates it's a good fit for conversational chat-style interactions with an LLM like GPT-4 Turbo. Or, maybe you need the resources.audio module to perform audio transcription, translation, and speech synthesis in your app.

Once you've determined the resource to use, create an OpenAI or AsyncOpenAI client instance and access the instance attribute for that resource on the client object. For example, if you instantiate an OpenAI client object named client, you'd access the OpenAI.chat instance attribute:

from openai import OpenAI

# Reads API key from OPENAI_API_KEY environment variable
client = OpenAI()

# Use the `chat` resource to interact with the OpenAI chat completions endpoint
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test",
        },
    ],
)
print(completion.choices[0].message.content)

For more information about the REST API this package talks to, or to find client libraries for other programming languages, see:

• REST API reference documentation for the OpenAPI REST API (platform.openai.com)
• OpenAPI Description (OAD) file for the OpenAPI REST API (GitHub)
• More client libraries for the OpenAI API (platform.openai.com)

MODULE	DESCRIPTION
cli
pagination
resources	The resources module aggregates classes and functions for interacting with the OpenAI API into several submodules, each representing a specific resource or feature of the API. The submodules' classes mirror the structure of the API's endpoints and offer synchronous and asynchronous communication with the API. Each resource is accessible as an attribute on the OpenAI and AsyncOpenAI clients. To work with a resource, initialize an instance of a client and then access the resource as an attribute on the client instance. For example, to work with the chat resource, create an instance of the OpenAI client and access the attributes and methods on your_client_instance.chat.
types
version

CLASS	DESCRIPTION
APIConnectionError
APIError
APIResponseValidationError
APIStatusError	Raised when an API response has a status code of 4xx or 5xx.
APITimeoutError
AsyncOpenAI
AsyncStream	Provides the core interface to iterate over an asynchronous stream response.
AuthenticationError
BadRequestError
BaseModel
ConflictError
InternalServerError
NotFoundError
NotGiven	A sentinel singleton class used to distinguish omitted keyword arguments
OpenAI	Primary synchronous client interface for interacting with the services (resources) provided by the OpenAI API.
OpenAIError
PermissionDeniedError
RateLimitError
RequestOptions
Stream	Provides the core interface to iterate over a synchronous stream response.
UnprocessableEntityError

FUNCTION	DESCRIPTION
file_from_path

ATTRIBUTE	DESCRIPTION
AsyncClient
Client
NOT_GIVEN
NoneType	TYPE: Type[None]
ProxiesTypes
Transport
api_key	TYPE: str | None
api_type	TYPE: _ApiType | None
api_version	TYPE: str | None
azure_ad_token	TYPE: str | None
azure_ad_token_provider	TYPE: AzureADTokenProvider | None
azure_endpoint	TYPE: str | None
base_url	TYPE: str | URL | None
default_headers	TYPE: Mapping[str, str] | None
default_query	TYPE: Mapping[str, object] | None
http_client	TYPE: Client | None
max_retries	TYPE: int
organization	TYPE: str | None
timeout	TYPE: float | Timeout | None

AsyncClient module-attribute

AsyncClient = AsyncOpenAI

Client module-attribute

Client = OpenAI

NOT_GIVEN module-attribute

NOT_GIVEN = NotGiven()

NoneType module-attribute

NoneType: Type[None]

ProxiesTypes module-attribute

ProxiesTypes = Union[str, Proxy, ProxiesDict]

Transport module-attribute

Transport = BaseTransport

api_key module-attribute

api_key: str | None = None

api_type module-attribute

api_type: _ApiType | None = cast(
    _ApiType, get("OPENAI_API_TYPE")
)

api_version module-attribute

api_version: str | None = get('OPENAI_API_VERSION')

azure_ad_token module-attribute

azure_ad_token: str | None = get('AZURE_OPENAI_AD_TOKEN')

azure_ad_token_provider module-attribute

azure_ad_token_provider: AzureADTokenProvider | None = None

azure_endpoint module-attribute

azure_endpoint: str | None = get('AZURE_OPENAI_ENDPOINT')

base_url module-attribute

base_url: str | URL | None = None

default_headers module-attribute

default_headers: Mapping[str, str] | None = None

default_query module-attribute

default_query: Mapping[str, object] | None = None

http_client module-attribute

http_client: Client | None = None

max_retries module-attribute

max_retries: int = DEFAULT_MAX_RETRIES

organization module-attribute

organization: str | None = None

timeout module-attribute

timeout: float | Timeout | None = DEFAULT_TIMEOUT

APIConnectionError

APIConnectionError(
    *, message: str = "Connection error.", request: Request
)

APIError

APIError(
    message: str, request: Request, *, body: object | None
)

ATTRIBUTE	DESCRIPTION
body	The API response body. TYPE: object | None
code	TYPE: Optional[str]
message	TYPE: str
param	TYPE: Optional[str]
request	TYPE: Request
type	TYPE: Optional[str]

body instance-attribute

body: object | None = body

The API response body.

If the API responded with a valid JSON structure then this property will be the decoded result.

If it isn't a valid JSON structure then this will be the raw response.

If there was no response associated with this error then it will be None.

code class-attribute instance-attribute

code: Optional[str] = None

message instance-attribute

message: str = message

param class-attribute instance-attribute

param: Optional[str] = None

request instance-attribute

request: Request = request

type instance-attribute

type: Optional[str]

APIResponseValidationError

APIResponseValidationError(
    response: Response,
    body: object | None,
    *,
    message: str | None = None
)

ATTRIBUTE	DESCRIPTION
response	TYPE: Response
status_code	TYPE: int

response instance-attribute

response: Response = response

status_code instance-attribute

status_code: int = status_code

APIStatusError

APIStatusError(
    message: str, *, response: Response, body: object | None
)

Raised when an API response has a status code of 4xx or 5xx.

ATTRIBUTE	DESCRIPTION
response	TYPE: Response
status_code	TYPE: int

response instance-attribute

response: Response = response

status_code instance-attribute

status_code: int = status_code

APITimeoutError

APITimeoutError(request: Request)

AsyncOpenAI

AsyncOpenAI(
    *,
    api_key: str | None = None,
    organization: str | None = None,
    base_url: str | URL | None = None,
    timeout: Union[
        float, Timeout, None, NotGiven
    ] = NOT_GIVEN,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: AsyncClient | None = None,
    _strict_response_validation: bool = False
)

This automatically infers the following arguments from their corresponding environment variables if they are not provided: - api_key from OPENAI_API_KEY - organization from OPENAI_ORG_ID

METHOD	DESCRIPTION
copy	Create a new client instance re-using the same options given to the current client with optional overriding.

ATTRIBUTE	DESCRIPTION
api_key	TYPE: str
audio	TYPE: AsyncAudio
auth_headers	TYPE: dict[str, str]
beta	TYPE: AsyncBeta
chat	TYPE: AsyncChat
completions	TYPE: AsyncCompletions
default_headers	TYPE: dict[str, str | Omit]
embeddings	TYPE: AsyncEmbeddings
files	TYPE: AsyncFiles
fine_tuning	TYPE: AsyncFineTuning
images	TYPE: AsyncImages
models	TYPE: AsyncModels
moderations	TYPE: AsyncModerations
organization	TYPE: str | None
qs	TYPE: Querystring
with_options
with_raw_response	TYPE: AsyncOpenAIWithRawResponse
with_streaming_response	TYPE: AsyncOpenAIWithStreamedResponse

api_key instance-attribute

api_key: str = api_key

audio instance-attribute

audio: AsyncAudio = AsyncAudio(self)

auth_headers property

auth_headers: dict[str, str]

beta instance-attribute

beta: AsyncBeta = AsyncBeta(self)

chat instance-attribute

chat: AsyncChat = AsyncChat(self)

completions instance-attribute

completions: AsyncCompletions = AsyncCompletions(self)

default_headers property

default_headers: dict[str, str | Omit]

embeddings instance-attribute

embeddings: AsyncEmbeddings = AsyncEmbeddings(self)

files instance-attribute

files: AsyncFiles = AsyncFiles(self)

fine_tuning instance-attribute

fine_tuning: AsyncFineTuning = AsyncFineTuning(self)

images instance-attribute

images: AsyncImages = AsyncImages(self)

models instance-attribute

models: AsyncModels = AsyncModels(self)

moderations instance-attribute

moderations: AsyncModerations = AsyncModerations(self)

organization instance-attribute

organization: str | None = organization

qs property

qs: Querystring

with_options class-attribute instance-attribute

with_options = copy

with_raw_response instance-attribute

with_raw_response: AsyncOpenAIWithRawResponse = (
    AsyncOpenAIWithRawResponse(self)
)

with_streaming_response instance-attribute

with_streaming_response: AsyncOpenAIWithStreamedResponse = (
    AsyncOpenAIWithStreamedResponse(self)
)

copy

copy(
    *,
    api_key: str | None = None,
    organization: str | None = None,
    base_url: str | URL | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
    http_client: AsyncClient | None = None,
    max_retries: int | NotGiven = NOT_GIVEN,
    default_headers: Mapping[str, str] | None = None,
    set_default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    set_default_query: Mapping[str, object] | None = None,
    _extra_kwargs: Mapping[str, Any] = {}
) -> Self

Create a new client instance re-using the same options given to the current client with optional overriding.

AsyncStream

AsyncStream(
    *,
    cast_to: type[_T],
    response: Response,
    client: AsyncOpenAI
)

Provides the core interface to iterate over an asynchronous stream response.

METHOD	DESCRIPTION
close	Close the response and release the connection.

ATTRIBUTE	DESCRIPTION
response	TYPE: Response

response instance-attribute

response: Response = response

close async

close() -> None

Close the response and release the connection.

Automatically called if the response body is read to completion.

AuthenticationError

AuthenticationError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[401]

status_code class-attribute instance-attribute

status_code: Literal[401] = 401

BadRequestError

BadRequestError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[400]

status_code class-attribute instance-attribute

status_code: Literal[400] = 400

BaseModel

CLASS	DESCRIPTION
Config

METHOD	DESCRIPTION
construct
model_dump	Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump
model_dump_json	Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump_json

ATTRIBUTE	DESCRIPTION
model_config	TYPE: ConfigDict
model_construct
model_fields_set	TYPE: set[str]

model_config class-attribute

model_config: ConfigDict = ConfigDict(extra='allow')

model_construct class-attribute instance-attribute

model_construct = construct

model_fields_set property

model_fields_set: set[str]

Config

ATTRIBUTE	DESCRIPTION
extra	TYPE: Any

extra class-attribute instance-attribute

extra: Any = allow

construct classmethod

construct(
    _fields_set: set[str] | None = None, **values: object
) -> ModelT

model_dump

model_dump(
    *,
    mode: Literal["json", "python"] | str = "python",
    include: IncEx = None,
    exclude: IncEx = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: bool = True
) -> dict[str, Any]

Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

PARAMETER	DESCRIPTION
mode	The mode in which to_python should run. If mode is 'json', the dictionary will only contain JSON serializable types. If mode is 'python', the dictionary may contain any Python objects. TYPE: Literal['json', 'python'] | str DEFAULT: 'python'
include	A list of fields to include in the output. TYPE: IncEx DEFAULT: None
exclude	A list of fields to exclude from the output. TYPE: IncEx DEFAULT: None
by_alias	Whether to use the field's alias in the dictionary key if defined. TYPE: bool DEFAULT: False
exclude_unset	Whether to exclude fields that are unset or None from the output. TYPE: bool DEFAULT: False
exclude_defaults	Whether to exclude fields that are set to their default value from the output. TYPE: bool DEFAULT: False
exclude_none	Whether to exclude fields that have a value of None from the output. TYPE: bool DEFAULT: False
round_trip	Whether to enable serialization and deserialization round-trip support. TYPE: bool DEFAULT: False
warnings	Whether to log warnings when invalid fields are encountered. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary representation of the model.

model_dump_json

model_dump_json(
    *,
    indent: int | None = None,
    include: IncEx = None,
    exclude: IncEx = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: bool = True
) -> str

Usage docs: https://docs.pydantic.dev/2.4/concepts/serialization/#modelmodel_dump_json

Generates a JSON representation of the model using Pydantic's to_json method.

PARAMETER	DESCRIPTION
indent	Indentation to use in the JSON output. If None is passed, the output will be compact. TYPE: int | None DEFAULT: None
include	Field(s) to include in the JSON output. Can take either a string or set of strings. TYPE: IncEx DEFAULT: None
exclude	Field(s) to exclude from the JSON output. Can take either a string or set of strings. TYPE: IncEx DEFAULT: None
by_alias	Whether to serialize using field aliases. TYPE: bool DEFAULT: False
exclude_unset	Whether to exclude fields that have not been explicitly set. TYPE: bool DEFAULT: False
exclude_defaults	Whether to exclude fields that have the default value. TYPE: bool DEFAULT: False
exclude_none	Whether to exclude fields that have a value of None. TYPE: bool DEFAULT: False
round_trip	Whether to use serialization/deserialization between JSON and class instance. TYPE: bool DEFAULT: False
warnings	Whether to show any warnings that occurred during serialization. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
str	A JSON string representation of the model.

ConflictError

ConflictError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[409]

status_code class-attribute instance-attribute

status_code: Literal[409] = 409

InternalServerError

InternalServerError(
    message: str, *, response: Response, body: object | None
)

NotFoundError

NotFoundError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[404]

status_code class-attribute instance-attribute

status_code: Literal[404] = 404

NotGiven

A sentinel singleton class used to distinguish omitted keyword arguments from those passed in with the value None (which may have different behavior).

For example:

def get(timeout: Union[int, NotGiven, None] = NotGiven()) -> Response:
    ...


get(timeout=1)  # 1s timeout
get(timeout=None)  # No timeout
get()  # Default timeout behavior, which may not be statically known at the method definition.

OpenAI

OpenAI(
    *,
    api_key: str | None = None,
    organization: str | None = None,
    base_url: str | URL | None = None,
    timeout: Union[
        float, Timeout, None, NotGiven
    ] = NOT_GIVEN,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: Client | None = None,
    _strict_response_validation: bool = False
)

Primary synchronous client interface for interacting with the services (resources) provided by the OpenAI API.

An instance of the OpenAI class is the top-level object you interact with to make synchronous calls to the OpenAI API. The client provides access to OpenAI's services, or resources, like text completion, chat, embeddings, image and audio processing, and managing the files used by these resources.

The API authenticates requests to its endpoints by validating your API key, which you provide to the OpenAI client object in one of two ways:

Set an environment variable named OPENAI_API_KEY that contains your API key and then instantiate the client without passing the api_key parameter. This is the preferred method.

Pass the api_key parameter explicitly when you instantiate the client object. Choose this method only if you're unwilling or unable to use a more secure method like setting the OPENAI_API_KEY environment variable.

Danger

To prevent unauthorized access to OpenAI services, securely manage credentials like your OpenAI API key.

Examples:

The following code snippets each create an instance of the OpenAI class ready to call the API. To interact with an OpenAI service (a resource in the API), you access the appropriate attribute on the initialized client object and call the the methods provided by that resource.

• Create client using inferred API key ⁠— The API key is obtained by the OpenAI client automatically from the OPENAI_API_KEY environment variable if you omit the api_key constructor argument.

  from openai import OpenAI
  
  # Instantiate the client with NO 'api_key' param so the client will
  # read the OPENAI_API_KEY variable from the environment automatically
  client = OpenAI()
  

• Create client using explicit API key ⁠— Passing the API key explicitly directs the OpenAI client to use that key instead of the OPENAI_API_KEY environment variable (if set).

  This instantiation method can pose an increased security risk. For example, by instantiating the client this way in your code, it's easier to accidentally commit your API key to version control, which you should never do.

  from openai import OpenAI
  
  # !!! USE WITH CAUTION !!!
  
  # Instantiate the client and pass the API key explicitly
  client = OpenAI(api_key='your_api_key_here')
  

PARAMETER	DESCRIPTION
api_key	The API key used for authenticating requests to OpenAI. If not provided, the client attempts to retrieve the API key from the OPENAI_API_KEY environment variable. Defaults to None. TYPE: str | None DEFAULT: None
organization	The ID of the organization under which the API calls are made. This is optional and typically used for OpenAI services that require organization-level access control. If not provided, the client attempts to retrieve the organization ID from the OPENAI_ORG_ID environment variable. Defaults to None. TYPE: str | None DEFAULT: None
base_url	The base URL for the OpenAI API. This allows for custom API endpoints like those used for testing or specific API versions. If not provided, defaults to the official OpenAI API URL. TYPE: str | URL | None DEFAULT: None
timeout	The timeout for API requests. This can be specified as a float representing seconds, a httpx.Timeout object for fine-grained control, or None to use the default timeout. Defaults to NOT_GIVEN, which utilizes the httpx default timeout settings. TYPE: Union[float, Timeout, None, NotGiven] DEFAULT: NOT_GIVEN
max_retries	The maximum number of retries for failed requests. This can help handle transient network issues or rate limit errors gracefully. Defaults to a predefined constant DEFAULT_MAX_RETRIES. TYPE: int DEFAULT: DEFAULT_MAX_RETRIES
default_headers	Default headers to include with every request. This can be used to set global headers like User-Agent or custom headers required for integration. Defaults to None. TYPE: Mapping[str, str] | None DEFAULT: None
default_query	Default query parameters to include with every request. This is useful for setting global parameters that should be included in all API calls. Defaults to None. TYPE: Mapping[str, object] | None DEFAULT: None
http_client	An instance of httpx.Client to be used for making HTTP requests. This allows for custom configuration of the HTTP client, like setting proxies or client-side SSL certificates. If not provided, a default httpx.Client instance is used. Defaults to None. TYPE: Client | None DEFAULT: None
_strict_response_validation	Enables or disables strict validation of API responses against the expected schema. This is primarily used for development and debugging purposes to ensure the API responses match the expected format. Note that this argument may be removed or changed in future releases. Defaults to False. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
OpenAIError	If neither the api_key is provided nor the OPENAI_API_KEY environment variable is set, indicating that the client's requests to the OpenAI API would fail authentication.

METHOD	DESCRIPTION
copy	Create a new client instance re-using the same options given to the current client with optional overriding.

ATTRIBUTE	DESCRIPTION
api_key	TYPE: str
audio	TYPE: Audio
auth_headers	TYPE: dict[str, str]
beta	TYPE: Beta
chat	TYPE: Chat
completions	TYPE: Completions
default_headers	TYPE: dict[str, str | Omit]
embeddings	TYPE: Embeddings
files	TYPE: Files
fine_tuning	TYPE: FineTuning
images	TYPE: Images
models	TYPE: Models
moderations	TYPE: Moderations
organization	TYPE: str | None
qs	TYPE: Querystring
with_options
with_raw_response	TYPE: OpenAIWithRawResponse
with_streaming_response	TYPE: OpenAIWithStreamedResponse

api_key instance-attribute

api_key: str = api_key

audio instance-attribute

audio: Audio = Audio(self)

auth_headers property

auth_headers: dict[str, str]

beta instance-attribute

beta: Beta = Beta(self)

chat instance-attribute

chat: Chat = Chat(self)

completions instance-attribute

completions: Completions = Completions(self)

default_headers property

default_headers: dict[str, str | Omit]

embeddings instance-attribute

embeddings: Embeddings = Embeddings(self)

files instance-attribute

files: Files = Files(self)

fine_tuning instance-attribute

fine_tuning: FineTuning = FineTuning(self)

images instance-attribute

images: Images = Images(self)

models instance-attribute

models: Models = Models(self)

moderations instance-attribute

moderations: Moderations = Moderations(self)

organization instance-attribute

organization: str | None = organization

qs property

qs: Querystring

with_options class-attribute instance-attribute

with_options = copy

with_raw_response instance-attribute

with_raw_response: OpenAIWithRawResponse = (
    OpenAIWithRawResponse(self)
)

with_streaming_response instance-attribute

with_streaming_response: OpenAIWithStreamedResponse = (
    OpenAIWithStreamedResponse(self)
)

copy

copy(
    *,
    api_key: str | None = None,
    organization: str | None = None,
    base_url: str | URL | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
    http_client: Client | None = None,
    max_retries: int | NotGiven = NOT_GIVEN,
    default_headers: Mapping[str, str] | None = None,
    set_default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    set_default_query: Mapping[str, object] | None = None,
    _extra_kwargs: Mapping[str, Any] = {}
) -> Self

Create a new client instance re-using the same options given to the current client with optional overriding.

OpenAIError

PermissionDeniedError

PermissionDeniedError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[403]

status_code class-attribute instance-attribute

status_code: Literal[403] = 403

RateLimitError

RateLimitError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[429]

status_code class-attribute instance-attribute

status_code: Literal[429] = 429

RequestOptions

ATTRIBUTE	DESCRIPTION
extra_json	TYPE: AnyMapping
headers	TYPE: Headers
idempotency_key	TYPE: str
max_retries	TYPE: int
params	TYPE: Query
timeout	TYPE: float | Timeout | None

extra_json instance-attribute

extra_json: AnyMapping

headers instance-attribute

headers: Headers

idempotency_key instance-attribute

idempotency_key: str

max_retries instance-attribute

max_retries: int

params instance-attribute

params: Query

timeout instance-attribute

timeout: float | Timeout | None

Stream

Stream(
    *, cast_to: type[_T], response: Response, client: OpenAI
)

Provides the core interface to iterate over a synchronous stream response.

METHOD	DESCRIPTION
close	Close the response and release the connection.

ATTRIBUTE	DESCRIPTION
response	TYPE: Response

response instance-attribute

response: Response = response

close

close() -> None

Close the response and release the connection.

Automatically called if the response body is read to completion.

UnprocessableEntityError

UnprocessableEntityError(
    message: str, *, response: Response, body: object | None
)

ATTRIBUTE	DESCRIPTION
status_code	TYPE: Literal[422]

status_code class-attribute instance-attribute

status_code: Literal[422] = 422

file_from_path

file_from_path(path: str) -> FileTypes