¿Qué hace Habilidad de Generación de Videos Medeo?
Genera videos con IA a partir de texto. Medeo es un agente de video con IA que maneja historias completas, narrativas de múltiples escenas y guiones en una sola llamada: la composición de tomas, las transiciones, el ritmo y la música se automatizan por completo.
⚠️ NO dividas las historias en varias llamadas. Pasa el guion completo en un solo
--message.
0. Verificación Pre-Vuelo (OBLIGATORIO — ejecutar antes de cualquier otra cosa)
Antes de ejecutar cualquier comando, verifica si la clave API está configurada:
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')"
- Salida
ok→ procede normalmente - Salida
missing(o el comando falla) → detente inmediatamente, NO ejecutes ningún otro comando. Envía el mensaje de configuración usando el método apropiado para el canal:
Feishu — usa la API de Feishu directamente (NO la herramienta message — no renderiza tarjetas):
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": "🎬 Generación de Video — Se Requiere Clave API"}, "template": "blue"},
"elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "Necesitas una **Clave API de Medeo** para generar videos.\n\n**Pasos:**\n1. Ve a https://medeo.app/dev/apikey\n - ¿No tienes cuenta? Se te guiará para registrarte. La clave aparece después de iniciar sesión.\n2. Copia la clave (comienza con `mk_`) y envíamela de vuelta.\n\nUna vez que la tenga, configuraré todo para ti."}}],
}
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 / Otros canales — envía texto plano a través de la herramienta message (estos canales soportan markdown de forma nativa):
🎬 Generación de Video — Se Requiere Clave API
Pasos:
1. Ve a https://medeo.app/dev/apikey (regístrate si es necesario — la clave aparece después de iniciar sesión)
2. Copia la clave (comienza con mk_) y envíamela de vuelta
Una vez que la tenga, configuraré todo para ti.
Una vez que proporcionen la clave: python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
1. Configuración Inicial
Si no hay una clave API configurada, el script emite "setup_required": true.
- Envía al usuario este enlace exacto: https://medeo.app/dev/apikey (esta página solicita el registro automáticamente si no ha iniciado sesión, luego muestra la clave API)
- Una vez que proporcionen la clave:
python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
2. Generar un Video (5-30 min, siempre asíncrono)
Los usuarios solo necesitan conocer 3 formas de generar un video:
- Enviar texto → generar video
- Enviar texto + subir imagen → generar video usando su imagen
- Enviar texto + URL de imagen → generar video usando la imagen de la URL
El agente maneja todo lo demás silenciosamente.
IMPORTANTE: Antes de iniciar la tarea de generación, responde inmediatamente al usuario con un acuse de recibo como: "🎬 Iniciando generación de video — te enviaré el resultado en unos 5–10 minutos." No esperes en silencio. El usuario debe saber que su solicitud fue recibida.
Uso 1: Solo texto
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descripción del video del usuario" \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Uso 2: Texto + imagen subida (el usuario envía una imagen en el chat)
# Primero: upload-file para obtener el media_id (ver Sección 3)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descripción del video del usuario" \
--media-ids "media_01..." \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Uso 3: Texto + URL de imagen
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descripción del video del usuario" \
--media-urls "https://example.com/photo.jpg" \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Comportamiento automático del agente: Cuando el usuario proporciona imágenes (Uso 2 o 3), pasa siempre
--asset-sources my_uploaded_assetspara que Medeo use sus imágenes en lugar de generar otras nuevas. El usuario no necesita saber que esta bandera existe.
Parámetros Internos (solo para uso del agente — nunca exponer a los usuarios)
Estos se manejan automáticamente por el agente. No los menciones a los usuarios ni les pidas que los proporcionen.
| Bande ra | Cuándo usarla | Comportamiento por defecto |
|---|---|---|
--voice-id "voice_01..." | Cuando se necesita una voz específica | Medeo elige automáticamente |
--video-style-id "style_01..." | Cuando se necesita un estilo visual específico | Medeo elige automáticamente |
--asset-sources | Cuando el usuario proporciona imágenes: pasa my_uploaded_assets | Medeo decide |
--recipe-id "recipe_01..." | Cuando se usa una plantilla | Ninguno |
--aspect-ratio "9:16" | Cuando el usuario especifica horizontal/vertical | 16:9 |
--duration-ms 30000 | Cuando el usuario especifica duración | Medeo decide |
--no-render | Solo depuración — omitir renderizado | Siempre renderizar |
Destino de Entrega (--deliver-to)
Esto es crítico — determina dónde se envía el video generado.
| Contexto | Valor de --deliver-to | Ejemplo |
|---|---|---|
| Chat grupal de Feishu | El chat_id del grupo (empieza con oc_). Extraer de metadatos entrantes conversation_label o chat_id — elimina el prefijo chat: si está presente (ej. chat:oc_xxx → oc_xxx) | oc_158fd3e54407cbe170697c6c954bd4f2 |
| Chat privado de Feishu | El open_id del usuario (empieza con ou_). Extraer de metadatos entrantes sender_id — elimina el prefijo user: si está presente | ou_f7f458f4d7b4ff49ec1b8de22a1e3206 |
| Telegram | El chat_id del contexto del mensaje entrante | -1001234567890 |
| Discord | El channel_id del contexto del mensaje entrante | 1234567890123456 |
Cómo determinar grupo vs privado en Feishu:
- Verifica
is_group_chaten los metadatos entrantes - Si es
true→ usaconversation_label/chat_id(el valoroc_) - Si es
false→ usasender_id(el valorou_)
Paso 2: Usa sessions_spawn con los args devueltos (label: "medeo: <breve>", runTimeoutSeconds: 2400).
Paso 3: Informa al usuario que se está generando. El subagente anuncia automáticamente cuando termina.
3. Subir Activos
3a. Desde URL (la imagen ya tiene una URL pública)
python3 {baseDir}/scripts/medeo_video.py upload \
--url "https://example.com/photo.jpg" \
--project-id "project_01..." # opcional: asociar el medio con un proyecto existente
--no-wait # opcional: devolver job_id inmediatamente sin esperar
3b. Desde adjunto de MI (el usuario envía la imagen directamente) ← NUEVO
Usa upload-file cuando el usuario envía una imagen a través de Telegram, Discord, Feishu o como archivo local.
Esto usa la API de carga directa (preparar → S3 presigned PUT → registrar) en lugar de la carga basada en URL.
Activación: Solo cuando el usuario solicita explícitamente generación de video Y envía un adjunto de imagen en el mismo mensaje (ej. "haz un video con esta foto"). NO subas automáticamente cada mensaje de imagen — otras habilidades o conversaciones pueden involucrar imágenes no relacionadas con la generación de video.
# Desde archivo local (descargado por OpenClaw desde el adjunto)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--file /tmp/user_photo.jpg
# Desde URL directa (CDN de Discord, etc.)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--url "https://cdn.discordapp.com/attachments/..."
# Desde Telegram (file_id de message.photo[-1].file_id)
# TELEGRAM_BOT_TOKEN debe establecerse como variable de entorno — nunca pasar como argumento CLI (ps aux lo filtra)
TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/medeo_video.py upload-file \
--telegram-file-id "AgACAgIAAxk..."
# Desde Feishu (message_id + image_key del contenido del mensaje)
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"
Salida: {"media_id": "media_01...", "filename": "photo.jpg"}
Luego pasa media_id a la generación:
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "Crea un video con esta persona" \
--media-ids "media_01..."
Guía de Extracción de Imágenes por Plataforma
| Plataforma | Cómo obtener la fuente de la imagen | Argumento upload-file |
|---|---|---|
| Telegram | message.photo[-1].file_id | --telegram-file-id |
| Discord | message.attachments[0].url (URL pública de CDN) | --url |
| Feishu | message_id + image_key del JSON del contenido del mensaje | --feishu-message-id + --feishu-image-key |
Descargar binario del adjunto → guardar en /tmp | --file | |
| URL genérica | Cualquier URL de imagen directa | --url |
Nota: Las URLs de adjuntos de Discord son enlaces públicos de CDN — --url funciona directamente. Todas las demás plataformas requieren autenticación para descargar.
3c. En línea en el pipeline de generación
# Basado en URL (comportamiento existente)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "Presentación de producto para esta zapatilla" \
--media-urls "https://example.com/front.jpg" "https://example.com/side.jpg"
Soporta .jpg, .png, .webp, .mp4, .mov, .gif. Mayor resolución + múltiples ángulos = mejores resultados.
3d. Verificar Estado de Carga
Después de upload o upload-file, si necesitas verificar el trabajo de carga:
python3 {baseDir}/scripts/medeo_video.py upload-status --job-id "job_01..."
Devuelve el estado del medio (processing, completed, failed) y media_id una vez finalizado.
4. Comandos de Pipeline de Bajo Nivel (interno del agente — nunca exponer a los usuarios)
Estos son solo para depuración del agente o intervención manual. Los usuarios nunca deberían ver estos comandos.
Flujo del pipeline:
spawn-task (recomendado, asíncrono)
└── generate (bloqueante, mismo pipeline)
├── upload (si --media-urls)
├── compose → compose-status (espera)
└── render → render-status (espera)
| Comando | Qué hace | Argumentos clave |
|---|---|---|
generate | Pipeline completo bloqueante (upload→compose→render) | Igual que spawn-task sin banderas de entrega |
compose | Crear proyecto solamente (sin render) | --message, --media-ids, --recipe-id |
compose-status | Esperar tarea de compose | --task-id "task_01..." |
render | Renderizar proyecto existente | --project-id "project_01..." |
render-status | Esperar trabajo de renderizado | --job-id "render_01..." |
upload-status | Esperar trabajo de carga | --job-id "job_01..." |
Todos los comandos soportan --no-wait para devolver inmediatamente sin esperar.
5. Explorar Recetas
python3 {baseDir}/scripts/medeo_video.py recipes # listar plantillas
python3 {baseDir}/scripts/medeo_video.py recipes --cursor <c> # paginar
Usar en generación: --recipe-id "recipe_01...". Ver docs/recipes.md.
6. Referencia Rápida de Comandos (para el agente, no visible para el usuario)
| Comando | Descripción | ¿Visible para el usuario? |
|---|---|---|
recipes | Listar plantillas de video | Sí — "¿qué plantillas están disponibles?" |
last-job | Estado del último trabajo | Sí — "¿mi último video está listo?" |
history | Historial de trabajos (últimos 50) | Sí — "muestra mi historial de videos" |
config | Mostrar configuración actual | No |
config-init --api-key "mk_..." | Inicializar clave API | Solo durante la configuración |
upload --url "URL" | Subir desde URL pública | No (interno del agente) |
upload-file --file RUTA | Subir desde archivo local | No (interno del agente) |
upload-file --url "URL" | Descargar URL → subir | No (interno del agente) |
upload-file --telegram-file-id "..." | Subir adjunto de Telegram | No (interno del agente) |
upload-file --feishu-image-key "..." | Subir adjunto de Feishu | No (interno del agente) |
upload-status --job-id "..." | Verificar estado del trabajo de carga | No (interno del agente) |
compose-status --task-id "..." | Verificar progreso de tarea compose | No (interno del agente) |
render-status --job-id "..." | Verificar progreso de trabajo de renderizado | No (interno del agente) |
7. Reglas Clave
- Siempre asíncrono —
spawn-task+sessions_spawnpara generación - Una llamada para historias — argumentos completos en un solo
--message, nunca dividir - Créditos insuficientes — compartir enlace de recarga desde la salida de error
- Carga de imagen desde MI — Solo subir imágenes cuando el usuario solicite explícitamente generación de video con esa imagen. NO subir automáticamente cada mensaje de imagen (el usuario puede tener otras habilidades instaladas). Cuando se active: ejecutar
upload-fileprimero → obtenermedia_id→ pasar a generación mediante--media-ids. Nunca pedir al usuario una URL si ya ha enviado la imagen. - Entrega nativa en MI — Después de la generación, entregar el video utilizando el método nativo del canal de MI (no solo una URL). Cada canal tiene un script de entrega dedicado:
- Feishu:
python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/result.mp4 --to "oc_xxx_or_ou_xxx" --cover-url "<thumbnail_url>" --duration <ms>(usaroc_chat_id para chats grupales,ou_open_id para chats privados; las formas prefixadaschat:oc_xxxyuser:ou_xxxtambién están aceptadas) - Telegram: Descargar video, luego enviar mediante
telegram_send_video.py(token solo desde entorno):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>" \
- Feishu: