0. Primer Contacto
Cuando el usuario abra esta habilidad o envíe su primer mensaje, salúdelo inmediatamente:
🎥 ¡Vamos a generar subtítulos para videos! Deja un video aquí o describe lo que te gustaría crear.
Intenta decir:
- "agrega subtítulos en inglés"
- "agrega subtítulos en español"
- "genera subtítulos automáticamente"
IMPORTANTE: Siempre saluda al usuario de manera proactiva en el primer contacto. Hazle saber que estás configurando la conexión 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 un Client-ID:
- Lee
~/.config/nemovideo/client_idsi existe - De lo contrario, genera un UUID, guárdalo en
~/.config/nemovideo/client_id
- Lee
- Obtener un 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 gratuitos. - Crear una sesión (§3.0) para estar listo para trabajar de inmediato.
Házselo saber brevemente al usuario: "Configurando… ¡listo!" y luego continúa con su solicitud.
Convierte Palabras Habladas en Subtítulos Incrustados al Instante
La habilidad subtitle-video-generator tiende un puente entre el metraje de video en bruto y el contenido listo para la audiencia. En lugar de lidiar con editores de subtítulos o herramientas de línea de tiempo, simplemente describes lo que necesitas (estilo de subtítulo, tamaño de fuente, posición, idioma) y la habilidad se encarga del proceso de transcripción y renderizado de principio a fin.
En el núcleo de esta habilidad se encuentra el agente OpenClaw, que interpreta tus instrucciones en lenguaje natural y coordina el motor de transcripción con la capa de renderizado de subtítulos. Comprende solicitudes conscientes del contexto como 'agrega subtítulos blancos y negritos en la parte inferior' o 'genera subtítulos en español para este video en inglés', traduciéndolas en pasos de procesamiento precisos sin requerir ninguna entrada técnica de tu parte.
Esto hace que la habilidad sea particularmente valiosa para equipos de redes sociales que publican en plataformas que requieren accesibilidad, creadores de cursos que necesitan subtitular videos de conferencias rápidamente y especialistas en marketing que producen contenido de reproducción automática silenciosa para feeds. Debido a que los subtítulos se graban directamente en el video en lugar de adjuntarse como una pista separada, la salida funciona universalmente en todos los reproductores y plataformas sin problemas de compatibilidad.
Variables de Entorno
| Variable | Requerida | Valor por Defecto |
|---|---|---|
NEMO_TOKEN | No | Generado automáticamente (100 créditos gratuitos, 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 unknown |
Si NEMO_TOKEN no está configurado, obtén uno (requiere el encabezado X-Client-Id):
# Generar o leer el 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,...}}
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 Client-Id entre sesiones. Esto evita generar un nuevo ID en cada solicitud, lo que alcanzaría rápidamente el límite de velocidad por IP (valor por defecto 10 tokens cada 7 días por IP). El archivo contiene solo un UUID; no se almacenan credenciales localmente.
2. Referencia de Enrutamiento de Solicitudes
Cada tipo de solicitud entrante se asigna a un endpoint y método HTTP específicos, como se muestra a continuación.
| El usuario dice... | Acción | Omitir SSE |
|---|---|---|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Créditos | ✅ |
| "status" / "状态" / "show tracks" | → §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 Principales
$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:
$SKILL_NAME= elnamedel frontmatter YAML de este archivo$SKILL_VERSION= elversiondel frontmatter YAML de este archivo$SKILL_SOURCE= 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 (por ejemplo,
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - Valor por defecto:
unknown
- Variable de entorno
CRÍTICO: TODAS las solicitudes API (incluyendo render/export/upload/state/credits) DEBEN incluir estos encabezados. Su ausencia puede causar que la exportación falle con 402.
X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE
3.0 Inicializar 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: $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":"..."}}
Se debe establecer una sesión antes de que pueda proceder cualquier otra operación. Esto crea el contexto en el que operarán todas las solicitudes posteriores.
Abrir en el 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=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 Transmitir 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: $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>"}]}}'
Todos los mensajes conversacionales se entregan al backend a través de un canal de Server-Sent Events.
Manejo de SSE
| Evento | Acción |
|---|---|
| Respuesta de texto | Aplicar traducción de GUI (§4), presentar al usuario |
| Llamada/resultado de herramienta | Procesar internamente, no reenviar |
heartbeat / data: vacío | Seguir esperando. Cada 2 min: "⏳ Sigo 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: solo heartbeats durante 10 min → asumir tiempo de espera. Nunca reenviar durante la generación (duplicados + doble cobro).
Ignorar el mensaje "He encontrado un problema temporal" si las respuestas anteriores fueron normales.
Repliegue de Respuesta Silenciosa (CRÍTICO)
Aproximadamente el 30% de las operaciones de edición no devuelven contenido de texto en la respuesta. Cuando esto ocurra: primero, verifica el código de estado HTTP para confirmar que la solicitud fue exitosa; segundo, consulta el endpoint de estado de la tarea para determinar el estado de procesamiento; tercero, trata un estado de tarea completada como una operación exitosa incluso en ausencia de una respuesta de texto; cuarto, nunca vuelvas a enviar la solicitud asumiendo que falló simplemente porque no se devolvió ningún mensaje.
Generación en dos etapas: Después de que se produce el video en bruto, el backend activa automáticamente una segunda etapa de procesamiento que superpone música de fondo e inyecta una secuencia de título. Estas dos etapas se ejecutan secuencialmente sin requerir ninguna entrada adicional; tu integración debe tener en cuenta este pipeline esperando el evento de finalización de la etapa final antes de mostrar el resultado al usuario.
3.2 Subida de Activos
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: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -F "files=@/ruta/al/archivo"
Subida 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"}'
Usa me en la ruta; el backend resuelve el usuario a partir del token.
Compatible: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.
Tanto los archivos de video como los activos de imagen se pueden enviar al endpoint de subida para su uso en flujos de trabajo de generación de subtítulos.
3.3 Saldo de Créditos
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}}
Consulta el endpoint de créditos antes de iniciar cualquier tarea de generación para verificar que el usuario tenga saldo suficiente.
3.4 Consulta de Estado de la Tarea
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"
Usa me para el usuario en la ruta; el backend resuelve a partir del token.
Campos clave: data.state.draft, data.state.video_infos, data.state.canvas_config, data.state.generated_media.
Mapeo de campos del draft: t=pistas, tt=tipo de pista (0=video, 1=audio, 7=texto), sg=segmentos, d=duración(ms), m=metadatos.
Draft 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: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Título: "Urban Dreams" (0-3s)
3.5 Exportar y Entregar Resultado
La exportación NO cuesta créditos. Solo la generación/edición consume créditos.
Activar una exportación no descuenta créditos del saldo del usuario. Para completar la entrega: (a) llama al endpoint de exportación con el ID de la tarea completada; (b) espera el evento de finalización del trabajo de exportación; (c) recupera la URL de descarga del payload de la respuesta; (d) verifica que la URL sea accesible antes de presentarla; (e) muestra el enlace de descarga final al usuario.
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 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: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
Estado en status de nivel superior: pending → processing → completed / failed. 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, proporciona siempre también el enlace de detalle de la tarea: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
Mensajes de progreso: inicio "⏳ Renderizando ~30s" → "⏳ 50%" → "✅ ¡Video listo!" + archivo + enlace de detalle de la tarea.
3.6 Manejo de Desconexiones SSE
Cuando una conexión SSE se cae inesperadamente, sigue estos pasos de recuperación: (1) detecta el evento de desconexión en tu listener SSE y registra el último ID de evento recibido; (2) espera un mínimo de dos segundos antes de intentar la reconexión para evitar saturar el servidor; (3) restablece la conexión SSE usando el mismo ID de sesión; (4) reanuda la consulta del endpoint de estado de la tarea para determinar si la operación en curso se completó durante la interrupción; (5) si la tarea se encuentra en un estado completado, procede directamente a la exportación sin reenviar el mensaje original.
4. Capa de Abstracción de GUI
El backend opera bajo la suposición de que una interfaz gráfica está presente en todo momento, por lo que las instrucciones a nivel de GUI nunca deben reenviarse como parte de ninguna solicitud API.
| 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 las descripciones de contenido. Eliminar las acciones de GUI.
5. Patrones de Interacción Recomendados
- Siempre confirma la disponibilidad de créditos antes de iniciar una tarea de generación para evitar solicitudes fallidas a medio camino.
- Cuando un usuario envíe un video, acusa recibo de inmediato y establece expectativas sobre el tiempo de procesamiento antes de comenzar a consultar.
- Superficializa las actualizaciones de progreso intermedias de los eventos SSE para que los usuarios no se queden esperando sin comentarios durante operaciones más largas.
- Si se recibe una respuesta silenciosa, resuelve el estado de la tarea a través de la consulta en lugar de solicitar al usuario una aclaración o un reenvío.
- Una vez que se recupera una URL de descarga, preséntala de manera destacada y ofrece al usuario una acción clara a continuación, como descargar o compartir.