> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.api.odyssey.ml/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Complete API reference for the Odyssey Python client library.
The `odyssey` package provides an async Python client for interacting with Odyssey's audio-visual intelligence.
Requires Python 3.12+
| Feature | Minimum Version |
| ------------ | --------------- |
| Core SDK | `^1.0.0` |
| Recordings | `^1.0.0` |
| Simulate API | `^1.0.0` |
| Broadcast | `^1.1.0` |
## Installation
```bash pip theme={null}
pip install git+https://github.com/odysseyml/odyssey-python.git
```
```bash uv theme={null}
uv pip install git+https://github.com/odysseyml/odyssey-python.git
```
## API Summary
### Methods
| Signature | Description |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect(**handlers) -> None` | Connect to a streaming session (raises on failure) |
| `create_client_credentials() -> ClientCredentials` | Mint short-lived credentials for client-side connections *(v1.3.0+)* |
| `connect_with_credentials(credentials, **handlers) -> None` | Connect with pre-minted credentials (no API key required) *(v1.3.0+)* |
| `disconnect() -> None` | Disconnect and clean up resources |
| `start_stream(prompt, portrait?, image?, broadcast?) -> str` | Start an interactive stream. Supports broadcast=True to enable shared playback for spectators.
When enabled, playback details are delivered via the on\_broadcast\_ready callback |
| `interact(prompt) -> str` | Send a prompt to update the video |
| `end_stream() -> None` | End the current stream session |
| `get_recording(stream_id) -> Recording` | Get recording URLs for a stream |
| `list_stream_recordings(limit?, offset?) -> StreamRecordingsList` | List user's stream recordings |
| `simulate(script) -> SimulationJobInfo` | Create an async simulation job *(v1.0.0+)* |
| `get_simulate_status(id) -> SimulationJobDetail` | Get simulation job status *(v1.0.0+)* |
| `list_simulations(limit?, offset?) -> SimulationJobsList` | List simulation jobs *(v1.0.0+)* |
| `cancel_simulation(id) -> None` | Cancel a simulation job *(v1.0.0+)* |
| `connect_to_stream(webrtc_url?, spectator_token?, on_video_frame?, on_disconnected?, debug?) -> SpectatorConnection` | Connect as a spectator to an existing broadcast stream using WebRTC/WHEP.
Use this when you have the webrtc\_url and spectator\_token provided by the streamer via on\_broadcast\_ready.
*(v1.0.19+)* |
### Properties
| Property | Type | Description |
| -------------------- | ----------------------- | ------------------------------------------ |
| `is_connected` | `bool` | Whether connected and ready |
| `current_status` | `ConnectionStatus` | Current connection status |
| `current_session_id` | `str \| None` | Current session ID |
| `broadcast_info` | `BroadcastInfo \| None` | Contains latest broadcast playback details |
### Event Handlers
| Handler | Parameters | Description |
| -------------------------- | ------------------------------- | ------------------------------------------------------------------------------ |
| `on_connected` | - | WebRTC connection established |
| `on_disconnected` | - | Connection closed |
| `on_video_frame` | `frame: VideoFrame` | Video frame received |
| `on_stream_started` | `stream_id: str` | Interactive stream ready (stream\_id can be used for recordings) |
| `on_stream_ended` | - | Interactive stream ended |
| `on_interact_acknowledged` | `prompt: str` | Interaction processed |
| `on_stream_error` | `reason, message` | Stream error occurred |
| `on_error` | `error: Exception, fatal: bool` | General error |
| `on_status_change` | `status, message?` | Connection status changed |
| `on_broadcast_ready` | `info: BroadcastInfo` | Fired when broadcast playback details are available (only when broadcast=True) |
### Exceptions
| Exception | Description |
| ------------------------ | ----------------------------------------- |
| `OdysseyError` | Base exception for all Odyssey errors |
| `OdysseyAuthError` | Authentication failed (invalid API key) |
| `OdysseyConnectionError` | Connection failed (no streamers, timeout) |
| `OdysseyStreamError` | Stream operation failed |
## Next Steps
Main client class documentation
Working with stream recordings
Async scripted video generation
Python types and dataclasses
Complete usage examples