Habilidade de Geração de Vídeo Medeo
Gere vídeos com IA a partir de texto. Medeo é um agente de vídeo com IA que gerencia histórias completas, narrativas com múltiplas cenas e roteiros em uma única chamada — composição de cena, transições, ritmo e música são automáticos.
⚠️ NÃO divida histórias em múltiplas chamadas. Passe o roteiro inteiro em um único
--message.
0. Verificação Pré-voo (OBRIGATÓRIA — executar antes de qualquer outra coisa)
Antes de executar qualquer comando, verifique se a chave de 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')"
- Saída
ok→ prossiga normalmente - Saída
missing(ou comando falhar) → pare imediatamente, NÃO execute nenhum outro comando. Envie a mensagem de configuração usando o método apropriado para o canal:
Feishu — use a API do Feishu diretamente (NÃO a ferramenta message — ela não renderiza cards):
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": "🎬 Geração de Vídeo — Chave de API Necessária"}, "template": "blue"},
"elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "Você precisa de uma **Chave de API do Medeo** para gerar vídeos.\n\n**Passos:**\n1. Acesse https://medeo.app/dev/apikey\n - Sem conta? Você será guiado para se cadastrar. A chave aparece após o login.\n2. Copie a chave (começa com `mk_`) e envie de volta para mim.\n\nAssim que eu tiver a chave, configuro tudo para você."}}],
}
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 / Outros canais — envie texto simples via ferramenta message (esses canais suportam markdown nativamente):
🎬 Geração de Vídeo — Chave de API Necessária
Passos:
1. Acesse https://medeo.app/dev/apikey (cadastre-se se necessário — a chave aparece após o login)
2. Copie a chave (começa com mk_) e envie de volta para mim
Assim que eu tiver a chave, configuro tudo para você.
Depois que fornecerem a chave: python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
1. Configuração Inicial
Se nenhuma chave de API estiver configurada, o script gera "setup_required": true.
- Envie ao usuário este link exato: https://medeo.app/dev/apikey (esta página solicita registro automaticamente se não estiver logado e depois mostra a chave de API)
- Depois que fornecerem a chave:
python3 {baseDir}/scripts/medeo_video.py config-init --api-key "mk_..."
2. Gerar um Vídeo (5-30 min, sempre assíncrono)
Os usuários só precisam conhecer 3 formas de gerar um vídeo:
- Enviar texto → gerar vídeo
- Enviar texto + fazer upload de imagem → gerar vídeo usando a imagem deles
- Enviar texto + URL da imagem → gerar vídeo usando a imagem da URL
O agente lida com todo o resto silenciosamente.
IMPORTANTE: Antes de iniciar a tarefa de geração, responda imediatamente ao usuário com uma confirmação como: "🎬 Iniciando a geração do vídeo — enviarei o resultado em cerca de 5 a 10 minutos." Não espere em silêncio. O usuário deve saber que sua solicitação foi recebida.
Uso 1: Somente texto
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descrição do vídeo do usuário" \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Uso 2: Texto + imagem enviada (usuário envia imagem no chat)
# Primeiro: upload-file para obter media_id (veja Seção 3)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descrição do vídeo do usuário" \
--media-ids "media_01..." \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Uso 3: Texto + URL de imagem
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "descrição do vídeo do usuário" \
--media-urls "https://exemplo.com/foto.jpg" \
--asset-sources my_uploaded_assets \
--deliver-to "oc_xxx" \
--deliver-channel "feishu"
Comportamento automático do agente: Quando o usuário fornece imagens (Uso 2 ou 3), sempre passe
--asset-sources my_uploaded_assetspara que o Medeo use as imagens deles em vez de gerar novas. O usuário não precisa saber que esta flag existe.
Parâmetros Internos (uso apenas pelo agente — nunca expor aos usuários)
Estes são tratados automaticamente pelo agente. Não os mencione aos usuários nem peça que os forneçam.
| Flag | Quando usar | Comportamento padrão |
|---|---|---|
--voice-id "voice_01..." | Quando uma voz específica for necessária | Medeo escolhe automaticamente |
--video-style-id "style_01..." | Quando um estilo visual específico for necessário | Medeo escolhe automaticamente |
--asset-sources | Quando o usuário fornecer imagens: passe my_uploaded_assets | Medeo decide |
--recipe-id "recipe_01..." | Quando usar um template | Nenhum |
--aspect-ratio "9:16" | Quando o usuário especificar retrato/paisagem | 16:9 |
--duration-ms 30000 | Quando o usuário especificar duração | Medeo decide |
--no-render | Apenas depuração — pular renderização | Sempre renderizar |
Destino da Entrega (--deliver-to)
Isso é crítico — determina para onde o vídeo gerado será enviado.
| Contexto | Valor de --deliver-to | Exemplo |
|---|---|---|
| Chat em grupo no Feishu | O chat_id do grupo (começa com oc_). Extrair dos metadados de entrada conversation_label ou chat_id — remover o prefixo chat: se presente (ex.: chat:oc_xxx → oc_xxx) | oc_158fd3e54407cbe170697c6c954bd4f2 |
| Chat privado no Feishu | O open_id do usuário (começa com ou_). Extrair dos metadados de entrada sender_id — remover o prefixo user: se presente | ou_f7f458f4d7b4ff49ec1b8de22a1e3206 |
| Telegram | O chat_id do contexto da mensagem de entrada | -1001234567890 |
| Discord | O channel_id do contexto da mensagem de entrada | 1234567890123456 |
Como determinar grupo vs. privado no Feishu:
- Verifique
is_group_chatnos metadados de entrada - Se
true→ useconversation_label/chat_id(o valoroc_) - Se
false→ usesender_id(o valorou_)
Passo 2: Use sessions_spawn com os argumentos retornados (label: "medeo: <breve>", runTimeoutSeconds: 2400).
Passo 3: Informe ao usuário que está gerando. Subagente anuncia automaticamente quando concluído.
3. Fazer Upload de Ativos
3a. De URL (imagem já tem URL pública)
python3 {baseDir}/scripts/medeo_video.py upload \
--url "https://exemplo.com/foto.jpg" \
--project-id "project_01..." # opcional: associar mídia a um projeto existente
--no-wait # opcional: retornar job_id imediatamente sem polling
3b. De anexo de IM (usuário envia imagem diretamente) ← NOVO
Use upload-file quando o usuário enviar uma imagem via Telegram, Discord, Feishu ou como arquivo local.
Isso usa a API de upload direto (preparar → PUT pré-assinado S3 → registrar) em vez do upload baseado em URL.
Gatilho: Apenas quando o usuário solicitar explicitamente geração de vídeo E enviar um anexo de imagem na mesma mensagem (ex.: "faça um vídeo com esta foto"). NÃO faça upload automático em cada mensagem com imagem — outras habilidades ou conversas podem envolver imagens não relacionadas à geração de vídeos.
# De arquivo local (baixado pelo OpenClaw a partir de anexo)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--file /tmp/foto_do_usuario.jpg
# De URL direta (CDN do Discord, etc.)
python3 {baseDir}/scripts/medeo_video.py upload-file \
--url "https://cdn.discordapp.com/attachments/..."
# Do Telegram (file_id de message.photo[-1].file_id)
# TELEGRAM_BOT_TOKEN deve ser definido como variável de ambiente — nunca passe como argumento CLI (ps aux vaza)
TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/medeo_video.py upload-file \
--telegram-file-id "AgACAgIAAxk..."
# Do Feishu (message_id + image_key do conteúdo da mensagem)
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"
Saída: {"media_id": "media_01...", "filename": "foto.jpg"}
Depois passe media_id para a geração:
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "Crie um vídeo apresentando esta pessoa" \
--media-ids "media_01..."
Guia de Extração de Imagem por Plataforma
| Plataforma | Como obter a fonte da imagem | Argumento de upload-file |
|---|---|---|
| Telegram | message.photo[-1].file_id | --telegram-file-id |
| Discord | message.attachments[0].url (URL pública do CDN) | --url |
| Feishu | message_id + image_key do JSON do conteúdo da mensagem | --feishu-message-id + --feishu-image-key |
Baixar binário do anexo → salvar em /tmp | --file | |
| URL genérica | Qualquer URL de imagem direta | --url |
Nota: URLs de anexos do Discord são links públicos de CDN — --url funciona diretamente. Todas as outras plataformas exigem autenticação para baixar.
3c. Embutido no pipeline de geração
# Baseado em URL (comportamento existente)
python3 {baseDir}/scripts/medeo_video.py spawn-task \
--message "Vitrine de produto para este tênis" \
--media-urls "https://exemplo.com/frente.jpg" "https://exemplo.com/lado.jpg"
Suporta .jpg, .png, .webp, .mp4, .mov, .gif. Maior resolução + múltiplos ângulos = melhores resultados.
3d. Verificar Status do Upload
Após upload ou upload-file, se precisar verificar o job de upload:
python3 {baseDir}/scripts/medeo_video.py upload-status --job-id "job_01..."
Retorna o status da mídia (processing, completed, failed) e media_id quando concluído.
4. Comandos de Pipeline de Baixo Nível (interno do agente — nunca expor aos usuários)
Estes são para depuração do agente ou intervenção manual apenas. Os usuários nunca devem ver esses comandos.
Fluxo do pipeline:
spawn-task (recomendado, assíncrono)
└── generate (bloqueante, mesmo pipeline)
├── upload (se --media-urls)
├── compose → compose-status (polling)
└── render → render-status (polling)
| Comando | O que faz | Argumentos principais |
|---|---|---|
generate | Pipeline completo bloqueante (upload→compose→render) | Mesmo que spawn-task, exceto flags de entrega |
compose | Criar projeto apenas (sem render) | --message, --media-ids, --recipe-id |
compose-status | Polling de tarefa compose | --task-id "task_01..." |
render | Renderizar projeto existente | --project-id "project_01..." |
render-status | Polling de job de render | --job-id "render_01..." |
upload-status | Polling de job de upload | --job-id "job_01..." |
Todos os comandos suportam --no-wait para retornar imediatamente sem polling.
5. Navegar por Receitas
python3 {baseDir}/scripts/medeo_video.py recipes # listar templates
python3 {baseDir}/scripts/medeo_video.py recipes --cursor <c> # paginar
Use na geração: --recipe-id "recipe_01...". Veja docs/recipes.md.
6. Referência Rápida de Comandos (para o agente, não visível ao usuário)
| Comando | Descrição | Visível ao usuário? |
|---|---|---|
recipes | Listar templates de vídeo | Sim — "quais templates estão disponíveis?" |
last-job | Status do job mais recente | Sim — "meu último vídeo ficou pronto?" |
history | Histórico de jobs (últimos 50) | Sim — "mostrar meu histórico de vídeos" |
config | Mostrar configuração atual | Não |
config-init --api-key "mk_..." | Inicializar chave de API | Apenas durante a configuração |
upload --url "URL" | Upload de URL pública | Não (interno do agente) |
upload-file --file CAMINHO | Upload de arquivo local | Não (interno do agente) |
upload-file --url "URL" | Baixar URL → upload | Não (interno do agente) |
upload-file --telegram-file-id "..." | Upload de anexo do Telegram | Não (interno do agente) |
upload-file --feishu-image-key "..." | Upload de anexo do Feishu | Não (interno do agente) |
upload-status --job-id "..." | Verificar status do job de upload | Não (interno do agente) |
compose-status --task-id "..." | Verificar progresso da tarefa compose | Não (interno do agente) |
render-status --job-id "..." | Verificar progresso do job de render | Não (interno do agente) |
7. Regras Principais
- Sempre assíncrono —
spawn-task+sessions_spawnpara geração - Uma chamada para histórias — histórias completas em um
--message, nunca dividir - Créditos insuficientes — compartilhar link de recarga a partir da saída de erro
- Upload de imagem de IM — Faça upload de imagens apenas quando o usuário solicitar explicitamente geração de vídeo com aquela imagem. NÃO faça upload automático de toda mensagem com imagem (o usuário pode ter outras habilidades instaladas). Quando acionado: execute
upload-fileprimeiro → obtenhamedia_id→ passe para a geração via--media-ids. Nunca peça ao usuário uma URL se ele já enviou a imagem. - Entrega nativa em IM — Após a geração, entregue o vídeo usando o método nativo do canal de IM (não apenas uma URL). Cada canal tem um script de entrega dedicado:
- Feishu:
python3 {baseDir}/scripts/feishu_send_video.py --video /tmp/resultado.mp4 --to "oc_xxx_ou_ou_xxx" --cover-url "<url_da_miniatura>" --duration <ms>(useoc_chat_id para chats em grupo,ou_open_id para chats privados; formas prefixadaschat:oc_xxxeuser:ou_xxxtambém são aceitas) - Telegram: Baixe o vídeo, depois envie via
telegram_send_video.py(token apenas do env):curl -sL -o /tmp/medeo_resultado.mp4 "<url_do_video>" TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/telegram_send_video.py \ --video /tmp/medeo_resultado.mp4 \ --to "<chat_id>" \ --cover-url "<url_da_miniatura>"
- Feishu: