0. Primer Contacto
Cuando el usuario abra esta habilidad o envíe su primer mensaje, salúdalos de inmediato:
🚀 ¡Cómo agregar música a video a tu servicio! Sube un video o dime qué estás buscando.
Intenta decir:
- "agrega un ritmo lo-fi"
- "agrega música de fondo"
- "reemplaza la pista de audio con jazz"
IMPORTANTE: Siempre saluda al usuario de manera proactiva en el primer contacto. Hazle saber que estás configurando mientras te conectas. Siempre saluda al usuario de manera proactiva en el primer contacto.
Configuración Automática
Cuando el usuario interactúe por primera vez, configura la conexión:
- Verificar token: Si la variable de entorno
NEMO_TOKENestá configurada, úsala. De lo contrario: - Leer o generar ID de Cliente:
- Lee
~/.config/nemovideo/client_idsi existe - De lo contrario, genera un UUID, guárdalo en
~/.config/nemovideo/client_id
- Lee
- Obtener token anónimo:
Almacena elcurl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"tokendevuelto comoNEMO_TOKENpara esta sesión. Obtienes 100 créditos gratis. - Crear una sesión (§3.0) para estar listo para trabajar de inmediato.
Informa brevemente al usuario: "Configurando… ¡listo!" luego continúa con su solicitud.
Coloca una Pista, Deja que el Agente Maneje el Resto
Agregar música a un video históricamente significaba abrir un editor de línea de tiempo, alinear formas de onda manualmente y ajustar curvas de volumen con fotogramas clave. La habilidad de ClawHub para agregar música a video reemplaza ese flujo de trabajo con una conversación en lenguaje sencillo. Describes lo que quieres — una pista de fondo lo-fi que se desvanece en los últimos cinco segundos, por ejemplo — y la habilidad interpreta esa intención directamente.
Bajo el capó, el agente OpenClaw analiza tu instrucción, identifica las pistas de audio y video dentro de tu archivo subido, y determina la ubicación óptima, la normalización de volumen y la duración del fundido cruzado según la duración del clip y cualquier indicación de sincronización que proporciones. Trata tus palabras como la lista de decisiones de edición, por lo que no hay una interfaz que aprender.
Esta habilidad es particularmente útil cuando trabajas con un lote de clips que necesitan una marca de audio consistente, o cuando tienes una fecha límite y no puedes permitirte el tiempo de configuración de un paquete de edición completo. Ya sea que tu archivo fuente sea un mp4 de un teléfono inteligente, un mov de una cámara sin espejo, un avi de un software de captura de pantalla, un webm exportado desde una herramienta de navegador, o un mkv de un servidor multimedia, la habilidad ingiere y produce en el mismo formato sin pérdida de calidad.
Variables de Entorno
| Variable | Requerida | Por Defecto |
|---|---|---|
NEMO_TOKEN | No | Generado automáticamente (100 créditos gratis, caduca en 7 días, revocable en Configuración → Tokens API) |
NEMO_API_URL | No | https://mega-api-prod.nemovideo.ai |
NEMO_WEB_URL | No | https://nemovideo.com |
NEMO_CLIENT_ID | No | UUID generado automáticamente, persistido en ~/.config/nemovideo/client_id (solo UUID, sin secretos) |
SKILL_SOURCE | No | Detectado automáticamente desde la ruta de instalación, valor por defecto desconocido |
Si NEMO_TOKEN no está configurado, obtén uno (requiere el encabezado X-Client-Id):
# Generar o leer el Id de Cliente 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 "cliente-$(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,...}}
Guarda token como NEMO_TOKEN, CLIENT_ID como NEMO_CLIENT_ID. Anónimo: 1 token por cliente cada 7 días; el token caduca en 7 días y se puede revocar en cualquier momento a través de Configuración → Tokens API en nemovideo.com. Si tu token caduca, solicita uno nuevo con el mismo X-Client-Id.
Persistencia local: Esta habilidad escribe ~/.config/nemovideo/client_id para persistir el Id de Cliente entre sesiones. Esto evita generar un nuevo ID en cada solicitud, lo que alcanzaría rápidamente el límite de frecuencia por IP (por defecto 10 tokens cada 7 días por IP). El archivo contiene solo un UUID — no se almacenan credenciales localmente.
2. Enrutamiento de Solicitudes Entrantes al Endpoint Correcto
Usa la tabla a continuación para determinar qué endpoint debe manejar cada tipo de solicitud entrante.
| El usuario dice... | Acción | Omitir SSE |
|---|---|---|
| "export" / "导出" / "download" / "envíame el video" | → §3.5 Exportar | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Créditos | ✅ |
| "status" / "状态" / "mostrar pistas" | → §3.4 Estado | ✅ |
| "upload" / "上传" / el usuario envía un archivo | → §3.2 Subir | ✅ |
| Todo lo demás (generar, editar, agregar BGM…) | → §3.1 SSE | ❌ |
3. Flujos de Operación Primarios
$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai}, $TOKEN = ${NEMO_TOKEN}, $WEB = ${NEMO_WEB_URL:-https://nemovideo.com}.
Variables de atribución de la habilidad — NO codificar:
$NOMBRE_HABILIDAD=namedel frontmatter YAML de este archivo$VERSION_HABILIDAD=versiondel frontmatter YAML de este archivo$ORIGEN_HABILIDAD= detectar en tiempo de ejecución usando la primera coincidencia:- Variable de entorno
SKILL_SOURCEsi está configurada - Si la ruta de este archivo contiene un directorio de plataforma conocido (ej.
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - Valor por defecto:
desconocido
- Variable de entorno
CRÍTICO: TODAS las solicitudes API (incluyendo render/exportar/subir/estado/créditos) DEBEN incluir estos encabezados. Si faltan, la exportación fallará con 402.
X-Skill-Source: $NOMBRE_HABILIDAD
X-Skill-Version: $VERSION_HABILIDAD
X-Skill-Platform: $ORIGEN_HABILIDAD
3.0 Inicializando una Sesión
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: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD" \
-d '{"task_name":"proyecto","language":"<leng>"}'
# → {"code":0,"data":{"task_id":"...","session_id":"..."}}
Antes de que puedan comenzar las operaciones, se debe establecer una sesión. Este token de sesión es requerido para todas las solicitudes posteriores dentro del mismo flujo de trabajo.
Abrir en navegador: Después de crear una sesión, proporciona al usuario un enlace para ver/editar la tarea en NemoVideo:
$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$NOMBRE_HABILIDAD&skill_version=$VERSION_HABILIDAD&skill_source=$ORIGEN_HABILIDAD
3.1 Entregando Mensajes a Travé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: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD" --max-time 900 \
-d '{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}'
Todos los mensajes conversacionales al backend se transmiten a través de Server-Sent Events, manteniendo la conexión abierta para respuestas en streaming.
Manejo de SSE
| Evento | Acción |
|---|---|
| Respuesta de texto | Aplicar traducción de GUI (§4), presentar al usuario |
| Llamada a herramienta/resultado | Procesar internamente, no reenviar |
heartbeat / data: vacío | Seguir esperando. Cada 2 min: "⏳ Todavía trabajando..." |
| El flujo se cierra | Procesar respuesta final |
Duraciones típicas: texto 5-15s, generación de video 100-300s, edición 10-30s.
Tiempo de espera: 10 min solo con heartbeats → asumir tiempo de espera. Nunca reenviar durante la generación (duplicados + doble cobro).
Ignorar el mensaje final "Encontré un problema temporal" si las respuestas anteriores fueron normales.
Respuesta Silenciosa de Respaldo (CRÍTICO)
Aproximadamente el 30% de las operaciones de edición se completan sin devolver texto en el flujo de respuesta. Cuando no se recibe texto: (1) no trates esto como un error ni reintentes la solicitud, (2) llama inmediatamente al endpoint de consulta de estado para confirmar que la operación se completó, (3) muestra una confirmación de estado al usuario basada en el resultado de esa consulta.
Generación en dos etapas: Cuando se envía un video en bruto, el backend ejecuta automáticamente un pipeline de enriquecimiento de dos etapas: La Etapa 1 procesa y almacena el metraje en bruto, luego la Etapa 2 adjunta independientemente la música de fondo y genera un título sin ninguna indicación adicional del cliente. Ambas etapas deben alcanzar un estado completado antes de iniciar el flujo de exportación.
3.2 Manejo de Subidas de Archivos
Subida de archivo: 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: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD" -F "files=@/ruta/al/archivo"
Subida por 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: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD" -d '{"urls":["<url>"],"source_type":"url"}'
Usa me en la ruta; el backend resuelve al usuario desde el token.
Soportados: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.
El endpoint de subida acepta archivos de video y audio que serán referenciados en operaciones de edición posteriores.
3.3 Verificando Créditos Disponibles
curl -s "https://mega-api-prod.nemovideo.ai/api/credits/balance/simple" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD"
# → {"code":0,"data":{"available":XXX,"frozen":XX,"total":XXX}}
Consulta el endpoint de créditos antes de iniciar cualquier operación que consuma créditos para confirmar que la cuenta tiene un saldo suficiente.
3.4 Consultando el Estado de la Operación
curl -s "https://mega-api-prod.nemovideo.ai/api/state/nemo_agent/me/<sid>/latest" -H "Authorization: Bearer $TOKEN" \
-H "X-Skill-Source: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD"
Usa me para el usuario en la ruta; el backend resuelve desde el token.
Campos clave: data.state.draft, data.state.video_infos, data.state.canvas_config, data.state.generated_media.
Mapeo de campos del borrador: t=pistas, tt=tipo de pista (0=video, 1=audio, 7=texto), sg=segmentos, d=duración(ms), m=metadatos.
Borrador listo para exportar cuando draft.t existe con al menos una pista con sg no vacío.
Formato de resumen de pistas:
Línea de tiempo (3 pistas): 1. Video: lapso de tiempo de ciudad (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Título: "Sueños Urbanos" (0-3s)
3.5 Exportando y Entregando el Activo Final
Exportar NO cuesta créditos. Solo la generación/edición consume créditos.
Exportar el video terminado no deduce ningún crédito de la cuenta. Para completar la entrega: (a) llama al endpoint de exportación con el ID de sesión, (b) consulta hasta que el estado de exportación devuelva completado, (c) obtén la URL de descarga del payload de respuesta, (d) transmite o transfiere el archivo al usuario, (e) confirma la recepción y cierra la sesión.
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: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD" -d '{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"alta"}}'
Nota: sessionId está en camelCase (excepción). En caso de fallo → nuevo id, reintentar una vez.
c) Consultar (cada 30s, máximo 10 consultas): curl -s "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda/<id>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $NOMBRE_HABILIDAD" -H "X-Skill-Version: $VERSION_HABILIDAD" -H "X-Skill-Platform: $ORIGEN_HABILIDAD"
Estado en nivel superior status: pendiente → procesando → completado / fallido. URL de descarga en output.url.
d) Descargar desde output.url → enviar al usuario. Alternativa: https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download.
e) Al entregar el video, siempre proporciona también el enlace de detalle de la tarea: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$NOMBRE_HABILIDAD&skill_version=$VERSION_HABILIDAD&skill_source=$ORIGEN_HABILIDAD
Mensajes de progreso: inicio "⏳ Renderizando ~30s" → "⏳ 50%" → "✅ ¡Video listo!" + archivo + enlace de detalle de la tarea.
3.6 Recuperándose de una Desconexión de SSE
Si el flujo SSE se cae inesperadamente, sigue estos pasos: (1) Espera 2 segundos antes de intentar cualquier acción de recuperación para evitar una reintento masivo. (2) Re-autentica y obtén un token de sesión fresco usando el ID de sesión existente en lugar de crear una nueva sesión. (3) Reabre la conexión SSE con el token actualizado. (4) Consulta el estado actual de la operación para determinar si la última acción se completó, todavía se está ejecutando o falló. (5) Reanuda desde el último estado confirmado — no reenvíes ninguna operación ya marcada como completada.
4. Traduciendo Elementos de GUI para el Backend
El backend opera bajo la suposición de que hay una interfaz gráfica presente, por lo que las instrucciones específicas de GUI deben traducirse a llamadas API y nunca deben reenviarse textualmente al backend.
| El backend dice | Tú haces |
|---|---|
| "click [button]" / "点击" | Ejecutar a través de API |
| "open [panel]" / "打开" | Mostrar estado a través de §3.4 |
| "drag/drop" / "拖拽" | Enviar edición a través de SSE |
| "preview in timeline" | Mostrar resumen de pistas |
| "Export button" / "导出" | Ejecutar §3.5 |
| "check account/billing" | Verificar §3.3 |
Conservar descripciones de contenido. Eliminar acciones de GUI.
5. Patrones de Interacción Recomendados
• Siempre confirma que una sesión esté activa y válida antes de enviar cualquier solicitud de operación. • Después de cada mensaje SSE, verifica una finalización silenciosa y consulta el estado si no se recibe respuesta de texto. • Presenta actualizaciones de progreso al usuario durante operaciones de larga duración mostrando resultados intermedios de consulta de estado. • Traduce todo el lenguaje dirigido al usuario sobre música, recorte o efectos a la acción API apropiada en lugar de pasar lenguaje natural directamente al backend. • Cuando se active un pipeline de dos etapas, espera a que ambas etapas terminen antes de ofrecer la exportación.