Medeo Video Generator Skill

Generate AI videos from text. Medeo is an AI video agent that handles full storylines, multi-scene narratives, and screenplays in a single call — shot composition, transitions, pacing, and music are all automatic.

⚠️ Do NOT split stories into multiple calls. Pass the entire screenplay in one

--message

.

0. Pre-Flight Check (MANDATORY — run before anything else)

Before running any command, check if API key is configured:

python3 {baseDir}/scripts/medeo_video.py config 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('ok' if d.get('apiKey') else 'missing')"

• Output

  ok

  → proceed normally
• Output

  missing

  (or command fails) → stop immediately, do NOT run any other commands. Send the setup message using the channel-appropriate method:

Feishu — use Feishu API directly (NOT

message

import json, urllib.request
cfg = json.loads(open("/home/ec2-user/.openclaw/openclaw.json").read())
feishu = cfg["channels"]["feishu"]["accounts"]["default"]
token = json.loads(urllib.request.urlopen(urllib.request.Request(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    data=json.dumps({"app_id": feishu["appId"], "app_secret": feishu["appSecret"]}).encode(),
    headers={"Content-Type": "application/json"}
)).read())["tenant_access_token"]
card = {
    "config": {"wide_screen_mode": True},
    "header": {"title": {"tag": "plain_text", "content": "🎬 Video Generation — API Key Required"}, "template": "blue"},
    "elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "You need a **Medeo API Key** to generate videos.\n\n**Steps:**\n1. Go to https://medeo.app/dev/apikey\n   - No account? You'll be guided to sign up. The key appears after login.\n2. Copy the key (starts with `mk_`) and send it back to me.\n\nOnce I have it, I'll configure everything for you."}}],
}
urllib.request.urlopen(urllib.request.Request(
    "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
    data=json.dumps({"receive_id": "<USER_OPEN_ID>", "msg_type": "interactive", "content": json.dumps(card)}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
))

Telegram / Discord / Other channels — send plain text via

message

🎬 Video Generation — API Key Required

Steps:
1. Go to https://medeo.app/dev/apikey (sign up if needed — the key appears after login)
2. Copy the key (starts with mk_) and send it back to me

Once I have it, I'll configure everything for you.

Once they provide the key:

python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."

1. First-Time Setup

If no API Key is configured, the script outputs

"setup_required": true

1. Send the user this exact link: https://medeo.app/dev/apikey (this page auto-prompts registration if not logged in, then shows the API key)
2. Once they provide the key:

   python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."

2. Generate a Video (5-30 min, always async)

Users only need to know 3 ways to generate a video:

1. Send text → generate video
2. Send text + upload image → generate video using their image
3. Send text + image URL → generate video using the URL image

The agent handles everything else silently.

IMPORTANT: Before spawning the generation task, immediately reply to the user with an acknowledgment like: "🎬 Starting video generation — I'll send you the result in about 5–10 minutes." Do NOT wait in silence. The user should know their request was received.

Usage 1: Text only

python3 {baseDir}/scripts/medeo_video.py spawn-task \
  --message "user's video description" \
  --deliver-to "oc_xxx" \
  --deliver-channel "feishu"

Usage 2: Text + uploaded image (user sends image in chat)

# First: upload-file to get media_id (see Section 3)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
  --message "user's video description" \
  --media-ids "media_01..." \
  --asset-sources my_uploaded_assets \
  --deliver-to "oc_xxx" \
  --deliver-channel "feishu"

Usage 3: Text + image URL

python3 {baseDir}/scripts/medeo_video.py spawn-task \
  --message "user's video description" \
  --media-urls "https://example.com/photo.jpg" \
  --asset-sources my_uploaded_assets \
  --deliver-to "oc_xxx" \
  --deliver-channel "feishu"

Agent auto-behavior: When the user provides images (Usage 2 or 3), always pass

--asset-sources my_uploaded_assets

so Medeo uses their images instead of generating new ones. The user does not need to know this flag exists.

Internal Parameters (agent use only — never expose to users)

These are handled automatically by the agent. Do NOT mention them to users or ask users to provide them.

--voice-id "voice_01..."

--video-style-id "style_01..."

--asset-sources

my_uploaded_assets

--recipe-id "recipe_01..."

--aspect-ratio "9:16"

16:9

--duration-ms 30000

--no-render

Delivery Target (

--deliver-to

)

This is critical — determines where the generated video gets sent.

--deliver-to

chat_id

oc_

conversation_label

chat_id

chat:

chat:oc_xxx

oc_xxx

oc_158fd3e54407cbe170697c6c954bd4f2

open_id

ou_

sender_id

user:

ou_f7f458f4d7b4ff49ec1b8de22a1e3206

chat_id

-1001234567890

channel_id

1234567890123456

How to determine group vs private on Feishu:

• Check

  is_group_chat

  in the inbound metadata
• If

  true

  → use

  conversation_label

  /

  chat_id

  (the

  oc_

  value)
• If

  false

  → use

  sender_id

  (the

  ou_

  value)

Step 2: Use

sessions_spawn

label: "medeo: <brief>"

runTimeoutSeconds: 2400

3. Upload Assets

3a. From URL (image already has a public URL)

python3 {baseDir}/scripts/medeo_video.py upload \
  --url "https://example.com/photo.jpg" \
  --project-id "project_01..."          # optional: associate media with existing project
  --no-wait                             # optional: return job_id immediately without polling

3b. From IM attachment (user sends image directly) ← NEW

Use

upload-file

Trigger: Only when the user explicitly requests video generation AND sends an image attachment in the same message (e.g. "make a video with this photo"). Do NOT auto-upload on every image message — other skills or conversations may involve images unrelated to video generation.

# From local file (downloaded by OpenClaw from attachment)
python3 {baseDir}/scripts/medeo_video.py upload-file \
  --file /tmp/user_photo.jpg

# From direct URL (Discord CDN, etc.)
python3 {baseDir}/scripts/medeo_video.py upload-file \
  --url "https://cdn.discordapp.com/attachments/..."

# From Telegram (file_id from message.photo[-1].file_id)
# TELEGRAM_BOT_TOKEN must be set as env var — never pass as CLI arg (ps aux leaks it)
TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/medeo_video.py upload-file \
  --telegram-file-id "AgACAgIAAxk..."

# From Feishu (message_id + image_key from message content)
python3 {baseDir}/scripts/medeo_video.py upload-file \
  --feishu-message-id "om_xxx" \
  --feishu-image-key "img_v3_xxx" \
  --feishu-app-token "$FEISHU_APP_TOKEN"

Output:

{"media_id": "media_01...", "filename": "photo.jpg"}

Then pass

media_id

python3 {baseDir}/scripts/medeo_video.py spawn-task \
  --message "Create a video featuring this person" \
  --media-ids "media_01..."

Platform-Specific Image Extraction Guide

upload-file

message.photo[-1].file_id

--telegram-file-id

message.attachments[0].url

--url

message_id

image_key

--feishu-message-id

--feishu-image-key

/tmp

--file

--url

Note: Discord attachment URLs are public CDN links —

--url

3c. Inline in generate pipeline

# URL-based (existing behavior)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
  --message "Product showcase for this sneaker" \
  --media-urls "https://example.com/front.jpg" "https://example.com/side.jpg"

Supports

.jpg

.png

.webp

.mp4

.mov

.gif

3d. Check Upload Status

After

upload

upload-file

python3 {baseDir}/scripts/medeo_video.py upload-status --job-id "job_01..."

Returns media status (

processing

completed

failed

media_id

4. Low-Level Pipeline Commands (agent internal — never expose to users)

These are for agent debugging or manual intervention only. Users should never see these commands.

Pipeline flow:
  spawn-task (recommended, async)
      └── generate (blocking, same pipeline)
              ├── upload (if --media-urls)
              ├── compose → compose-status (poll)
              └── render → render-status (poll)

generate

compose

--message

--media-ids

--recipe-id

compose-status

--task-id "task_01..."

render

--project-id "project_01..."

render-status

--job-id "render_01..."

upload-status

--job-id "job_01..."

All commands support

--no-wait

5. Browse Recipes

python3 {baseDir}/scripts/medeo_video.py recipes              # list templates
python3 {baseDir}/scripts/medeo_video.py recipes --cursor <c>  # paginate

Use in generation:

--recipe-id "recipe_01..."

6. Quick Commands Reference (for agent, not user-facing)

recipes

last-job

history

config

config-init --api-key "mk_..."

upload --url "URL"

upload-file --file PATH

upload-file --url "URL"

upload-file --telegram-file-id "..."

upload-file --feishu-image-key "..."

upload-status --job-id "..."

compose-status --task-id "..."

render-status --job-id "..."

7. Key Rules

1. Always async —

   spawn-task

   +

   sessions_spawn

   for generation
2. One call for stories — full storylines in one

   --message

   , never split
3. Insufficient credits — share recharge link from error output
4. IM image upload — Only upload images when the user explicitly asks for video generation with that image. Do NOT auto-upload every image message (user may have other skills installed). When triggered: run

   upload-file

   first → get

   media_id

   → pass to generation via

   --media-ids

   . Never ask the user for a URL if they already sent the image.
5. IM-native delivery — After generation, deliver the video using the IM channel's native method (not just a URL). Each channel has a dedicated delivery script:
   • Feishu:

     python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/result.mp4 --to "oc_xxx_or_ou_xxx" --cover-url "<thumbnail_url>" --duration <ms>

     (use

     oc_

     chat_id for group chats,

     ou_

     open_id for private chats;

     chat:oc_xxx

     and

     user:ou_xxx

     prefixed forms are also accepted)
   • Telegram: Download video, then send via

     telegram_send_video.py

     (token from env only):

     curl -sL -o /tmp/medeo_result.mp4 "<video_url>"
     TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/telegram_send_video.py \
       --video /tmp/medeo_result.mp4 \
       --to "<chat_id>" \
       --cover-url "<thumbnail_url>" \
       --duration <seconds> \
       --caption "🎬 Video ready!"
     

   • Discord: Use the

     message

     tool directly — download the video to

     /tmp/result.mp4

     via

     curl -sL -o /tmp/result.mp4 "<video_url>"

     , then call

     message(action="send", channel="discord", target="<channel_id>", message="🎬 Video ready!", filePath="/tmp/result.mp4")

     . For files >25 MB, send

     video_url

     as a plain link instead.
   • WhatsApp / Signal / Other: Use the

     message

     tool with

     media

     parameter, or share

     video_url

     as a link if native sending is unavailable.
   • Cover image URL: The generate output JSON includes

     thumbnail_url

     — the API always returns this field. Constructed as

     {ossBaseUrl}/{thumbnail_relative_path}

     (e.g.

     https://oss.prd.medeo.app/assets/medias/media_xxx.png

     ).
   • Video URL: Same pattern —

     {ossBaseUrl}/{video_relative_path}

     (e.g.

     https://oss.prd.medeo.app/exported_video/v_xxx

     ).
   • Security: Never pass bot tokens as CLI args (visible in

     ps

     ). Always use env vars:

     TELEGRAM_BOT_TOKEN

     ,

     DISCORD_BOT_TOKEN

     .
6. Timeline completion — Medeo's backend is an AI agent. Generated images/videos must be added to the Timeline to trigger task completion and rendering. Always append to your prompt: "Add the generated video/image to the Timeline."

8. Error Handling

setup_required: true

upload_prep_rejected

s3_put_failed

upload-file --url

9. Reference Docs

• docs/recipes.md — Full recipe browsing and pagination
• docs/assets-upload.md — All upload paths (URL, local file, IM attachments), platform-specific guides,

  upload

  vs

  upload-file

  comparison
• docs/feishu-send.md — Sending generated video via Feishu (cover image, duration, compression)
• docs/multi-platform.md — Multi-platform video delivery (Feishu, Telegram, Discord, WhatsApp)

10. Data Storage

All data in

~/.openclaw/workspace/medeo-video/

config.json

last_job.json

history/

11. Security Notes

• API key resolution: env var

  MEDEO_API_KEY

  →

  config.json

  → built-in defaults. No legacy system-level files are read.
• Feishu delivery:

  feishu_send_video.py

  reads

  appId

  +

  appSecret

  from local

  ~/.openclaw/openclaw.json

  to call Feishu Open API. Credentials stay local and are never transmitted beyond the Feishu API.
• Telegram delivery: Bot token is read from

  TELEGRAM_BOT_TOKEN

  env var only (never CLI args).
• No secrets in skill directory:

  config.json

  lives in the runtime data directory (

  ~/.openclaw/workspace/medeo-video/

  ), not in the skill source directory.