Send Video Message

Send Video Message

Send the user a video message where an AI avatar speaks your words — lip-synced with natural motion. Use this for async updates, code review walkthroughs, incident summaries, or anything that's better explained with a face than a wall of text.

Privacy & Data Handling

Setup

Get a Runway API Key

1. Go to dev.runwayml.com 2. Create an account and get an API key 3. Set it: export RUNWAY_API_SECRET=your_key

One-Time Setup: Create Your Avatar

Before generating videos, create a custom avatar (face image + Runway). You only need to do this once — the avatar ID is saved and reused for all future videos.

The voice is chosen later in generate_video.py, not at avatar creation.

Which face to use — follow this order

1. Default (no user preference): Use Openclaw Lobster 2 as referenceImage via setup_avatar.py --image-url (URL below). Do not use Runway’s built-in preset avatars (game-character, cat-character, etc.) as the first choice — those are only for the fallback in step 3. 2. User asked for a look: Pick another image from the list below, use an image URL they gave you, or run setup_avatar.py --description "..." to generate a face from text (slower; uses Runway text-to-image). 3. Fallback — urgent or you’re out of time: Skip setup_avatar and call generate_video.py with --preset-id "game-character" (or another Runway preset ID from the fallback list below). Faster, less distinctive than Lobster / list images.

Check first: If ~/.openclaw/runway-avatar.json already has an avatar_id (or you know one from a prior run), reuse it and skip to Generate a Video Message.

Step 1: Pick a face image (for custom avatar)

Use Openclaw Lobster 2 unless the user wants something else from this list (or their own URL):

Generate from text (when the user asks for a custom look and no URL fits) — setup_avatar.py --description "...". The image should be a character facing the camera directly, head and shoulders, centered. Be bold and creative:

Step 2: Create the avatar

Default — Openclaw Lobster 2:

uv run {baseDir}/scripts/setup_avatar.py \
  --name "Mochi" \
  --image-url "https://runway-static-assets.s3.us-east-1.amazonaws.com/calliope-demo/agent-avatars-presets/openclaw-lobster2.jpg"

Another character from the list above — same command as Lobster 2, only change --image-url to that preset’s URL.

Text description (generates the image) — when the user wants a custom generated look:

uv run {baseDir}/scripts/setup_avatar.py \
  --name "Mochi" \
  --description "A cute fluffy white cartoon creature with large expressive eyes, looking directly at the viewer, 3D animation style, head and shoulders, neutral background"

With your own image URL:

uv run {baseDir}/scripts/setup_avatar.py \
  --name "Mochi" \
  --image-url "https://example.com/avatar.jpg"

The setup script prints the avatar ID and saves it to ~/.openclaw/runway-avatar.json. Future generate_video.py calls use it automatically. Save the avatar ID — reuse it for all videos. Do NOT create a new avatar each time.

Generate a Video Message

Write what you want to say, pick a voice that matches your avatar image, and the avatar will speak it with lip-synced animation. Always pass --voice — choose one that fits the character's appearance (e.g. a female avatar should use a female voice, an authoritative-looking character should use a deeper voice).

uv run {baseDir}/scripts/generate_video.py \
  --text "Hey Alex — quick update on the deploy. Everything went through, all tests passing. The memory fix from your PR cut p99 latency by 40 percent. Nice work." \
  --voice "Maya"

Do not pass --preset-id when a custom avatar is already saved or you pass --avatar-id — that is the normal path after Lobster 2 / list / text setup.

Cropping for mobile & Telegram

Runway’s avatar video is wide (16:9). On phones that can look squished or awkward. Crop it to match the target app:

| Target | Flag | Resolution | Ratio | |--------|------|-----------|-------| | Telegram | --square | 1080×1080 | 1:1 | | Other mobile (WhatsApp, iMessage, etc.) | --vertical | 1080×1920 | 9:16 |

Both flags scale the frame up to cover the target area, then center-crop. They are mutually exclusive — pick one. Env vars work too: SEND_VIDEO_MESSAGE_SQUARE=1 or SEND_VIDEO_MESSAGE_VERTICAL=1.

Requires ffmpeg on the machine that runs the script (brew install ffmpeg on macOS).

Telegram (square):

uv run {baseDir}/scripts/generate_video.py \
  --text "Quick update — deploy is green, all tests passed." \
  --voice "Maya" \
  --square

WhatsApp / iMessage / other mobile (vertical):

uv run {baseDir}/scripts/generate_video.py \
  --text "Quick update — deploy is green, all tests passed." \
  --voice "Maya" \
  --vertical

Available TTS voices

Pass --voice to generate_video.py (default: Maya):

| ID | Gender | Style | Pitch | |----|--------|-------|-------| | Maya | Woman | Upbeat | Higher | | Arjun | Man | Clear | Middle | | Serene | Woman | Calm | Middle | | Bernard | Man | Authoritative | Lower | | Billy | Man | Casual | Middle | | Mark | Man | Neutral | Middle | | Clint | Man | Gravelly | Lower | | Mabel | Woman | Warm | Middle | | Chad | Man | Energetic | Middle | | Leslie | Woman | Friendly | Middle | | Eleanor | Woman | Mature | Middle | | Elias | Man | Smooth | Lower-middle | | Elliot | Man | Even | Middle | | Noah | Man | Relaxed | Lower-middle | | Rachel | Woman | Clear | Middle | | James | Man | Firm | Lower | | Katie | Woman | Bright | Higher | | Tom | Man | Casual | Middle | | Wanda | Woman | Warm | Middle | | Benjamin | Man | Professional | Lower-middle |

With a specific avatar ID (overrides saved default; still no --preset-id):

uv run {baseDir}/scripts/generate_video.py --text "Morning standup recap..." --avatar-id "550e8400-e29b-41d4-a716-446655440000" --voice "Maya"

Fallback — Runway preset avatar (only if no time)

Use only when you cannot run setup_avatar (deadline, user waiting, etc.). Prefer game-character as the preset. No Lobster / list image — Runway’s generic character.

uv run {baseDir}/scripts/generate_video.py \
  --text "Quick heads up about the deploy." \
  --preset-id "game-character" \
  --voice "Maya" \
  --vertical

Other preset IDs if needed: game-character-man, music-superstar, cat-character, influencer, tennis-coach, human-resource, fashion-designer, cooking-teacher

Script output

The script outputs: 1. Progress updates as it generates speech and video 2. Video saved: /tmp/runway-avatar-YYYY-MM-DD-HH-MM-SS.mp4 3. MEDIA: /tmp/runway-avatar-...mp4 — OpenClaw auto-attaches this to the user's chat

Do not read the video file back — just report the path and let OpenClaw handle delivery.

When to Use Video Messages

Use video messages for async communication that benefits from a face:

Use a video call (not a video message) for things that need real-time back-and-forth.

Complete Example: Deploy Notification

1. Agent detects a successful deploy 2. If no saved avatar: runs setup_avatar.py with Openclaw Lobster 2 --image-url (one-time) 3. Agent composes what to say: "Hey Alex — deploy went through. 3 PRs merged: the auth refactor, the cart fix, and your memory optimization. All tests green. P99 latency dropped 40 percent after your fix. Nice work." 4. Generates the video with the saved custom avatar (no --preset-id). Add --square for Telegram or --vertical for other mobile:

   uv run {baseDir}/scripts/generate_video.py --text "Hey Alex — deploy went through..." --voice "Maya" --square
   

Notes

Get a Runway API Key

1. Go to dev.runwayml.com 2. Create an account and get an API key 3. Set it: export RUNWAY_API_SECRET=your_key