simulate

Simulation Example

Submit and manage asynchronous video generation jobs using YAML config files.

Setup

1. Install the example dependencies:

cd interactive-client/python
uv sync --extra examples

2. Configure your API key (choose one method):

# Option A: Create a .env.local file (recommended)
echo 'ODYSSEY_API_KEY=ody_your_key_here' > .env.local

# Option B: Export environment variable
export ODYSSEY_API_KEY="ody_your_api_key_here"

Usage

# Submit a simulation job
uv run python examples/simulate/main.py submit examples/simulate/examples/cat_nap.yaml

# Test different image input formats (path, pil, bytes, numpy)
uv run python examples/simulate/main.py submit examples/simulate/examples/robot_dance.yaml --image-format pil

# Check job status
uv run python examples/simulate/main.py status <job_id>

# List your jobs
uv run python examples/simulate/main.py list
uv run python examples/simulate/main.py list --active  # Only pending/processing

# Wait for completion and download
uv run python examples/simulate/main.py wait <job_id> --output video.mp4

# Cancel a pending job
uv run python examples/simulate/main.py cancel <job_id>

Example Configs

File	Description
examples/simple.yaml	Minimal - just a prompt, no interactions
examples/cat_nap.yaml	Text-to-video with timed interactions
examples/garden.yaml	Auto-spaced interactions (simple string list)
examples/robot_dance.yaml	Image-to-video (requires your own image)

YAML Config Format

# Required
prompt: "Description of the scene"

# Optional (defaults shown)
portrait: true          # true = 704x1280, false = 1280x704
duration: 10s           # Supports: 10s, 1.5m, 5000ms, or just 10 (seconds)
image: ./path/to/img.jpg  # For image-to-video (i2v)

# Interactions - two formats supported:

# Format 1: Timed interactions
interactions:
  - time: 3s
    prompt: "Something happens"
  - time: 6s
    prompt: "Something else happens"

# Format 2: Simple strings (auto-spaced evenly)
interactions:
  - "First thing happens"
  - "Second thing happens"

Time Formats

The duration and time fields support multiple formats:

Format	Example	Meaning
Seconds	10s or 10	10 seconds
Minutes	1.5m	1.5 minutes (90 seconds)
Milliseconds	5000ms	5000 milliseconds