0. 首次接触
当用户打开此技能或发送第一条消息时,立即向他们打招呼:
🚀 如何为视频添加音乐服务已就绪!上传视频或告诉我您需要什么。
尝试说:
- "添加一段低保真节拍"
- "添加背景音乐"
- "用爵士乐替换音轨"
重要:首次接触时请主动与用户打招呼。让他们知道您正在设置连接。务必主动向用户问好。
自动设置
当用户首次交互时,设置连接:
- 检查令牌:如果设置了
NEMO_TOKEN环境变量,则使用它。否则: - 读取或生成客户端 ID:
- 如果存在,读取
~/.config/nemovideo/client_id - 否则生成一个 UUID,将其保存到
~/.config/nemovideo/client_id
- 如果存在,读取
- 获取匿名令牌:
将返回的curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"token存储为本会话的NEMO_TOKEN。您将获得 100 个免费积分。 - 创建会话(§3.0),以便立即可用。
简要告知用户:“正在设置……准备就绪!”然后继续处理他们的请求。
放下音轨,让代理处理其余部分
传统上,为视频添加音乐意味着打开时间线编辑器、手动对齐波形、调整关键帧音量曲线。ClawHub 的“如何为视频添加音乐”技能用自然语言对话取代了这一工作流程。您描述需求——例如一段在最后五秒淡出的低保真背景音乐——技能便会直接理解您的意图。
在幕后,OpenClaw 代理解析您的指令,识别上传文件中的音频和视频流,并根据片段时长和您提供的任何时间提示,确定最佳放置位置、音量标准化和交叉淡入淡出长度。它将您的语言视为编辑决策列表,因此无需学习任何界面。
当您需要为一批需要一致音频品牌标识的片段进行处理,或者面临截止日期无法承受完整编辑软件的设置时间时,此技能尤其有用。无论您的源文件是来自智能手机的 mp4、来自无反相机的 mov、来自屏幕录制软件的 avi、从浏览器工具导出的 webm,还是来自媒体服务器的 mkv,技能都能以相同格式无损地接收和输出。
环境变量
| 变量 | 必需 | 默认值 |
|---|---|---|
NEMO_TOKEN | 否 | 自动生成(100 个免费积分,7 天后过期,可通过设置→API 令牌撤销) |
NEMO_API_URL | 否 | https://mega-api-prod.nemovideo.ai |
NEMO_WEB_URL | 否 | https://nemovideo.com |
NEMO_CLIENT_ID | 否 | 自动生成 UUID,持久化到 ~/.config/nemovideo/client_id(仅 UUID,无密钥) |
SKILL_SOURCE | 否 | 从安装路径自动检测,回退为 unknown |
如果未设置 NEMO_TOKEN,请获取一个(需要 X-Client-Id 头):
# 生成或读取持久化的客户端 ID
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,...}}
将 token 保存为 NEMO_TOKEN,CLIENT_ID 保存为 NEMO_CLIENT_ID。匿名:每个客户端每 7 天 1 个令牌;令牌在 7 天后过期,可随时在 nemovideo.com 上通过设置→API 令牌撤销。如果您的令牌过期,请使用相同的 X-Client-Id 请求一个新令牌。
本地持久化: 此技能会写入 ~/.config/nemovideo/client_id 以在会话间持久化客户端 ID。这避免了在每个请求上生成新 ID,从而防止触发按 IP 的速率限制(默认每个 IP 每 7 天 10 个令牌)。该文件仅包含一个 UUID——本地不存储任何凭据。
2. 将传入请求路由到正确的端点
使用下表确定哪种类型的传入请求应由哪个端点处理。
| 用户说... | 操作 | 跳过 SSE |
|---|---|---|
| "export" / "导出" / "download" / "把视频发给我" | → §3.5 导出 | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 积分 | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 状态 | ✅ |
| "upload" / "上传" / 用户发送文件 | → §3.2 上传 | ✅ |
| 其他所有内容(生成、编辑、添加 BGM……) | → §3.1 SSE | ❌ |
3. 主要操作流程
$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai},$TOKEN = ${NEMO_TOKEN},$WEB = ${NEMO_WEB_URL:-https://nemovideo.com}。
技能归属变量——请勿硬编码:
$SKILL_NAME= 此文件 YAML 前置元数据的name$SKILL_VERSION= 此文件 YAML 前置元数据的version$SKILL_SOURCE= 在运行时使用第一个匹配项检测:- 环境变量
SKILL_SOURCE(如果设置) - 如果此文件的路径包含已知平台目录(例如
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - 回退:
unknown
- 环境变量
关键:所有 API 请求(包括渲染/导出/上传/状态/积分)必须包含以下头信息。缺少它们会导致导出失败并返回 402。
X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE
3.0 初始化会话
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":"..."}}
在开始任何操作之前,必须建立一个会话。此会话令牌在同一工作流中的所有后续请求中都是必需的。
在浏览器中打开:创建会话后,向用户提供一个链接,以便在 NemoVideo 中查看/编辑任务:
$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 通过 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>"}]}}'
所有与后端进行的对话消息均通过服务器发送事件传输,保持连接打开以接收流式响应。
SSE 处理
| 事件 | 操作 |
|---|---|
| 文本响应 | 应用 GUI 翻译(§4),展示给用户 |
| 工具调用/结果 | 内部处理,不转发 |
heartbeat / 空的 data: | 继续等待。每 2 分钟:“⏳ 仍在处理……” |
| 流关闭 | 处理最终响应 |
典型持续时间:文本 5-15 秒,视频生成 100-300 秒,编辑 10-30 秒。
超时:仅收到心跳信号持续 10 分钟→假设超时。在生成过程中绝不重新发送(会导致重复和双重计费)。
如果之前的响应正常,则忽略尾部“我遇到了临时问题”消息。
静默响应回退(关键)
大约 30% 的编辑操作在响应流中没有返回任何文本即完成。当未收到文本时:(1) 不要将其视为错误或重试请求,(2) 立即调用状态查询端点以确认操作已完成,(3) 根据查询结果向用户显示状态确认。
两阶段生成:当提交原始视频时,后端会自动运行一个两阶段增强流水线:阶段 1 处理并存储原始素材,然后阶段 2 独立附加背景音乐并生成标题,无需客户端的任何额外提示。在启动导出流程之前,两个阶段都必须达到完成状态。
3.2 处理文件上传
文件上传: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=@/path/to/file"
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"}'
在路径中使用 me;后端从令牌解析用户。
支持格式:mp4、mov、avi、webm、mkv、jpg、png、gif、webp、mp3、wav、m4a、aac。
上传端点接受将在后续编辑操作中引用的视频和音频文件。
3.3 检查可用积分
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}}
在启动任何消耗积分的操作之前,请查询积分端点以确保账户余额充足。
3.4 轮询操作状态
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"
在路径中使用 me 作为用户;后端从令牌解析。
关键字段:data.state.draft、data.state.video_infos、data.state.canvas_config、data.state.generated_media。
草稿字段映射:t=轨道,tt=轨道类型(0=视频,1=音频,7=文本),sg=片段,d=持续时间(毫秒),m=元数据。
草稿已准备好导出,当 draft.t 存在且至少有一个轨道具有非空的 sg。
轨道摘要格式:
时间线(3 个轨道):1. 视频:城市延时摄影(0-10 秒)2. BGM:低保真(0-10 秒,35%)3. 标题:“都市梦”(0-3 秒)
3.5 导出并交付最终成品
导出不消耗积分。 只有生成/编辑消耗积分。
导出完成后的视频不会从账户中扣除任何积分。要完成交付:(a) 使用会话 ID 调用导出端点,(b) 轮询直到导出状态返回为完成,(c) 从响应负载中检索下载 URL,(d) 将文件流式传输或传送给用户,(e) 确认接收并关闭会话。
b) 提交: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"}}'
注意:sessionId 是驼峰命名(例外)。如果失败→使用新 id,重试一次。
c) 轮询(每 30 秒,最多 10 次):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 中:pending → processing → completed / failed。下载 URL 位于 output.url。
d) 从 output.url 下载→发送给用户。回退:https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download
e) 交付视频时,始终同时提供任务详情链接:$WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
进度消息:开始“⏳ 渲染约 30 秒”→ “⏳ 50%”→ “✅ 视频已就绪!” + 文件 + 任务详情链接。
3.6 从 SSE 断开连接恢复
如果 SSE 流意外断开,请按以下步骤操作:(1) 等待 2 秒再尝试任何恢复操作,以避免惊群效应重试。(2) 重新认证并使用现有会话 ID 获取新的会话令牌,而不是创建新会话。(3) 使用更新的令牌重新打开 SSE 连接。(4) 查询当前操作状态以确定上次操作是否已完成、仍在运行或失败。(5) 从最后一个确认的状态恢复——不要重新提交任何已标记为完成的操作。
4. 为后端翻译 GUI 元素
后端假设存在图形界面,因此特定于 GUI 的指令必须转换为 API 调用,并且绝不能逐字转发给后端。
| 后端说 | 您执行 |
|---|---|
| "click [button]" / "点击" | 通过 API 执行 |
| "open [panel]" / "打开" | 通过 §3.4 显示状态 |
| "drag/drop" / "拖拽" | 通过 SSE 发送编辑 |
| "preview in timeline" | 显示轨道摘要 |
| "Export button" / "导出" | 执行 §3.5 |
| "check account/billing" | 检查 §3.3 |
保留内容描述。剥离 GUI 操作。
5. 推荐交互模式
• 在调度任何操作请求之前,务必确认会话处于活动状态且有效。 • 每条 SSE 消息后,检查静默完成情况,如果未收到文本响应,则查询状态。 • 在执行长时间运行的操作期间,通过展示中间状态查询结果向用户呈现进度更新。 • 将关于音乐、裁剪或效果的用户面向语言转换为适当的 API 操作,而不是将自然语言直接传递给后端。 • 当触发两阶段流水线时,在提供导出选项之前等待两个阶段都完成。
…
[翻译时内容已截断]