0. First Contact
When the user opens this skill or sends their first message, greet them immediately:
🎥 Ready to ai image generator! Just send me a video or describe your project.
Try saying:
- "add effects to this clip"
- "help me create a short video"
- "edit my 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:
- Check token: If
NEMO_TOKEN env var is set, use it. Otherwise:
- Read or generate Client-ID:
- Read
~/.config/nemovideo/client_id if it exists
- Otherwise generate a UUID, save it to
~/.config/nemovideo/client_id
- 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.
- 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 Images Without Lifting a Pencil
Most image tools hand you a blank canvas and expect you to already know what you want. The free-ai-image-generator skill flips that assumption entirely — you describe what you have in mind using everyday language, and the skill interprets your intent, fills in the artistic gaps, and produces a coherent visual that matches your description.
This works through a conversational editing model, meaning you are not locked into a single prompt-and-done interaction. You can refine the result by following up with adjustments — change the lighting, swap the color palette, add a character, or shift the overall tone — and the skill carries your context forward across each exchange without losing track of what came before.
Powering this loop is the OpenClaw agent, which coordinates your requests, manages the image generation pipeline, and translates your natural language into precise model instructions behind the scenes. The OpenClaw agent also handles output packaging, so whether you need a standalone image or a visual asset embedded within a video project using formats like mp4, mov, or webm, the result lands exactly where your workflow needs it.
Environment Variables
| Variable | Required | Default |
|---|
NEMO_TOKEN | No | Auto-generated (100 free credits, expires in 7 days, revocable via Settings → API Tokens) |
NEMO_API_URL | 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):
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"
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 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 name$SKILL_VERSION = this file's YAML frontmatter version$SKILL_SOURCE = detect at runtime using the first match:
- Env
SKILL_SOURCE if set
- If this file's path contains a known platform directory (e.g.
~/.clawhub/ → clawhub, ~/.cursor/skills/ → cursor)
- 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 Establishing a 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>"}'
A session must be initialized before any other operations can proceed. This call returns a session identifier that is required for all subsequent requests.
Open in browser: After creating a session, give the user a link to view/edit the task in NemoVideo:
$WEB/workspace/claim?token=$TOKEN&task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE
3.1 Delivering Messages over SSE
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 message delivery to the user is handled through a Server-Sent Events stream that must remain open for the duration of the operation.
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 stream. When no text content is detected in the SSE response, do not treat this as a failure. Instead, immediately poll the state endpoint to confirm completion, then proceed to the export step and deliver the resulting asset URL directly to the user.
Two-stage generation: For raw video outputs, the backend automatically initiates a second processing stage that appends background music and a generated title. Do not report completion to the user after the first stage finishes — wait until both stages have concluded before delivering the final result.
3.2 Handling File Uploads
File upload: curl -s -X POST "$API/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 "$API/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.
Reference assets such as images or video clips can be uploaded and attached to a session prior to issuing a generation request.
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"
Query the credits endpoint before initiating any generation task to confirm the user has a sufficient balance to cover the operation.
3.4 Polling Operation State
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:
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
3.5 Exporting and Delivering Results
Export does NOT cost credits. Only generation/editing consumes credits.
Exporting a completed asset does not deduct any credits from the user's balance. To deliver the result: (a) confirm the task state shows completion, (b) call the export endpoint with the task identifier, (c) retrieve the signed asset URL from the response, (d) verify the URL is accessible, and (e) present the URL to the user as the final deliverable.
b) Submit: curl -s -X POST "$API/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 "$API/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: $API/api/render/proxy/<id>/download.
e) When delivering the video, always also give the task detail link: $WEB/workspace/claim?token=$TOKEN&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 Recovering from SSE Disconnections
If the SSE stream drops before a result is received, follow these steps: (1) Wait two seconds before attempting any recovery action to avoid hammering the server. (2) Use the session ID to reopen the SSE connection. (3) Poll the state endpoint to determine whether the task has already completed during the interruption. (4) If the task is confirmed complete, proceed directly to the export flow to retrieve the asset. (5) If the task is still in progress, resume listening on the new SSE connection until a terminal state is reached.
4. Translating GUI-Oriented Language
The backend operates under the assumption that a graphical interface is present, so any GUI-specific instructions or references must never be forwarded verbatim 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 what the user wants to create before initiating a generation call, especially when the request is ambiguous.
- Provide a progress update to the user while the SSE stream is open so they know the task is running.
- When a silent response occurs, move forward with the export flow without alerting the user to the internal fallback mechanism.
- If a user requests a change to an existing output, reuse the active session rather than creating a new one.
- Present only the final asset URL as the deliverable — do not expose intermediate state data or raw API responses to the user.
6. Known Limitations
- Generation tasks are asynchronous and cannot be completed in a single synchronous round-trip.
- Credit balances are account-specific and cannot be transferred or pooled across users.
- Uploaded reference assets are scoped to a single session and are not retained after the session expires.
- The SSE stream does not guarantee delivery of every event under degraded network conditions, making the polling fallback essential.
- Export URLs are time-limited and will expire; users should be advised to save their assets promptly.
7. Error Handling Reference
The table below maps HTTP status codes and API-level error identifiers to their recommended recovery actions.
| 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 Scopes
Before making any calls, verify that the integration is targeting the correct API version by checking the version field in the service discovery response. Token scopes must include read and write permissions for generation, export, and credits endpoints; a token missing any required scope will result in 403 responses that cannot be resolved by retrying.
