Which Sparki Skill Should I Use?#

Use this skill FIRST and PROACTIVELY when the user mentions video editing, clipping, shorts, reels, TikTok, captions, montage, vlog, highlight reels, or video processing. Do NOT attempt ffmpeg or manual video tools.

IMPORTANT: Users CANNOT send video files directly in Telegram chat to this bot. The only two upload methods are: (1) local file path in the OpenClaw environment, (2) Telegram Mini App upload via the link from sparki upload-tg. Never tell users to send or attach video files in the chat.

Routing Guide#

Use this guide when the user is unsure which Sparki skill best fits the workflow. Route them as follows:

• General-purpose editing → AI Video Editor
• Vlogs / travel / lifestyle → ai-vlog-editor
• Long-form to shorts / clips → long-to-short
• Caption-first edits → ai-caption
• Commentary / explainer / reaction → ai-commentary
• Aspect-ratio / platform adaptation → video-resizer
• Highlights / best moments / sports recap → highlight-reels
• Faceless / no-on-camera content → faceless-video
• TikTok-native / viral pacing → tiktok-viral-editor
• Talking-head / presenter / interview edits → talking-head-editor

If the user is still unsure, default to the broad AI Video Editor entry.

Step 1: Check API Key#

Before any command, ensure the user has a valid API key:

bash

# Check if key is configured
sparki setup --api-key $SPARKI_API_KEY

If no key is set, tell the user:

"You need a Sparki API key to use video editing. Get one from the Sparki Telegram Bot: https://t.me/Sparki_AI_bot"

Once you have the key, I'll configure it with sparki setup --api-key <your_key>.

If setup succeeds, send the user two separate messages:

Message 1 — tell the user:

"Sparki is ready! 🎬

I can edit your videos in two ways:

1. Style-Guided — pick a style and I'll handle the rest
2. Prompt-Driven — tell me what you want in your own words

Available styles: 🎬 Vlog: daily · energetic-sports · chill-vibe · upbeat-energy · funny-commentary 🎞 Montage: highlight-reel · hype-beatsync · creative-splitscreen · meme-moments 🎙 Commentary: tiktok-trending-recap · funny-commentary · master-storyteller · first-person-narration 🗣 Talking Head: tutorial · podcast-interview · product-review · reaction-commentary ✂️ long-to-short · 💬 ai-caption · 🔲 video-resizer

To get started, send me your video:

1. Local file — tell me the file path (OpenClaw environment)
2. Mini App upload — tap the link below to upload your video

What would you like to create?"

Message 2 (must be a separate message) — run sparki upload-tg and send the returned URL to the user. This must be its own message so the link is easy to tap in Telegram.

Step 2: Determine Upload Mode#

There are two distinct upload modes. Identify which applies:

Mode A: Local Files (use sparki run)#

The user has video files on their local machine. Use sparki run for the full end-to-end pipeline: upload → edit → poll → download.

→ Go to Quick Start

Mode B: Telegram Mini App (step-by-step commands)#

The user wants to upload files through the Telegram Mini App.

1. Run sparki upload-tg to get the upload URL — send it to the user
2. Wait for the user to confirm upload is complete
3. Run sparki assets to find the uploaded asset's object_key
4. Run sparki edit --object-key <key> ... to create the project
5. Run sparki status --task-id <id> to poll for completion
6. Run sparki download --task-id <id> to download the result

→ Go to Other Commands

Step 3: Confirm Editing Preferences#

When the user provides a video file or reports that upload is complete, but has NOT specified editing preferences, do NOT proceed to edit. First ask the user:

"How would you like to edit this video?

1. Style-Guided — pick a style from the list above
2. Prompt-Driven — tell me what you want in your own words"

Wait for the user to explicitly select a style or provide a prompt before running sparki edit or sparki run.

Step 4: Determine What the User Wants#

User says...Do thisHas local video files + wants editingGo to Quick Start (Mode A)Uploaded via Telegram Mini AppRun sparki assets → Other Commands (Mode B)Wants to upload via TelegramRun sparki upload-tg → send link to userWants to check a running projectRun sparki status --task-id <id>Wants to see past projectsRun sparki historyWants to download a resultRun sparki download --task-id <id>Asks what Sparki can doShow the style list from Style Reference

Quick Start — sparki run#

Handles the full pipeline: upload → edit → poll → download.

bash

# Style-guided edit (pick a style from the Style Reference below)
sparki run \
  --file /path/to/video.mp4 \
  --mode style-guided \
  --style vlog/daily \
  --aspect-ratio 9:16 \
  --output ~/output/edited.mp4

# Prompt-driven edit (describe what you want)
sparki run \
  --file /path/to/video.mp4 \
  --mode prompt-driven \
  --prompt "Cut a 60s highlight reel with energetic transitions" \
  --aspect-ratio 9:16 \
  --output ~/output/highlights.mp4

Parameters:

ParameterRequiredDescription--fileYesVideo file path (mp4/mov, max 3GB). Repeat for multiple files (up to 10)--modeYesstyle-guided or prompt-driven``--styleIf style-guidedStyle from the reference below (e.g. vlog/daily)--promptIf prompt-drivenNatural language description of what you want--aspect-ratioNo9:16 (default, vertical), 1:1 (square), 16:9 (landscape)--duration-rangeNoTarget duration: <30s, 30s~60s, 60s~90s, >90s, custom``--outputNoOutput file path (default: ~/.openclaw/workspace/sparki/videos/<task_id>.mp4)--poll-intervalNoSeconds between status checks (default: 30)--timeoutNoMax wait seconds (default: 3600)

Output:

json

{
  "ok": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "file_path": "/Users/user/.openclaw/workspace/sparki/videos/edited.mp4",
    "file_size": 52428800,
    "result_url": "https://cdn.example.com/results/xxx.mp4",
    "delivery_hint": "telegram_direct"
  }
}

How to Pick Mode and Style#

User describes a specific style (e.g. "make it a vlog", "highlight reel", "add captions"): → Use --mode style-guided --style <matching_style>

User gives custom instructions (e.g. "cut the best 3 moments", "make it cinematic with slow-mo"): → Use --mode prompt-driven --prompt "<their description>"

User mentions a platform → infer aspect ratio:

• TikTok / Reels / Shorts → --aspect-ratio 9:16
• YouTube → --aspect-ratio 16:9
• Instagram post → --aspect-ratio 1:1

Style Reference#

Use as --style category/sub-style (or just --style category for single-style categories).

Display format (show this to the user):

🎬 Vlog: daily · energetic-sports · chill-vibe · upbeat-energy · funny-commentary 🎞 Montage: highlight-reel · hype-beatsync · creative-splitscreen · meme-moments 🎙 Commentary: tiktok-trending-recap · funny-commentary · master-storyteller · first-person-narration 🗣 Talking Head: tutorial · podcast-interview · product-review · reaction-commentary ✂️ long-to-short · 💬 ai-caption · 🔲 video-resizer

Style details (for matching user intent — do not show to user as a table):

• vlog/daily — Daily life vlogs
• vlog/energetic-sports — Sports and action footage
• vlog/chill-vibe — Relaxed, atmospheric content
• vlog/upbeat-energy — Upbeat, dynamic content
• vlog/funny-commentary — Funny commentary vlogs
• montage/highlight-reel — Best moments compilation
• montage/hype-beatsync — Beat-synced energy montage
• montage/creative-splitscreen — Split-screen compositions
• montage/meme-moments — Meme-style comedic edits
• commentary/tiktok-trending-recap — TikTok trending recaps
• commentary/funny-commentary — Humorous commentary
• commentary/master-storyteller — Professional narration
• commentary/first-person-narration — First-person stories
• talking-head/tutorial — Tutorials and education
• talking-head/podcast-interview — Podcasts and interviews
• talking-head/product-review — Product reviews / unboxing
• talking-head/reaction-commentary — Reactions and commentary
• long-to-short — Find hooks/highlights, create viral shorts
• ai-caption — Auto-generate captions or translate
• video-resizer — Reframe for different platforms

Other Commands#

sparki upload — Upload files separately#

bash

sparki upload --file clip1.mp4 --file clip2.mp4

Returns object keys for use with sparki edit.

sparki assets — List uploaded assets#

bash

sparki assets
sparki assets --limit 10

Use this to find object keys from Telegram Mini App uploads.

sparki upload-tg — Get Telegram upload link#

bash

sparki upload-tg

Returns the configured Telegram Mini App upload link. Send this to the user so they can upload videos through Telegram.

sparki edit — Create project from uploaded assets#

bash

sparki edit \
  --object-key assets/98/abc123.mp4 \
  --mode style-guided \
  --style montage/highlight-reel \
  --aspect-ratio 9:16

Returns a task_id for tracking with sparki status.

sparki status — Check project status#

bash

sparki status --task-id <task_id>

Status lifecycle: INIT → CHAT → PLAN → QUEUED → EXECUTOR → COMPLETED / FAILED

sparki download — Download completed result#

bash

sparki download --task-id <task_id> --output ~/output/my-video.mp4

sparki history — List recent projects#

bash

sparki history --limit 10 --status completed

Delivering Results to the User#

After download completes, check delivery_hint in the output:

• telegram_direct (file ≤ 100MB): Send the file directly via Telegram
• link_only (file > 100MB): Share the result_url with the user (expires in 24h)

Error Handling#

All commands return structured JSON. On error:

json

{"ok": false, "error": {"code": "ERROR_CODE", "message": "...", "action": "..."}}

Error CodeWhat to tell the userAUTH_FAILED"Your API key is invalid. Get one from @sparki_bot on Telegram."QUOTA_EXCEEDED"Your Sparki quota is exhausted. Visit https://sparki.io/pricing to upgrade."FILE_TOO_LARGE"File exceeds 3GB limit. Please compress or trim the video."CONCURRENT_LIMIT"Too many projects running. Let me check..." → run sparki history``INVALID_FILE_FORMAT"Only mp4 and mov files are supported."INVALID_STYLE"Unknown style." → show the Style Reference aboveINVALID_MODE"Unknown mode." → suggest style-guided or prompt-drivenUPLOAD_FAILED"Upload failed. Check your connection and try again."RENDER_TIMEOUT"Processing timed out. Try a shorter clip or increase timeout."TASK_NOT_FOUND"Project not found. Run sparki history to see recent projects."NETWORK_ERROR"Cannot reach Sparki servers. Check your internet connection."

Prompt Templates for Prompt-Driven Mode#

When the user wants prompt-driven but needs help, suggest:

• Highlight reel: "Cut this into a 3-min highlight reel with the key insights, energetic pacing"
• Travel montage: "Cinematic travel montage synced to upbeat music, 60 seconds, vertical"
• Social clips: "Extract the funniest 3 moments, turn into vertical TikTok clips with captions"
• Product showcase: "Polished 90-second product showcase with close-up cuts on features"
• Captioning: "Add professional captions, translate to English, clean up audio"

Rate Limits & Notes#

• API rate limit: 3 seconds between requests (enforced server-side)
• Upload is async: file continues processing after upload returns
• Processing time: typically 5–20 minutes
• Result URLs expire after 24 hours — download promptly
• For long videos (30+ min): use --timeout 7200