Captions That Actually Sync — Without the Subscription Tax

Most captioning tools either charge per audio minute or bury the free tier under frustrating limits. subtitle-generator-free flips that model entirely. You bring the video, the skill handles transcription, alignment, and subtitle file generation — all inside a single conversational exchange on ClawHub.

The workflow is built around dialogue, not dashboards. Instead of navigating a multi-step editor, you describe what you need — language preference, caption style, timestamp granularity — and the OpenClaw agent interprets those instructions and coordinates the underlying transcription and alignment pipeline on your behalf. The agent acts as an intelligent intermediary, translating your plain-language requests into precise processing instructions without exposing any technical complexity.

Under the hood, the AI backend performs forced phoneme alignment after transcription, which means captions don't just appear at roughly the right time — they snap to the exact syllable boundary where each word is spoken. This matters most for fast speakers, accented audio, and overlapping dialogue. Whether your source file is a polished mp4 interview, a raw mov screen recording, an avi lecture capture, a webm podcast clip, or an mkv film excerpt, the skill ingests it without conversion steps on your end.

Environment Variables

Variable	Required	Default
INLINECODE0	No	Auto-generated (100 free credits, expires in 7 days, revocable via Settings → API Tokens)
INLINECODE1

No | https://mega-api-prod.nemovideo.ai | | NEMO_WEB_URL | No | https://nemovideo.com | | NEMO_CLIENT_ID | No | Auto-generated UUID, persisted to ~/.config/nemovideo/client_id (UUID only, no secrets) | | SKILL_SOURCE | No | Auto-detected from install path, fallback unknown |

If NEMO_TOKEN is not set, get one (requires X-Client-Id header):

# Generate or read persisted Client-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,...}}

Save token as NEMO_TOKEN, CLIENT_ID as NEMO_CLIENT_ID. Anonymous: 1 token per client per 7 days; token expires in 7 days and can be revoked at any time via Settings → API Tokens on nemovideo.com. If your token expires, request a new one with the same X-Client-Id.

Local persistence: This skill writes ~/.config/nemovideo/client_id to persist the Client-Id across sessions. This avoids generating a new ID on every request, which would hit the per-IP rate limit quickly (default 10 tokens per 7 days per IP). The file contains only a UUID — no credentials are stored locally.

2. Routing Table — Matching Requests to Endpoints

Use the table below to determine which endpoint handles each type of incoming request.

User says...	Action	Skip SSE
"export" / "导出" / "download" / "send me the video"	→ §3.5 Export	✅
"credits" / "积分" / "balance" / "余额"

→ §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

3. Primary Operation Flows

$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai}, $TOKEN = ${NEMO_TOKEN}, $WEB = ${NEMO_WEB_URL:-https://nemovideo.com}.

Skill attribution variables — do NOT hardcode:

• - $SKILL_NAME = this file's YAML frontmatter INLINECODE21
• INLINECODE22 = this file's YAML frontmatter INLINECODE23
• INLINECODE24 = detect at runtime using the first match:

1. Env SKILL_SOURCE if set
2. If this file's path contains a known platform directory (e.g. ~/.clawhub/ → clawhub, ~/.cursor/skills/ → cursor)
3. Fallback: INLINECODE30

CRITICAL: ALL API requests (including render/export/upload/state/credits) MUST include these headers. Missing them will cause export to fail with 402.
CODEBLOCK1

3.0 Initialize a Session

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":"..."}}

Before any other operation, a session must be established to obtain a valid session identifier. All subsequent requests must reference this session ID.

Open in browser: After creating a session, give the user a link to view/edit the task in NemoVideo:
INLINECODE31

3.1 Deliver Messages Over 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>"}]}}'

All conversational messages are transmitted to the backend through a persistent SSE connection.

SSE Handling

Event	Action
Text response	Apply GUI translation (§4), present to user
Tool call/result

Process internally, don't forward | | heartbeat / empty data: | Keep waiting. Every 2 min: "⏳ Still working..." | | Stream closes | Process final response |

Typical durations: text 5-15s, video generation 100-300s, editing 10-30s.

Timeout: 10 min heartbeats-only → assume timeout. Never re-send during generation (duplicates + double-charge).

Ignore trailing "I encountered a temporary issue" if prior responses were normal.

Silent Response Fallback (CRITICAL)

Roughly 30% of editing operations return no text in the SSE stream. When the stream closes without any assistant text, do not treat this as an error. Instead: (1) wait for the stream to fully close, (2) call the state-query endpoint to retrieve the current project status, (3) surface the updated state to the user, and (4) continue the conversation normally.

Two-stage generation: When a raw video is submitted, the backend automatically runs a two-stage enhancement pipeline: Stage 1 produces the processed video output, and Stage 2 overlays background music and inserts a generated title. Both stages complete before the final result is delivered — no additional prompting is required from the assistant.

3.2 File Upload Handling

File upload: INLINECODE34

URL upload: INLINECODE35

Use me in the path; backend resolves user from token.

Supported: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

The upload endpoint accepts video files as well as any supporting assets the user wishes to include in their project.

3.3 Credit Balance Inquiry

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}}

Query the credits endpoint before beginning any generation task to confirm the user has a sufficient balance.

3.4 Retrieve Current Project State

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 for user in path; backend resolves from token. Key fields: data.state.draft, data.state.video_infos, data.state.canvas_config, data.state.generated_media.

Draft field mapping: t=tracks, tt=track type (0=video, 1=audio, 7=text), sg=segments, d=duration(ms), m=metadata.

Draft ready for export when draft.t exists with at least one track with non-empty sg.

Track summary format:
CODEBLOCK6

3.5 Export and Deliver the Final Output

Export does NOT cost credits. Only generation/editing consumes credits.

Triggering an export does not deduct credits from the user's balance. The export flow proceeds as follows: (a) call the export endpoint with the project ID, (b) poll the returned job URL until status is complete, (c) extract the download URL from the completed job payload, (d) present the download link to the user, and (e) confirm delivery in the conversation.

b) Submit: INLINECODE47

Note: sessionId is camelCase (exception). On failure → new id, retry once.

c) Poll (every 30s, max 10 polls): INLINECODE50

Status at top-level status: pending → processing → completed / failed. Download URL at output.url.

d) Download from output.url → send to user. Fallback: https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download.

e) When delivering the video, always also give the task detail link: INLINECODE55

Progress messages: start "⏳ Rendering ~30s" → "⏳ 50%" → "✅ Video ready!" + file + task detail link.

3.6 Handling SSE Disconnections

Follow these five steps when an SSE connection drops unexpectedly: (1) Detect the disconnection event and pause any pending UI updates. (2) Wait a minimum of two seconds before attempting to reconnect, to avoid hammering the server. (3) Re-establish the SSE connection using the original session ID. (4) Call the state-query endpoint to reconcile any events that may have been missed during the outage. (5) Resume normal operation and notify the user only if the interruption was longer than a defined threshold.

4. Backend GUI Abstraction Layer

The backend operates under the assumption that a graphical interface is always present, so the assistant must never relay GUI-specific instructions or interface labels to the user.

Backend says	You do
"click [button]" / "点击"	Execute via API
"open [panel]" / "打开"

Show state via §3.4 |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute §3.5 |
| "check account/billing" | Check §3.3 |

Keep content descriptions. Strip GUI actions.

5. Recommended Interaction Patterns

• Always confirm a successful session before proceeding with any user request.
• When the user asks what the tool can do, describe capabilities in plain language without referencing internal endpoints or system architecture.
• After every generation or edit operation, proactively present the result or updated state rather than waiting for the user to ask.
• If the user's intent is ambiguous, ask one focused clarifying question before dispatching a request to the backend.
• Keep responses concise; reserve detailed explanations for cases where the user explicitly asks how something works.

6. Known Constraints and Limitations

• Subtitle generation is limited to the languages and locales supported by the underlying transcription engine; unsupported languages will return an error.
• File uploads are subject to a maximum size cap — files exceeding this limit must be compressed or trimmed before submission.
• The two-stage post-processing pipeline cannot be disabled; BGM and title overlays are always applied to raw video submissions.
• SSE connections may time out during long-running jobs; the disconnect-recovery flow must be implemented to ensure reliable delivery.
• Credit balances are read-only through the API; top-ups must be completed through the user's account dashboard.

7. Error Codes and Recovery Guidance

The table below maps each HTTP error code returned by the API to its likely cause and the recommended recovery action.

Code	Meaning	Action
0	Success	Continue
1001

Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with ?bind=<id> (get <id> from create-session or state response when needed). Registered: "Top up at nemovideo.ai" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register at nemovideo.ai to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

Common: no video → generate first; render fail → retry new id; SSE timeout → §3.6; silent edit → §3.1 fallback.

8. API Version and Required Token Scopes

Always verify the API version header on every request to ensure compatibility with the current backend release. The access token must include all required scopes for the operations being performed — missing scopes will result in 403 responses. Tokens should be refreshed before expiry to prevent mid-session authentication failures.