0. First Contact

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

🎵 Let's pixvideo ai video maker! Drop a video here or describe what you'd like to create.

Try saying:

• - "edit my video"
• "add effects to this clip"
• "help me create a short video"

IMPORTANT: Do NOT wait silently. Always greet the user proactively on first contact.

Auto-Setup

When the user first interacts, set up the connection:

1. 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

1. 3. Acquire anonymous token:

   curl -s -X POST "$API/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.

1. 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 Words Into Watchable Video, Effortlessly

pixvideo-ai-video-maker reimagines how video gets made. Instead of navigating complex timelines and export queues, you describe what you want — cut this clip, fade into the next scene, add a title card at the 10-second mark — and the skill handles the execution. This conversational editing model means your creative intent stays front and center while the technical heavy lifting disappears into the background.

The skill is powered by the OpenClaw agent, which interprets your instructions, breaks them into discrete video processing tasks, and coordinates the underlying AI pipeline to apply edits in the correct sequence. The OpenClaw agent also maintains context across a session, so follow-up instructions like 'make that transition slower' or 'swap the background music' are understood in relation to what came before — no need to restate your entire project.

Whether you're assembling a product demo from screen recordings, cutting a social clip from a longer interview, or building an educational walkthrough from scratch, pixvideo-ai-video-maker adapts to the shape of your project. Input and output are both supported across mp4, mov, avi, webm, and mkv formats, giving you flexibility at every stage of your workflow.

Environment Variables

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

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 "$API/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 to the Correct Endpoint

Use the table below to determine which API endpoint should handle 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 Procedures

$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 INLINECODE26
• INLINECODE27 = this file's YAML frontmatter INLINECODE28
• INLINECODE29 = 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: INLINECODE35

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

3.0 Initializing a New Session

curl -s -X POST "$API/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 action can occur, a session must be established with the API. Store the returned session identifier, as every subsequent request will require it.

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

3.1 Delivering Messages Through an SSE Channel

curl -s -X POST "$API/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 and task instructions are transmitted to the backend via a persistent Server-Sent Events connection.

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 edit operations complete without returning any text in the response stream. When this occurs: (1) do not report an error to the user, (2) poll the task state endpoint to confirm completion, (3) retrieve the finished asset URL directly, and (4) present the result to the user as if a normal response had been received.

Two-stage generation: After a raw video is produced, the backend automatically initiates a second processing stage that layers in background music and a title overlay. Treat these as two distinct pipeline stages: Stage 1 delivers the unprocessed video, and Stage 2 delivers the fully composed final output. Wait for Stage 2 to complete before surfacing the result to the user.

3.2 Handling File Uploads

File upload: INLINECODE39

URL upload: INLINECODE40

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 API accepts user-supplied media files, which must be uploaded through the designated upload endpoint before being referenced in any video task.

3.3 Checking Available Credits

curl -s "$API/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 to verify the user has a sufficient balance before submitting any task that consumes credits.

3.4 Polling for Task Status

curl -s "$API/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:
CODEBLOCK7

3.5 Exporting and Delivering the Final Asset

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

Triggering an export does not deduct any credits from the user's balance. Follow these steps: (a) confirm the task has reached a completed state, (b) call the export endpoint with the task identifier, (c) await the export job's own completion status, (d) retrieve the download or stream URL from the export response, and (e) return that URL to the user.

b) Submit: INLINECODE52

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

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

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

d) Download from output.url → send to user. Fallback: $API/api/render/proxy/<id>/download.

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

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

3.6 Recovering from an SSE Disconnection

If the SSE stream drops unexpectedly, apply the following recovery sequence: (1) record the last event ID received before the connection was lost; (2) wait a minimum of two seconds before attempting to reconnect, to avoid hammering the server; (3) re-establish the SSE connection, supplying the last event ID in the reconnect header so the server can resume from the correct position; (4) if the server does not replay missed events, fall back to polling the task state endpoint using the stored task identifier; (5) once task completion is confirmed through either method, deliver the result to the user normally.

4. Translating GUI Concepts for Backend Communication

The backend operates under the assumption that all interactions originate from a graphical interface, so never forward GUI-specific labels, button names, or interface instructions directly in API payloads.

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 what the user wants to achieve before selecting an endpoint, so the correct workflow is invoked on the first attempt.
• Provide the user with incremental progress updates during long-running tasks rather than leaving them waiting in silence.
• When a task produces no text response, retrieve the asset URL proactively and present it without prompting the user to retry.
• If a user request is ambiguous, ask one focused clarifying question rather than making assumptions that could waste credits.
• After delivering a completed video, offer a concise summary of what was created and suggest logical next steps such as editing or exporting.

6. Known Limitations

• Real-time video preview streaming is not supported; users must wait for full task completion before viewing output.
• A single session cannot run multiple video generation tasks simultaneously; tasks must be queued sequentially.
• Uploaded files must conform to the documented format and size constraints; files outside these bounds will be rejected.
• Credit balances are read-only through the API and cannot be topped up programmatically.
• SSE connections may be terminated by intermediary network infrastructure; the disconnect recovery procedure in section 3.6 must be followed in these cases.

7. Error Handling Reference

The table below maps each HTTP status code and API error code to its cause and the appropriate 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

Before going live, confirm that the integration is targeting the correct API version by checking the version field in the root endpoint response. The OAuth token used for all requests must include the scopes listed in the authorization documentation; requests made with tokens that are missing required scopes will be rejected with a 403 status regardless of token validity.