sparki-video-editor（火花视频编辑器）

Sparki Video Editor

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.

VERIFY SKILL VERSION BEFORE RUNNING COMMANDS. Compare the skill_version value in sparki doctor's output against the version: field at the top of this SKILL.md (currently 1.1.0). If they do not match, the SKILL.md you are reading is stale — stop, tell the user the skill must be reloaded (the updated file has different commands or options), and do not run any sparki command until the two versions agree.

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.

Step 0: Run Doctor and Verify Version (ALWAYS FIRST)

Before any other command in a new conversation, run:

sparki doctor

sparki doctor checks the CLI install, API key, base URL, config directory, and reports the installed skill version (skill_version check).

IMPORTANT — version consistency check. Take the skill_version value from doctor's output and compare it against the version: field at the top of this SKILL.md (the frontmatter shows version: 1.1.0). If the two values disagree:

• You are looking at a stale SKILL.md that does not describe the installed

skill. Commands, options, and styles may have changed.

• Stop. Tell the user: "Skill version on disk is X but this SKILL.md

is Y — I need the updated SKILL.md before I can run sparki commands."

• Do not run any sparki command until the two versions match.

All other doctor checks must also pass before you proceed. If any check fails, follow the action field of that check in the output.

If doctor reports the CLI is outdated:

uv tool install --upgrade sparki-cli
sparki doctor

If the CLI upgrade raises the installed skill to a newer version than this SKILL.md, the version-check above will fire — stop and request the refreshed SKILL.md.

If doctor reports api_key is missing, go to Step 1: First-Time Setup. If api_key is valid but base_url doesn't match the skill manifest, re-run sparki setup --base-url <correct-url>.

Step 1: First-Time Setup (only if doctor said api_key is missing)

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

After running sparki setup --api-key <KEY>, run sparki doctor again to confirm. Once doctor passes, send the user two separate messages:

Message 1 — tell the user:

"Sparki is ready! 🎬 I can edit your videos in three 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 3. Style-Clone — provide a reference video and I'll clone its style Available styles: 🎬 Vlog: daily · travel · sports · chill-vibe ✂️ Clips: long-to-short · highlight-reel 🎙 Narrative: podcast-interview · funny-commentary · master-storyteller 🛠 Tools: ai-captions · ai-translation To get started, provide 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

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 Handling Multiple Files below, then 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 list to find the uploaded asset's object_key
4. Run sparki edit <object_key> [<object_key2>...] --mode ... to create the project (positional; see Handling Multiple Files / Keys)
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 3. Style-Clone — provide a reference video and I'll clone its style"

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

If the user selects Style-Clone, ask how they want to provide the reference video:

"How would you like to provide the reference video? 1. Video link — paste a link from TikTok, Instagram, X, or Facebook 2. Upload via Telegram — upload through the Mini App 3. Local file — provide a file path"

Step 4: Determine What the User Wants

Handling Multiple Files / Keys

The same decision rule applies to both sparki run (local files, Mode A) and sparki edit (already-uploaded object keys, Mode B) — identify which scenario before running.

A. Multiple inputs → ONE output (combine into a single project)

When the user says "make ONE highlight reel / montage / supercut from these clips", pass all inputs in a single call.

Mode A — local files with sparki run:

sparki run a.mp4 b.mp4 c.mp4 \
  --mode style-guided --style clips/highlight-reel

Shell glob works: sparki run *.mp4 .... Or use --dir:

sparki run --dir ./clips \
  --mode style-guided --style clips/highlight-reel

Mode B — already-uploaded keys with sparki edit:

sparki edit \
  assets/98/a.mp4 assets/98/b.mp4 assets/98/c.mp4 \
  --mode style-guided --style clips/highlight-reel

Positional object-keys work the same way — all of them become source resources of ONE project.

B. Multiple inputs → N independent outputs (separate projects)

When the user says "edit EACH of these videos as a vlog" or similar, call the command once per input.

Mode A — loop on sparki run:

sparki run clip1.mp4 --mode style-guided --style vlog/daily
sparki run clip2.mp4 --mode style-guided --style vlog/daily

Mode B — loop on sparki edit:

sparki edit assets/98/a.mp4 --mode style-guided --style vlog/daily
sparki edit assets/98/b.mp4 --mode style-guided --style vlog/daily

Decision rule

• "Combine / merge / into one" → scenario A (single call, all inputs positional)
• "Each / separately / N videos" → scenario B (loop, one input per call)
• Ambiguous → ask the user: "Do you want one combined output, or one output per video?"

This rule applies uniformly: sparki run for local files, sparki edit for already-uploaded object keys from Telegram Mini App.

Reliability (sparki run)

Every file has automatic retry (3 attempts, exponential backoff). On partial upload failure, sparki run proceeds with the successful files and warns to stderr. Pass --strict to abort if any file fails.

Tuning flags:

• --max-retries N (default 3; 0 disables)
• --upload-timeout SEC (default 600)
• --quiet to suppress progress on stderr

sparki edit does not upload, so these flags don't apply.

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 /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 /path/to/video.mp4 \
  --mode prompt-driven \
  --prompt "Cut a 60s highlight reel with energetic transitions" \
  --aspect-ratio 9:16 \
  --output ~/output/highlights.mp4

# Style-Clone with reference URL
sparki run /path/to/video.mp4 \
  --mode style-clone \
  --reference-url "https://www.tiktok.com/@user/video/123" \
  --aspect-ratio 9:16 \
  --output ~/output/cloned.mp4

# Style-Clone with local reference file
sparki run /path/to/video.mp4 \
  --mode style-clone \
  --reference-file /path/to/reference.mp4 \
  --aspect-ratio 9:16 \
  --output ~/output/cloned.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 · travel · sports · chill-vibe ✂️ Clips: long-to-short · highlight-reel 🎙 Narrative: podcast-interview · funny-commentary · master-storyteller 🛠 Tools: ai-captions · ai-translation

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

• vlog/daily — Day-in-the-life vlogs, event recaps, and BTS content
• vlog/travel — Vacations, road trips, city breaks, multi-stop trips
• vlog/sports — Game highlights, match recaps, performance reels
• vlog/chill-vibe — Morning routines, slow living, aesthetic content
• clips/long-to-short — Find a long video's best moments and turn them into a short
• clips/highlight-reel — Curate best moments into a beat-synced montage (trip recaps, weekend memories)
• narrative/podcast-interview — Trim filler/pauses from podcasts, sit-down interviews, panels
• narrative/funny-commentary — Write & voice hilarious commentary (movie recaps, reactions)
• narrative/master-storyteller — Narrate with dramatic arcs & emotional depth (movie narration, documentary edits)
• tools/ai-captions — Generate timed, styled captions from dialogue
• tools/ai-translation — Add captions in a chosen target language from dialogue

Other Commands

sparki doctor — Self-check

sparki doctor
sparki doctor --json     # JSON-only output (for parsing)
sparki doctor --fix      # Attempt to auto-fix (e.g. mkdir config dir)

Checks CLI install, PyPI version freshness, API key validity, base URL match with skill manifest, and config directory writability. Always run this first after install or update.

sparki upload — Upload files separately

# Positional (recommended)
sparki upload clip1.mp4 clip2.mp4
sparki upload *.mp4

# Directory
sparki upload --dir ./clips

Returns object keys for use with sparki edit. On partial failure, returns assets (successes) and failures (errors). Flags: --max-retries, --upload-timeout, --quiet.

sparki assets list — List uploaded assets

sparki assets list
sparki assets list --limit 10

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

sparki assets delete — Delete uploaded assets

# Specific object keys (preferred)
sparki assets delete assets/98/abc.mp4 assets/98/def.mp4

# By backend-stored file_name (NOT the user's original uploaded filename)
sparki assets delete --name 1f43c9915ed547128a621581cf7d9f20.mp4

# Clear ALL uploaded assets — requires --yes
sparki assets delete --all --yes

About --name. The value must be the backend-stored file_name field returned by sparki assets list — that value is a hashed basename of the object_key (e.g. 1f43c9915ed547128a621581cf7d9f20.mp4), not the original filename the user uploaded (the backend does not persist the original name). When the user asks to "delete clip_3.mp4" by its original name, the agent should first sparki assets list, find the asset whose upload context matched that clip, and then pass either the object_key (positional — simpler) or the file_name (via --name). If nothing matches, the CLI emits NO_MATCH.

Use this when the user says storage is full or wants to clean up old uploads. Assets currently being used by active projects are skipped automatically (reported in the skipped field).

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

Accepts object keys as positional args. For multi-input semantics, re-read Handling Multiple Files / Keys above.

# Single source key (scenario B pattern — one output per call)
sparki edit assets/98/abc123.mp4 \
  --mode style-guided \
  --style clips/highlight-reel \
  --aspect-ratio 9:16

# Multiple source keys combined into ONE output (scenario A)
sparki edit \
  assets/98/a.mp4 assets/98/b.mp4 assets/98/c.mp4 \
  --mode style-guided \
  --style clips/highlight-reel

# Style-Clone with reference URL
sparki edit assets/98/abc123.mp4 \
  --mode style-clone \
  --reference-url "https://www.tiktok.com/@user/video/123"

# Style-Clone: get Telegram upload link for reference video
sparki edit assets/98/abc123.mp4 \
  --mode style-clone \
  --reference-tg

When using --reference-tg, the command returns an upload link (no project is created yet). Send the upload link to the user and ask them to upload their reference video via the Telegram Mini App. Once the user confirms the upload is complete, proceed with sparki edit --mode style-clone --reference-url <url> or --reference-file to create the project.

edit parameters:

Other options (--style, --prompt, --aspect-ratio, --duration-range, --reference-url, --reference-file) mirror sparki run.

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

Note: Style-clone projects use a shorter lifecycle: INIT → EXECUTOR → COMPLETED / FAILED / CANCEL (no CHAT/PLAN/QUEUED stages).

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

Managing Storage

If the user reports storage is full, or an upload fails with STORAGE_FULL (asset storage quota exceeded):

1. Run sparki assets list --limit 50 to inspect what's stored. Note the

object_key and file_name of each asset you may want to delete.

1. Suggest deleting old / unused assets:

- By object_key (preferred): sparki assets delete assets/98/abc.mp4 assets/98/def.mp4 - By file_name (the hashed basename from sparki assets list, not the user's original filename): sparki assets delete --name 1f43c9915ed547128a621581cf7d9f20.mp4 - Full wipe: sparki assets delete --all --yes (confirm with user first).

1. As an alternative, let the user know they can manage assets from the web

UI at https://sparki.io (same account).

1. Assets in use by active projects are skipped — tell the user to wait for

those to finish, or cancel them.

Out of Credits

If any command returns QUOTA_EXCEEDED (not enough credits to process a video), tell the user there are two ways to top up:

• Fastest — Sparki Telegram Bot: open https://t.me/Sparki_AI_bot in

Telegram and run /topup. The credits purchase popup opens directly in the chat.

• Web — upgrade plan: visit https://sparki.io/ to pick a larger

plan.

After top-up, retry the failed command.

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

Support

If you encounter any issues or have feature requests, please contact us at support@sparki.io