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:

# 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

Quick Start — sparki run

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

# 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:

Output:

{
  "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

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

Returns object keys for use with sparki edit.

sparki assets — List uploaded assets

sparki assets
sparki assets --limit 10

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

sparki upload-tg — Get Telegram upload link

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

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

sparki status --task-id <task_id>

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

sparki download — Download completed result

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

sparki history — List recent projects

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:

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

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