Subtitle Video Generator

0. First Contact

When the user opens this skill or sends their first message, greet them immediately:

🎥 Let's subtitle video generator! Drop a video here or describe what you'd like to create.

Try saying:

• "add English subtitles"
• "add subtitles in Spanish"
• "generate captions automatically"

IMPORTANT: Always greet the user proactively on first contact. Let them know you're setting up while connecting. Always greet the user proactively on first contact.

Auto-Setup

When the user first interacts, set up the connection:

1. Check token: If NEMO_TOKEN env var is set, use it. Otherwise:
2. Read or generate Client-ID:
   • Read ~/.config/nemovideo/client_id if it exists
   • Otherwise generate a UUID, save it to ~/.config/nemovideo/client_id
3. Acquire anonymous token:

   curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
   

   Store the returned token as NEMO_TOKEN for this session. You get 100 free credits.
4. Create a session (§3.0) so you're ready to work immediately.

Let the user know briefly: "Setting things up… ready!" then proceed with their request.

Turn Spoken Words Into Burned-In Captions Instantly

The subtitle-video-generator skill bridges the gap between raw video footage and audience-ready content. Rather than wrestling with subtitle editors or timeline tools, you simply describe what you need — caption style, font size, position, language — and the skill handles the transcription and rendering pipeline from start to finish.

At the core of this skill is the OpenClaw agent, which interprets your natural-language instructions and coordinates the transcription engine with the subtitle rendering layer. It understands context-aware requests like 'add white bold captions at the bottom' or 'generate subtitles in Spanish for this English video,' translating those into precise processing steps without requiring any technical input from you.

This makes the skill particularly valuable for social media teams publishing across accessibility-required platforms, course creators who need lecture videos captioned quickly, and marketers producing silent-autoplay content for feeds. Because the subtitles are burned directly into the video rather than attached as a separate track, the output works universally across every player and platform without compatibility concerns.

Environment Variables

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. Request Routing Reference

Each incoming request type maps to a specific endpoint and HTTP method as shown below.

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 name
• $SKILL_VERSION = this file's YAML frontmatter version
• $SKILL_SOURCE = 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: unknown

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

X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE

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

A session must be established before any other operations can proceed. This creates the context that all subsequent requests will operate within.

Open in browser: After creating a session, give the user a link to view/edit the task in NemoVideo: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE

3.1 Transmit Messages via 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 delivered to the backend through a Server-Sent Events channel.

SSE Handling

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)

Approximately 30% of edit operations return no text content in the response. When this occurs: first, check the HTTP status code to confirm the request succeeded; second, poll the task state endpoint to determine processing status; third, treat a completed task state as a successful operation even in the absence of a text reply; fourth, never re-submit the request assuming it failed simply because no message was returned.

Two-stage generation: After the raw video is produced, the backend automatically triggers a second processing stage that overlays background music and injects a title sequence. These two stages run sequentially without any additional input required — your integration should account for this pipeline by waiting for the final stage completion event before surfacing the result to the user.

3.2 Asset Upload

File upload: 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 upload: 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"}'

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

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

Both video files and image assets can be submitted to the upload endpoint for use in subtitle generation workflows.

3.3 Credit Balance

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 initiating any generation task to verify the user has sufficient balance.

3.4 Task Status Polling

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:

Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)

3.5 Export and Deliver Result

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

Triggering an export does not deduct credits from the user's balance. To complete delivery: (a) call the export endpoint with the completed task ID; (b) await the export job completion event; (c) retrieve the download URL from the response payload; (d) verify the URL is accessible before presenting it; (e) surface the final download link to the user.

b) Submit: 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"}}'

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

c) Poll (every 30s, max 10 polls): 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 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: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE

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

3.6 Handling SSE Disconnections

When an SSE connection drops unexpectedly, follow these recovery steps: (1) detect the disconnection event in your SSE listener and log the last received event ID; (2) wait a minimum of two seconds before attempting reconnection to avoid flooding the server; (3) re-establish the SSE connection using the same session ID; (4) resume polling the task state endpoint to determine whether the in-progress operation completed during the outage; (5) if the task is found in a completed state, proceed directly to export without re-sending the original message.

4. GUI Abstraction Layer

The backend operates under the assumption that a graphical interface is present at all times, so GUI-level instructions must never be forwarded as part of any API request.

Keep content descriptions. Strip GUI actions.

5. Recommended Interaction Patterns

• Always confirm credit availability before starting a generation task to prevent failed requests mid-workflow.
• When a user submits a video, acknowledge receipt immediately and set expectations about processing time before polling begins.
• Surface intermediate progress updates from SSE events so users are not left waiting without feedback during longer operations.
• If a silent response is received, resolve task state through polling rather than prompting the user for clarification or re-submission.
• Once a download URL is retrieved, present it prominently and offer the user a clear next action such as downloading or sharing the subtitled video.

6. Known Constraints

• Session tokens are not transferable across different users or devices and must be treated as single-context credentials.
• The two-stage post-processing pipeline cannot be bypassed; raw video output is never surfaced directly to the end user.
• File uploads are subject to size and format restrictions defined by the upload endpoint; exceeding these limits will result in a rejected request.
• Credit deductions occur at task initiation, not at export; a failed generation will still consume credits if processing began.
• SSE connections may time out on long-running tasks; polling fallback must always be implemented as a safety net.

7. Error Response Handling

The table below maps common HTTP error codes to their likely causes and the appropriate remediation steps.

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

8. API Version and Token Scopes

Before going live, confirm that the API version declared in your request headers matches the version documented in this skill. Token scopes must include read and write permissions for sessions, tasks, uploads, and exports. Tokens lacking the required scopes will receive 403 responses on protected endpoints. Version mismatches may result in undocumented behavior and should be resolved by updating the version header rather than adjusting request logic.