Environment:Openai Openai python Realtime WebSocket
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Realtime |
| Last Updated | 2026-02-15 10:00 GMT |
Overview
Optional WebSocket dependency environment for the OpenAI Realtime API, requiring the `websockets` package (>= 13, < 16).
Description
This environment extends the base Python 3.9+ environment with WebSocket support for the OpenAI Realtime API. The `websockets` library is an optional dependency that is only required when using the `client.beta.realtime.connect()` or `client.realtime.connect()` methods. It provides both synchronous and asynchronous WebSocket client connectivity for real-time audio/text conversations.
Usage
Use this environment when working with the Realtime Conversation workflow, including real-time voice interactions, session configuration, conversation item management, and server event processing. It is the mandatory prerequisite for the Realtime_Connect, Realtime_Session_Update, Realtime_Conversation_Item_Create, Realtime_Server_Events, and Realtime_Error_Event implementations.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows | Same as base SDK |
| Python | >= 3.9 | Same as base SDK |
| Network | WebSocket connectivity | Requires outbound WebSocket (wss://) connections to OpenAI API |
Dependencies
System Packages
No additional system packages required beyond the base SDK.
Python Packages
- `websockets` >= 13, < 16 — WebSocket client library (both sync and async)
- All base SDK dependencies (see Environment:Openai_Openai_python_Python_3_9_Plus)
Credentials
Same as base SDK:
- `OPENAI_API_KEY`: Required. OpenAI API key.
Quick Install
# Install SDK with realtime support
pip install openai[realtime]
# Or install websockets separately
pip install openai websockets>=13
Code Evidence
WebSocket import check from `resources/beta/realtime/realtime.py:355-358`:
try:
from websockets.asyncio.client import connect
except ImportError as exc:
raise OpenAIError("You need to install `openai[realtime]` to use this method") from exc
Optional dependency declaration from `pyproject.toml:50`:
realtime = ["websockets >= 13, < 16"]
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `OpenAIError: You need to install openai[realtime] to use this method` | `websockets` package not installed | `pip install openai[realtime]` |
| `ConnectionRefusedError` | WebSocket endpoint unreachable | Check network connectivity and firewall rules for wss:// connections |
Compatibility Notes
- WebSocket URL scheme: The SDK automatically converts `http://` and `https://` base URLs to `wss://` for WebSocket connections.
- Sync and async: Both synchronous (`websockets.sync.client.connect`) and asynchronous (`websockets.asyncio.client.connect`) clients are supported.
- Audio format: For `pcm16` audio over realtime connections, audio must be 16-bit PCM at 24kHz sample rate, single channel.