### If the key is missing — how to get one

1. **Request a key:** Email `[email protected]` with your use case. You will receive a key like `sk_live_xxxx`.
2. **Configure the key** using ONE of these methods (in order of preference):

**Method 1 — OpenClaw config (recommended, persists across restarts):**

> **Important for agents:** After setting the key via shell profile or .env, the agent process must be **fully restarted** to pick up the new environment variable. Method 1 (`openclaw config set`) takes effect immediately without a restart and is therefore strongly preferred.

### Verify the key works

---

## Tools

### Tool 4 (Recommended): End-to-End Edit

**Use when:** the user wants to process a video from start to finish — **this is the primary tool for almost all requests.**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `file_path` | Yes | Local path to `.mp4` or `.mov` file |
| `tips` | Yes | Comma-separated style tip IDs (e.g. `"1,2,3"`) |
| `user_prompt` | No | Free-text creative direction (e.g. `"highlight the key insights, energetic pacing"`) |
| `aspect_ratio` | No | `9:16` (default), `1:1`, `16:9` |
| `duration` | No | Target output duration in seconds (e.g. `120` for 2 minutes) |

**Tips reference (use the most relevant IDs):**

| ID | Style |
|----|-------|
| `1` | Energetic / fast-paced |
| `2` | Cinematic / slow motion |
| `3` | Highlight reel / best moments |
| `4` | Talking-head / interview |

**Environment overrides:**

| Variable | Default | Description |
|----------|---------|-------------|
| `WORKFLOW_TIMEOUT` | `3600` | Max seconds to wait for project completion |
| `ASSET_TIMEOUT` | `60` | Max seconds to wait for asset upload |

**Example — 2-minute vertical highlight reel:**

---

### Tool 1: Upload Video Asset

**Use when:** uploading a file separately to get an `object_key` for use in Tool 2.

Validates file locally (mp4/mov, ≤ 3 GB) before uploading. Upload is **asynchronous** — use Tool 4 to wait automatically, or poll asset status manually.

---

### Tool 2: Create Video Project

**Use when:** you already have an `object_key` and want to start AI processing.

**Error 453 — concurrent limit:** wait for a running project to complete, or use Tool 4 which retries automatically.

---

### Tool 3: Check Project Status

**Use when:** polling an existing `project_id` for completion.

**Project status values:** `INIT` → `CHAT` → `PLAN` → `QUEUED` → `EXECUTOR` → `COMPLETED` / `FAILED`

---

## Error Reference

| Code | Meaning | Resolution |
|------|---------|------------|
| `401` | Invalid or missing `SPARKI_API_KEY` | Run the key verification command above; reconfigure via `openclaw config set` |
| `403` | API key lacks permission | Contact `[email protected]` |
| `413` | File too large or storage quota exceeded | Use a file ≤ 3 GB or contact support to increase quota |
| `453` | Too many concurrent projects | Wait for an in-progress project to complete; Tool 4 handles this automatically |
| `500` | Internal server error | Retry after 30 seconds |

---

## Rate Limits & Async Notes

- **Rate limit:** 3 seconds between API requests (enforced automatically in all scripts)
- **Upload is async:** after `upload_asset.sh` returns, the file continues uploading in the background — Tool 4 waits automatically
- **Processing time:** typically 5–20 minutes depending on video length and server load
- **Result URL expiry:** download URLs expire after **24 hours** — download or share promptly
- **Long videos:** set `WORKFLOW_TIMEOUT=7200` for videos over 30 minutes

---

Powered by [Sparki](https://sparki.io) — AI video editing for everyone.

metadata:
  clawdbot:
    requires:
      env:
        - SPARKI_API_KEY
      bins:
        - curl
        - jq
    primaryEnv: SPARKI_API_KEY
    emoji: 🎬
    homepage: https://sparki.io
    os: [darwin, linux]
    always: false
---

# ai-video-editor

> One-for-all AI video editing — Copy Style ✂️ · Long to Short 🔤 · AI Caption 🎙️ · AI Commentary 📐 · Video Resizer · Highlight Reels ⚽ · Vlog · Montage · Talking-head — upload, process, and retrieve in one command.

## Overview

**Use this Skill when** the user wants to:
- **Copy Style** — replicate a creator's editing rhythm, color grading, or pacing
- **Long to Short** — cut a long video into shareable short-form clips (Reels, Shorts, TikTok)
- **AI Caption / AI Commentary** — add auto-generated subtitles or voice-over commentary
- **Video Resizer** — reformat footage for different platforms (vertical 9:16, square 1:1, landscape 16:9)
- **Highlight Reels** — extract the best moments from sports, events, or recordings ⚽
- **Vlog / Montage / Talking-head** — produce polished content from raw footage with a single prompt
- Automate batch video production or content creation pipelines
- Apply a style, tone, or creative direction to existing video via natural language

**What this Skill does:**
- Uploads video files (mp4/mov, up to 3 GB) to cloud storage
- Creates an AI video processing project with style tips and custom parameters
- Polls until the processed video is ready, then returns a download URL
- Handles the full async workflow: upload → process → retrieve

**Supported aspect ratios:** `9:16` (vertical/Reels), `1:1` (square), `16:9` (landscape)

---

## Prerequisites

Set your Sparki Business API key as an environment variable:

No other configuration is needed. All requests go to `https://agent-api-test.aicoding.live`.

---

## Tools

### Tool 4 (Recommended): End-to-End Workflow

**Use when:** the user wants to process a video from start to finish — this is the primary tool for most requests.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `file_path` | Yes | Local path to `.mp4` or `.mov` file |
| `tips` | Yes | Comma-separated style tip IDs (e.g. `"1,2"`) |
| `user_prompt` | No | Free-text creative direction |
| `aspect_ratio` | No | `9:16` (default), `1:1`, `16:9` |
| `duration` | No | Target output duration in seconds |

**Environment overrides:**

| Variable | Default | Description |
|----------|---------|-------------|
| `WORKFLOW_TIMEOUT` | `3600` | Max seconds to wait for project completion |
| `ASSET_TIMEOUT` | `60` | Max seconds to wait for asset upload |

**Example — vertical short-form video:**