Turn Spoken Words Into Embedded, Searchable Captions

Most captioning tools hand you a raw transcript and leave the placement, timing, and styling entirely up to you. The video-caption-generator skill takes a different approach — you describe what you want in plain language, and the system handles transcription, alignment, and rendering in one continuous step.

The skill works through a back-and-forth conversation. You can specify caption style, font size, line length, speaker labels, or language preferences simply by typing your intent. If the first pass doesn't match your expectations, you refine it with a follow-up message rather than digging through export menus or re-uploading the file. This iterative model means the output improves with each exchange rather than locking you into a single automated decision.

Under the hood, the OpenClaw agent coordinates audio extraction, speech-to-text processing, timing synchronization, and caption rendering into a single pipeline. The agent interprets your conversational instructions and translates them into precise rendering parameters, so the gap between what you ask for and what you receive stays narrow. Whether you are adding accessibility subtitles to a lecture recording or styling captions for a social media reel, the same conversational interface handles both without requiring separate tools or manual track editing.

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 Incoming Requests

Use the table below to determine which endpoint handles each type of user 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 Workflow Sequences

$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 depend on this identifier being present and active.

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

3.1 Transmit Messages Using 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

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

Wait silently, 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)

Approximately 30% of editing operations return no visible text in the response stream. When this occurs: (1) do not treat the absence of text as a failure, (2) immediately invoke the state query endpoint to retrieve the current job status, (3) surface the resulting status information to the user as confirmation that the operation is progressing or complete.

Two-stage generation: When raw video is submitted, the backend automatically triggers a two-stage enrichment pipeline. Stage one processes the raw footage, and stage two appends background music and a title overlay without any additional instruction from the client. Both stages must reach a completed state before the final output is considered ready.

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 and returns a file reference identifier to be used in subsequent captioning requests.

3.3 Credit Balance Verification

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 prior to processing to confirm the user has a sufficient balance for the requested operation.

3.4 Retrieve Job Status

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 Output

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

Exporting a finished caption file does not deduct any credits from the user's balance. To deliver the output: (a) confirm the job status is complete, (b) call the export endpoint with the job identifier, (c) specify the desired subtitle format, (d) receive the download URL in the response, (e) present the URL or file directly to the user.

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 Connection Loss

If the SSE connection drops, follow these five steps to recover: (1) detect the disconnection event and pause any pending UI updates, (2) wait a minimum of two seconds before attempting to reconnect to avoid flooding the server, (3) re-establish the SSE connection using the original session identifier, (4) immediately query the job state endpoint to reconcile any events that were missed during the outage, (5) resume normal operation and notify the user only if the job state has changed in a meaningful way.

4. Interpreting GUI-Side Behavior

The backend operates under the assumption that a graphical interface is present on the client side, so GUI-specific instructions must never be forwarded through the API.

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 session is active before dispatching any message or file upload request.
• When a user asks about progress, poll the state endpoint rather than relying solely on the SSE stream.
• If a silent response is received, proactively fetch job status and relay it to the user without waiting for them to ask.
• Present credit balance information before starting long operations so users can make informed decisions.
• After export, offer the download link immediately and suggest a format if the user has not specified one.

6. Known Constraints and Limitations

• Caption generation is not instantaneous; processing time scales with video length and server load.
• Only supported video formats may be uploaded; unsupported file types will be rejected at the upload stage.
• The SSE stream does not guarantee delivery of every intermediate event during high-load periods.
• Credit deductions occur at job initiation, not at export; a failed job may still consume credits depending on how far processing advanced.
• Session identifiers expire after a defined period of inactivity and cannot be reused once invalidated.

7. Error Response Handling

The table below maps common HTTP error codes to their likely causes and the recommended recovery action for each.

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 Token Scopes

Before making any requests, verify that the integration targets the correct API version by checking the version field in the base configuration. Token scopes must include read and write permissions for both jobs and files; a token missing either scope will result in authorization errors on upload or export calls. Review scope assignments whenever a new token is issued to ensure continued compatibility.