Sparki

View saved version →

---
name: sparki-video-editor
description: AI video editor for creators. Transform raw footage into polished vlogs, talking-head videos, or social media content (TikTok/Shorts/Reels). From cloning a reference style to natural language editing, simply describe your vision and let Sparki handle the rest. Runs on the cloud-hosted Sparki API — no local rendering, no ffmpeg.
---

# Sparki Video Editor

Skill version: 1.1.7

Use this skill whenever the user asks to edit, clip, caption, translate, or
reformat video. Sparki renders in the cloud; never use ffmpeg or a local video
renderer.

## 1. Choose one runtime

Do this before setup or editing:

- **Codex browser / hosted cloud workspace:** use the bundled Web Runner. Do
  not install `uv`, pip packages, or `sparki-cli`.
- **Codex desktop app / local terminal:** use the Local CLI.
- **Uncertain:** a chat attachment under a disposable workspace means Web
  Runner. Otherwise ask one short question before installing software.

Always write results to `./sparki-output/<name>.mp4` in the current working
directory. A browser workspace is not the user's computer: attach the finished
MP4 to the conversation and also report its `local_path` and
`output_directory`.

## 2. Browser / hosted Codex

Resolve `scripts/sparki_web_runner.py` relative to this `SKILL.md`. Use
`python3 -B`, or `python -B` only when it is Python 3. Never guess or copy the
runner path.

### Connect

```bash
python3 -B <skill-dir>/scripts/sparki_web_runner.py probe
python3 -B <skill-dir>/scripts/sparki_web_runner.py authorize --channel codex --state ./sparki-output/.sparki-web-auth.json
```

Show the returned `authorization_url`. Ask the user to sign in at Sparki and
approve access. Never ask for an API key. Reuse the same state and URL while it
is unexpired; do not add `--force` for a pending authorization. The runner keeps
the exchanged key in memory only and removes the state after exchange.

If `probe` fails, explain that the hosted environment cannot reach
`agent-api.sparki.io`; installing packages is not a workaround.

### Confirm and edit

Browser approval grants account access but does not authorize a paid editing
task. Before `run`, ask the user to approve creating the potentially paid
project. Add `--confirm-charge` only after they agree.

Choose one mode:

- `style-guided`: a known format; requires `--style`.
- `prompt-driven`: free-form instructions; requires `--prompt`.
- `style-clone`: copy one reference; requires exactly one of
  `--reference-url` or `--reference-file`.

Examples:

```bash
python3 -B <runner> run input.mp4 --state ./sparki-output/.sparki-web-auth.json --mode style-guided --style clips/highlight-reel --aspect-ratio 9:16 --output ./sparki-output/highlight.mp4 --confirm-charge
python3 -B <runner> run input.mp4 --state ./sparki-output/.sparki-web-auth.json --mode prompt-driven --prompt "Create a concise vertical travel reel" --aspect-ratio 9:16 --output ./sparki-output/travel.mp4 --confirm-charge
python3 -B <runner> run input.mp4 --state ./sparki-output/.sparki-web-auth.json --mode style-clone --reference-file reference.mp4 --aspect-ratio 9:16 --output ./sparki-output/cloned.mp4 --confirm-charge
```

Multiple positional inputs create one combined output. To create separate
outputs, run one authorized project per input. Ask if intent is ambiguous.

### Recover without duplicate charges

If `run` returns `AUTHORIZATION_PENDING`, show the same returned URL and retry
the same command only after approval.

If an error after project creation contains `task_id`, `mode`, and `output`, do
not run the full edit again. Create a fresh browser authorization, have the
user approve it, then resume the existing project:

```bash
python3 -B <runner> authorize --channel codex --state ./sparki-output/.sparki-web-auth.json
python3 -B <runner> resume --state ./sparki-output/.sparki-web-auth.json --task-id <task-id> --mode <mode> --o

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.