# openai/openai-python architecture

> Architecture diagram of the GitHub repository openai/openai-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-python
- Repository: https://github.com/openai/openai-python

## Overview

OpenAI Python API library is a typed sync/async SDK: an application configures a client, calls a resource method, and receives parsed or streamed API results. The graph preserves documented Responses, Chat Completions, vision, audio, realtime, administration, and webhook capabilities, plus client transport, authentication, and response handling. Some feature implementations are represented by their exact resource directories because their individual source files were not sampled; edges are limited to README or source-index evidence.

Main entry points: [`src/openai/_client.py`](https://github.com/openai/openai-python/blob/main/src/openai/_client.py) (Sync and async clients), [`src/openai/_base_client.py`](https://github.com/openai/openai-python/blob/main/src/openai/_base_client.py) (HTTP request engine), [`src/openai/resources`](https://github.com/openai/openai-python/tree/main/src/openai/resources) (Other API resources), [`src/openai/_legacy_response.py`](https://github.com/openai/openai-python/blob/main/src/openai/_legacy_response.py) (Legacy response wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client and transport"]
  node_client["Sync and async clients<br/>[_client.py]"]
  node_auth["Authentication hooks<br/>[_client_auth.py]"]
  node_transport["HTTP request engine<br/>[_base_client.py]"]
  node_httpx["HTTPX2 client<br/>[_httpx2.py]"]
end

subgraph group_api["API resources"]
  node_responses["Responses API"]
  node_chat["Chat Completions"]
  node_other_api["Other API resources"]
  node_admin["Administration API"]
end

subgraph group_features["Specialized capabilities"]
  node_audio["Audio API"]
  node_realtime["Realtime API"]
  node_beta["Beta agents and tools"]
  node_webhooks["Webhook operations<br/>[webhooks.py]"]
end

subgraph group_results["Responses and types"]
  node_pagination["Pagination<br/>[pagination.py]"]
  node_response["Parsed and raw responses<br/>[_response.py]"]
  node_legacy_response["Legacy response wrappers"]
  node_streaming["Server-sent streaming<br/>[_streaming.py]"]
  node_models["Typed models<br/>[_models.py]"]
  node_exceptions["API exceptions<br/>[_exceptions.py]"]
end

node_application(("Python application"))

node_application -->|"configures and calls"| node_client
node_client -->|"configures authentication"| node_auth
node_client -->|"uses request engine"| node_transport
node_transport -->|"sends HTTP"| node_httpx
node_application -->|"calls Responses API"| node_responses
node_application -->|"calls Chat API"| node_chat
node_client -->|"exposes resource"| node_responses
node_client -->|"exposes resource"| node_chat
node_client -->|"exposes resources"| node_other_api
node_client -->|"exposes resources"| node_admin
node_client -->|"exposes resources"| node_audio
node_client -->|"exposes resources"| node_realtime
node_client -->|"exposes resources"| node_beta
node_client -->|"exposes resources"| node_webhooks
node_other_api -->|"uses pagination"| node_pagination
node_other_api -->|"wraps raw results"| node_legacy_response
node_transport -->|"builds legacy result"| node_legacy_response
node_response -->|"parses results"| node_models
node_legacy_response -->|"parses results"| node_models
node_transport -->|"creates streams"| node_streaming
node_streaming -->|"raises API errors"| node_exceptions
node_client -->|"maps status errors"| node_exceptions

click node_client "https://github.com/openai/openai-python/blob/main/src/openai/_client.py"
click node_auth "https://github.com/openai/openai-python/blob/main/src/openai/lib/_client_auth.py"
click node_transport "https://github.com/openai/openai-python/blob/main/src/openai/_base_client.py"
click node_httpx "https://github.com/openai/openai-python/blob/main/src/openai/_httpx2.py"
click node_responses "https://github.com/openai/openai-python/tree/main/src/openai/resources/responses"
click node_chat "https://github.com/openai/openai-python/tree/main/src/openai/resources/chat"
click node_other_api "https://github.com/openai/openai-python/tree/main/src/openai/resources"
click node_admin "https://github.com/openai/openai-python/tree/main/src/openai/resources/admin"
click node_audio "https://github.com/openai/openai-python/tree/main/src/openai/resources/audio"
click node_realtime "https://github.com/openai/openai-python/tree/main/src/openai/resources/realtime"
click node_beta "https://github.com/openai/openai-python/tree/main/src/openai/resources/beta"
click node_webhooks "https://github.com/openai/openai-python/blob/main/src/openai/resources/webhooks/webhooks.py"
click node_pagination "https://github.com/openai/openai-python/blob/main/src/openai/pagination.py"
click node_response "https://github.com/openai/openai-python/blob/main/src/openai/_response.py"
click node_legacy_response "https://github.com/openai/openai-python/blob/main/src/openai/_legacy_response.py"
click node_streaming "https://github.com/openai/openai-python/blob/main/src/openai/_streaming.py"
click node_models "https://github.com/openai/openai-python/blob/main/src/openai/_models.py"
click node_exceptions "https://github.com/openai/openai-python/blob/main/src/openai/_exceptions.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_auth,node_transport,node_httpx toneBlue
class node_responses,node_chat,node_other_api,node_admin toneAmber
class node_audio,node_realtime,node_beta,node_webhooks toneMint
class node_pagination,node_response,node_legacy_response,node_streaming,node_models,node_exceptions toneRose
class node_application toneIndigo
```

## Components

### Client and transport

- [Sync and async clients](https://github.com/openai/openai-python/blob/main/src/openai/_client.py): `src/openai/_client.py`
- [Authentication hooks](https://github.com/openai/openai-python/blob/main/src/openai/lib/_client_auth.py): `src/openai/lib/_client_auth.py`
- [HTTP request engine](https://github.com/openai/openai-python/blob/main/src/openai/_base_client.py): `src/openai/_base_client.py`
- [HTTPX2 client](https://github.com/openai/openai-python/blob/main/src/openai/_httpx2.py): `src/openai/_httpx2.py`

### API resources

- [Responses API](https://github.com/openai/openai-python/tree/main/src/openai/resources/responses): `src/openai/resources/responses`
- [Chat Completions](https://github.com/openai/openai-python/tree/main/src/openai/resources/chat): `src/openai/resources/chat`
- [Other API resources](https://github.com/openai/openai-python/tree/main/src/openai/resources): `src/openai/resources`
- [Administration API](https://github.com/openai/openai-python/tree/main/src/openai/resources/admin): `src/openai/resources/admin`

### Specialized capabilities

- [Audio API](https://github.com/openai/openai-python/tree/main/src/openai/resources/audio): `src/openai/resources/audio`
- [Realtime API](https://github.com/openai/openai-python/tree/main/src/openai/resources/realtime): `src/openai/resources/realtime`
- [Beta agents and tools](https://github.com/openai/openai-python/tree/main/src/openai/resources/beta): `src/openai/resources/beta`
- [Webhook operations](https://github.com/openai/openai-python/blob/main/src/openai/resources/webhooks/webhooks.py): `src/openai/resources/webhooks/webhooks.py`

### Responses and types

- [Pagination](https://github.com/openai/openai-python/blob/main/src/openai/pagination.py): `src/openai/pagination.py`
- [Parsed and raw responses](https://github.com/openai/openai-python/blob/main/src/openai/_response.py): `src/openai/_response.py`
- [Legacy response wrappers](https://github.com/openai/openai-python/blob/main/src/openai/_legacy_response.py): `src/openai/_legacy_response.py`
- [Server-sent streaming](https://github.com/openai/openai-python/blob/main/src/openai/_streaming.py): `src/openai/_streaming.py`
- [Typed models](https://github.com/openai/openai-python/blob/main/src/openai/_models.py): `src/openai/_models.py`
- [API exceptions](https://github.com/openai/openai-python/blob/main/src/openai/_exceptions.py): `src/openai/_exceptions.py`

### Other components

- **Python application**

## Connections

- Python application → Sync and async clients: configures and calls
- Sync and async clients → Authentication hooks: configures authentication (evidence: `src/openai/_client.py`)
- Sync and async clients → HTTP request engine: uses request engine (evidence: `src/openai/_client.py`)
- HTTP request engine → HTTPX2 client: sends HTTP (evidence: `src/openai/_base_client.py`)
- Python application → Responses API: calls Responses API
- Python application → Chat Completions: calls Chat API
- Sync and async clients → Responses API: exposes resource (evidence: `src/openai/_client.py`)
- Sync and async clients → Chat Completions: exposes resource (evidence: `src/openai/_client.py`)
- Sync and async clients → Other API resources: exposes resources (evidence: `src/openai/_client.py`)
- Sync and async clients → Administration API: exposes resources (evidence: `src/openai/_client.py`)
- Sync and async clients → Audio API: exposes resources (evidence: `src/openai/_client.py`)
- Sync and async clients → Realtime API: exposes resources (evidence: `src/openai/_client.py`)
- Sync and async clients → Beta agents and tools: exposes resources (evidence: `src/openai/_client.py`)
- Sync and async clients → Webhook operations: exposes resources (evidence: `src/openai/_client.py`)
- Other API resources → Pagination: uses pagination (evidence: `src/openai/resources/admin/organization/external_storage.py`)
- Other API resources → Legacy response wrappers: wraps raw results (evidence: `src/openai/resources/admin/organization/external_storage.py`)
- HTTP request engine → Legacy response wrappers: builds legacy result (evidence: `src/openai/_base_client.py`)
- Parsed and raw responses → Typed models: parses results (evidence: `src/openai/_response.py`)
- Legacy response wrappers → Typed models: parses results (evidence: `src/openai/_legacy_response.py`)
- HTTP request engine → Server-sent streaming: creates streams (evidence: `src/openai/_base_client.py`)
- Server-sent streaming → API exceptions: raises API errors (evidence: `src/openai/_streaming.py`)
- Sync and async clients → API exceptions: maps status errors (evidence: `src/openai/_client.py`)
