headless

Headless Example

Headless image-to-video generation using YAML config files. Runs without a display - connects, streams based on a script, and saves the server-rendered recording to a file.

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

# Run from YAML config
uv run python examples/headless/main.py run examples/headless/examples/robot_dance.yaml

# Override output file
uv run python examples/headless/main.py run examples/headless/examples/robot_dance.yaml --output my_video.mp4

YAML Config Format

# Required
image: ./robot.jpg          # Path to source image (relative to config file)

# Optional
prompt: "Robot dancing"     # Generation prompt (default: "")
portrait: false             # Orientation (default: true)
duration: 10s               # Stream duration (default: 10s)
output: video.mp4           # Output file (default: video.mp4)

# Optional: Timed interactions
interactions:
  - time: 3s
    prompt: "Robot does a spin"
  - time: 6s
    prompt: "Robot strikes a pose"

Time Format

Times can be specified as:

• 5s - seconds
• 1.5m - minutes
• 500ms - milliseconds
• 5 - raw number (treated as seconds)

Example Configs

File	Description
examples/robot_dance.yaml	Robot dancing with interactions (landscape)
examples/robot_wave.yaml	Robot waving hello (portrait)
examples/simple.yaml	Minimal example without interactions

How It Works

1. Parses the YAML config file
2. Connects to Odyssey via WebRTC
3. Starts an image-to-video stream
4. Sends interactions at the scheduled times
5. Ends the stream after the specified duration
6. Downloads the server-rendered H.264 video recording

The output video is downloaded from the server (not encoded locally), ensuring broad codec compatibility.