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
pip install git+https://github.com/odysseyml/odyssey-python.git
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
Odyssey Client
Main client class documentation
Recordings
Working with stream recordings
Simulate API
Async scripted video generation
Types
Python types and dataclasses
Examples
Complete usage examples