pip install git+https://github.com/odysseyml/odyssey-python.git

uv pip install git+https://github.com/odysseyml/odyssey-python.git

import asyncio
from odyssey import Odyssey, OdysseyAuthError, OdysseyConnectionError

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        await client.connect(
            on_video_frame=lambda frame: print(f"Frame: {frame.width}x{frame.height}"),
            on_stream_started=lambda stream_id: print(f"Stream started: {stream_id}"),
        )
        await client.start_stream("A cat", portrait=True)
        await client.interact("Pet the cat")
        await client.end_stream()
    except OdysseyAuthError:
        print("Invalid API key")
    except OdysseyConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()

asyncio.run(main())

import asyncio
import cv2
from odyssey import Odyssey, VideoFrame, OdysseyConnectionError

current_frame = None

def on_frame(frame: VideoFrame) -> None:
    global current_frame
    # Convert RGB to BGR for OpenCV
    current_frame = cv2.cvtColor(frame.data, cv2.COLOR_RGB2BGR)

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    try:
        await client.connect(on_video_frame=on_frame)
        await client.start_stream("A serene beach at sunset")

        # Display loop
        while True:
            if current_frame is not None:
                cv2.imshow("Odyssey", current_frame)
            if cv2.waitKey(1) & 0xFF == ord("q"):
                break

        await client.end_stream()
    except OdysseyConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()
        cv2.destroyAllWindows()

asyncio.run(main())

# From file path
await client.start_stream(
    prompt="The robot starts dancing",
    portrait=False,
    image="/path/to/robot.jpg",
)

# From PIL Image
from PIL import Image
img = Image.open("robot.jpg")
await client.start_stream(prompt="Robot dancing", image=img)

# From numpy array (e.g., OpenCV frame)
frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
await client.start_stream(prompt="Animate this", image=frame_rgb)

from odyssey import Odyssey, BroadcastInfo

def on_broadcast_ready(info: BroadcastInfo) -> None:
    print(f"WebRTC: {info.webrtc_url}")
    print(f"HLS: {info.hls_url}")

await client.connect(on_broadcast_ready=on_broadcast_ready)
await client.start_stream("A sunset", broadcast=True)

import asyncio
from odyssey import Odyssey, SimulationJobStatus

async def main():
    client = Odyssey(api_key="ody_your_api_key_here")

    # Submit a simulation job
    job = await client.simulate(
        script=[
            {"timestamp_ms": 0, "start": {"prompt": "A cat sleeping on a couch"}},
            {"timestamp_ms": 5000, "interact": {"prompt": "The cat wakes up"}},
            {"timestamp_ms": 10000, "end": {}},
        ]
    )
    print(f"Job submitted: {job.job_id}")

    # Poll for completion
    while True:
        status = await client.get_simulate_status(job.job_id)
        print(f"Status: {status.status.value}")

        if status.status == SimulationJobStatus.COMPLETED:
            print(f"Video URL: {status.streams[0].video_url}")
            break
        elif status.status in (SimulationJobStatus.FAILED, SimulationJobStatus.CANCELLED):
            print(f"Job failed: {status.error_message}")
            break

        await asyncio.sleep(5)

    await client.disconnect()

asyncio.run(main())

@dataclass
class VideoFrame:
    data: np.ndarray      # RGB uint8 array, shape (H, W, 3)
    width: int
    height: int
    timestamp_ms: int

@dataclass
class BroadcastInfo:
    hls_url: str | None           # HLS playback URL (may be None if HLS disabled)
    webrtc_url: str | None        # WebRTC/WHEP playback URL
    spectator_token: str | None   # Authentication token for spectator access