0. Primeiro Contato
Quando o usuário abrir esta habilidade ou enviar a primeira mensagem, saúde-o imediatamente:
🚀 Como Adicionar Música a Vídeo ao seu serviço! Envie um vídeo ou diga o que você está procurando.
Tente dizer:
- "adicione uma batida lo-fi"
- "adicione música de fundo"
- "substitua a faixa de áudio por jazz"
IMPORTANTE: Sempre cumprimente o usuário proativamente no primeiro contato. Deixe-o saber que você está configurando enquanto se conecta. Sempre cumprimente o usuário proativamente no primeiro contato.
Configuração Automática
Quando o usuário interage pela primeira vez, configure a conexão:
- Verifique o token: Se a variável de ambiente
NEMO_TOKENestiver definida, use-a. Caso contrário: - Leia ou gere um Client-ID:
- Leia
~/.config/nemovideo/client_idse existir - Caso contrário, gere um UUID, salve-o em
~/.config/nemovideo/client_id
- Leia
- Adquira um token anônimo:
Armazene ocurl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"tokenretornado comoNEMO_TOKENpara esta sessão. Você ganha 100 créditos gratuitos. - Crie uma sessão (§3.0) para estar pronto para trabalhar imediatamente.
Avise o usuário rapidamente: "Configurando... pronto!" então prossiga com a solicitação.
Solte uma Faixa, Deixe o Agente Cuidar do Resto
Adicionar música a vídeos historicamente significava abrir um editor de timeline, alinhar formas de onda manualmente e ajustar curvas de volume com keyframes. A habilidade de como adicionar música a vídeo do ClawHub substitui esse fluxo de trabalho por uma conversa em linguagem natural. Você descreve o que deseja — uma faixa de fundo lo-fi que desaparece nos últimos cinco segundos, por exemplo — e a habilidade interpreta essa intenção diretamente.
Sob o capô, o agente OpenClaw analisa sua instrução, identifica os streams de áudio e vídeo no arquivo enviado, e determina o posicionamento ideal, normalização de volume e duração do crossfade com base na duração do clipe e quaisquer dicas de tempo que você fornecer. Ele trata suas palavras como a lista de decisões de edição, então não há interface para aprender.
Esta habilidade é particularmente útil quando você está trabalhando em um lote de clipes que precisam de uma identidade de áudio consistente, ou quando você está com um prazo apertado e não pode arcar com o tempo de configuração de um conjunto completo de edição. Seja seu arquivo fonte um mp4 de um smartphone, um mov de uma câmera mirrorless, um avi de software de captura de tela, um webm exportado de uma ferramenta de navegador, ou um mkv de um servidor de mídia, a habilidade ingere e produz no mesmo formato sem perda de qualidade.
Variáveis de Ambiente
| Variável | Obrigatória | Padrão |
|---|---|---|
NEMO_TOKEN | Não | Gerado automaticamente (100 créditos gratuitos, expira em 7 dias, revogável via Configurações → Tokens de API) |
NEMO_API_URL | Não | https://mega-api-prod.nemovideo.ai |
NEMO_WEB_URL | Não | https://nemovideo.com |
NEMO_CLIENT_ID | Não | UUID gerado automaticamente, persistido em ~/.config/nemovideo/client_id (apenas UUID, sem segredos) |
SKILL_SOURCE | Não | Detectado automaticamente do caminho de instalação, fallback unknown |
Se NEMO_TOKEN não estiver definido, obtenha um (requer cabeçalho X-Client-Id):
# Gere ou leia o Client-Id persistido
CLIENT_ID="${NEMO_CLIENT_ID:-$(cat ~/.config/nemovideo/client_id 2>/dev/null)}"
if [ -z "$CLIENT_ID" ]; then
CLIENT_ID=$(uuidgen 2>/dev/null || echo "client-$(date +%s)-$RANDOM")
mkdir -p ~/.config/nemovideo & echo "$CLIENT_ID" > ~/.config/nemovideo/client_id
fi
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
# → {"code":0,"data":{"token":"nmv_usr_xxx","credits":100,...}}
Salve token como NEMO_TOKEN, CLIENT_ID como NEMO_CLIENT_ID. Anônimo: 1 token por cliente a cada 7 dias; o token expira em 7 dias e pode ser revogado a qualquer momento via Configurações → Tokens de API em nemovideo.com. Se seu token expirar, solicite um novo com o mesmo X-Client-Id.
Persistência local: Esta habilidade escreve ~/.config/nemovideo/client_id para persistir o Client-Id entre sessões. Isso evita gerar um novo ID a cada requisição, o que atingiria rapidamente o limite de taxa por IP (padrão de 10 tokens a cada 7 dias por IP). O arquivo contém apenas um UUID — nenhuma credencial é armazenada localmente.
2. Roteamento de Solicitações Recebidas para o Endpoint Correto
Use a tabela abaixo para determinar qual endpoint deve tratar cada tipo de solicitação recebida.
| Usuário diz... | Ação | Pular SSE |
|---|---|---|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Exportar | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Créditos | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 Estado | ✅ |
| "upload" / "上传" / usuário envia arquivo | → §3.2 Upload | ✅ |
| Todo o resto (gerar, editar, adicionar BGM…) | → §3.1 SSE | ❌ |
3. Fluxos de Operação Primários
$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai}, $TOKEN = ${NEMO_TOKEN}, $WEB = ${NEMO_WEB_URL:-https://nemovideo.com}.
Variáveis de atribuição da habilidade — NÃO codificar:
$SKILL_NAME= onamedo frontmatter YAML deste arquivo$SKILL_VERSION= oversiondo frontmatter YAML deste arquivo$SKILL_SOURCE= detectar em tempo de execução usando a primeira correspondência:- Variável de ambiente
SKILL_SOURCEse definida - Se o caminho deste arquivo contém um diretório de plataforma conhecido (ex.:
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - Fallback:
unknown
- Variável de ambiente
CRÍTICO: TODAS as requisições de API (incluindo render/export/upload/state/credits) DEVEM incluir esses cabeçalhos. Faltar com eles fará a exportação falhar com 402.
X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE
3.0 Inicializando uma Sessão
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" \
-d '{"task_name":"project","language":"<lang>"}'
# → {"code":0,"data":{"task_id":"...","session_id":"..."}}
Antes que qualquer operação possa começar, uma sessão deve ser estabelecida. Este token de sessão é necessário para todas as requisições subsequentes dentro do mesmo fluxo de trabalho.
Abrir no navegador: Após criar uma sessão, forneça ao usuário um link para visualizar/editar a tarefa no NemoVideo:
$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 Entregando Mensagens Através de SSE
curl -s -X POST "https://mega-api-prod.nemovideo.ai/run_sse" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "Accept: text/event-stream" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" --max-time 900 \
-d '{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}'
Todas as mensagens conversacionais para o backend são transmitidas via Server-Sent Events, mantendo a conexão aberta para respostas em stream.
Manipulação de SSE
| Evento | Ação |
|---|---|
| Resposta de texto | Aplicar tradução de GUI (§4), apresentar ao usuário |
| Chamada/resultado de ferramenta | Processar internamente, não encaminhar |
heartbeat / data: vazio | Continuar esperando. A cada 2 min: "⏳ Ainda trabalhando..." |
| Stream fecha | Processar resposta final |
Durações típicas: texto 5-15s, geração de vídeo 100-300s, edição 10-30s.
Timeout: 10 min apenas heartbeats → assumir timeout. Nunca reenviar durante geração (duplicatas + cobrança dupla).
Ignorar "Encontrei um problema temporário" se respostas anteriores foram normais.
Fallback de Resposta Silenciosa (CRÍTICO)
Aproximadamente 30% das operações de edição são concluídas sem retornar nenhum texto no stream de resposta. Quando nenhum texto for recebido: (1) não trate isso como um erro nem repita a requisição, (2) chame imediatamente o endpoint de consulta de estado para confirmar que a operação foi concluída, (3) apresente uma confirmação de status ao usuário com base no resultado dessa consulta.
Geração em dois estágios: Quando um vídeo bruto é enviado, o backend executa automaticamente um pipeline de enriquecimento de dois estágios: Estágio 1 processa e armazena a filmagem bruta, então Estágio 2 anexa independentemente música de fundo e gera um título sem nenhum prompt adicional do cliente. Ambos os estágios devem atingir um estado concluído antes que o fluxo de exportação seja iniciado.
3.2 Manipulando Uploads de Arquivos
Upload de arquivo: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -F "files=@/caminho/para/arquivo"
Upload de URL: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"urls":["<url>"],"source_type":"url"}'
Use me no caminho; o backend resolve o usuário a partir do token.
Suportados: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.
O endpoint de upload aceita arquivos de vídeo e áudio que serão referenciados em operações de edição subsequentes.
3.3 Verificando Créditos Disponíveis
curl -s "https://mega-api-prod.nemovideo.ai/api/credits/balance/simple" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
# → {"code":0,"data":{"available":XXX,"frozen":XX,"total":XXX}}
Consulte o endpoint de créditos antes de iniciar qualquer operação que consuma créditos para confirmar que a conta tem saldo suficiente.
3.4 Consultando o Estado da Operação
curl -s "https://mega-api-prod.nemovideo.ai/api/state/nemo_agent/me/<sid>/latest" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
Use me para usuário no caminho; o backend resolve a partir do token.
Campos chave: data.state.draft, data.state.video_infos, data.state.canvas_config, data.state.generated_media.
Mapeamento de campos do draft: t=faixas, tt=tipo de faixa (0=video, 1=audio, 7=texto), sg=segmentos, d=duração(ms), m=metadados.
Draft pronto para exportação quando draft.t existe com pelo menos uma faixa com sg não vazio.
Formato de resumo de faixas:
Timeline (3 faixas): 1. Vídeo: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Título: "Urban Dreams" (0-3s)
3.5 Exportando e Entregando o Ativo Final
Exportar NÃO custa créditos. Apenas geração/edição consome créditos.
Exportar o vídeo finalizado não deduz nenhum crédito da conta. Para completar a entrega: (a) chame o endpoint de exportação com o ID da sessão, (b) consulte até que o status de exportação retorne completo, (c) recupere a URL de download da resposta, (d) faça stream ou transfira o arquivo para o usuário, (e) confirme o recebimento e feche a sessão.
b) Enviar: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}'
Nota: sessionId é camelCase (exceção). Em falha → novo id, tente novamente uma vez.
c) Consultar (a cada 30s, máx. 10 consultas): curl -s "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda/<id>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
Status no nível superior status: pendente → processando → concluído / falhou. URL de download em output.url.
d) Baixar de output.url → enviar para o usuário. Fallback: https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download.
e) Ao entregar o vídeo, sempre forneça também o link de detalhes da tarefa: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
Mensagens de progresso: iniciar "⏳ Renderizando ~30s" → "⏳ 50%" → "✅ Vídeo pronto!" + arquivo + link de detalhes da tarefa.
3.6 Recuperando de uma Desconexão SSE
Se o stream SSE cair inesperadamente, siga estes passos: (1) Espere 2 segundos antes de tentar qualquer ação de recuperação para evitar uma sobrecarga de retentativas. (2) Reautentique e obtenha um token de sessão fresco usando o ID de sessão existente, em vez de criar uma nova sessão. (3) Reabra a conexão SSE com o token atualizado. (4) Consulte o estado atual da operação para determinar se a última ação foi concluída, ainda está em execução ou falhou. (5) Retome do último estado confirmado — não reenvie nenhuma operação já marcada como concluída.
4. Traduzindo Elementos de GUI para o Backend
O backend opera sob a suposição de que uma interface gráfica está presente, então instruções específicas de GUI devem ser traduzidas em chamadas de API e nunca devem ser encaminhadas textualmente para o backend.
| Backend diz | Você faz |
|---|---|
| "clique em [botão]" / "点击" | Executar via API |
| "abra [painel]" / "打开" | Mostrar estado via §3.4 |
| "arraste/solte" / "拖拽" | Enviar edição via SSE |
| "visualizar na timeline" | Mostrar resumo de faixas |
| "Botão Exportar" / "导出" | Executar §3.5 |
| "verificar conta/faturamento" | Verificar §3.3 |
Manter descrições de conteúdo. Remover ações de GUI.
5. Padrões de Interação Recomendados
• Sempre confirme que uma sessão está ativa e válida antes de despachar qualquer requisição de operação. • Após cada mensagem SSE, verifique se houve uma conclusão silenciosa e consulte o estado se nenhuma resposta de texto for recebida. • Apresente atualizações de progresso ao usuário durante operações de longa duração, exibindo resultados intermediários de consultas de estado. • Traduza toda a linguagem voltada ao usuário sobre música, cortes ou efeitos na ação de API apropriada, em vez de passar linguagem natural diretamente para o backend. • Quando um pipeline de dois estágios for acionado, espere que ambos os estágios terminem antes de oferecer a exportação.