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의 비디오에 음악 추가하는 방법 스킬은 이러한 워크플로우를 일반 언어 대화로 대체합니다. 원하는 것을 설명하면(예를 들어 마지막 5초에 페이드 아웃되는 로파이 배경 트랙), 스킬이 그 의도를 직접 해석합니다.
내부적으로 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 | 아니요 | 설치 경로에서 자동 감지, fallback 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" / "send me the video" | → §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 frontmattername$SKILL_VERSION= 이 파일의 YAML frontmatterversion$SKILL_SOURCE= 런타임에 첫 번째 일치 항목을 사용하여 감지:- 설정된 경우 환경 변수
SKILL_SOURCE - 이 파일의 경로에 알려진 플랫폼 디렉토리가 포함된 경우 (예:
~/.clawhub/→clawhub,~/.cursor/skills/→cursor) - Fallback:
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분 동안 heartbeat만 수신 → 시간 초과로 간주. 생성 중에는 절대 재전송하지 마세요 (중복 + 이중 청구).
이전 응답이 정상이었다면 후행 "일시적인 문제가 발생했습니다"는 무시하세요.
무음 응답 폴백 (중요)
약 30%의 편집 작업이 응답 스트림에 텍스트를 반환하지 않고 완료됩니다. 텍스트가 수신되지 않은 경우: (1) 이를 오류로 처리하거나 요청을 재시도하지 말고, (2) 즉시 상태 조회 엔드포인트를 호출하여 작업이 완료되었는지 확인하고, (3) 해당 조회 결과를 기반으로 사용자에게 상태 확인을 표시합니다.
2단계 생성: 원본 비디오가 제출되면 백엔드는 자동으로 2단계 강화 파이프라인을 실행합니다: 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=지속 시간(ms), m=메타데이터.
내보내기 준비 완료 드래프트: draft.t가 존재하고 비어 있지 않은 sg를 가진 하나 이상의 트랙이 있는 경우.
트랙 요약 형식:
타임라인 (3 트랙): 1. 비디오: 도시 타임랩스 (0-10초) 2. BGM: 로파이 (0-10초, 35%) 3. 제목: "Urban Dreams" (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는 camelCase입니다 (예외). 실패 시 → 새 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 동작으로 변환하고 자연어를 백엔드에 직접 전달하지 마세요. • 2단계 파이프라인이 트리거되면 내보내기 전에 두 단계가 모두 완료될 때까지 기다리세요.