Clipcat - AI Viral Video Maker for TikTok Shop

SKILL.md

---
name: clipcat
description: Clipcat - TikTok e-commerce video creation skill. Video search, product insights, viral replication, product-to-video generation, breakdown analysis, and video download via Clipcat CLI.
user-invocable: true
metadata:
  {
    "openclaw":
      {
        "skillKey": "clipcat",
        "requires": { "env": ["CLIPCAT_API_KEY"] },
        "primaryEnv": "CLIPCAT_API_KEY",
        "install":
          [
            {
              "id": "download-darwin-arm64",
              "kind": "download",
              "os": ["darwin"],
              "arch": ["arm64"],
              "url": "https://static.clipcat.ai/public/cli/v1.0.24/clipcat_darwin_arm64.tar.gz",
              "archive": "tar.gz",
              "bins": ["clipcat"],
              "label": "Install Clipcat CLI (macOS Apple Silicon)",
            },
            {
              "id": "download-darwin-x64",
              "kind": "download",
              "os": ["darwin"],
              "arch": ["x64"],
              "url": "https://static.clipcat.ai/public/cli/v1.0.24/clipcat_darwin_amd64.tar.gz",
              "archive": "tar.gz",
              "bins": ["clipcat"],
              "label": "Install Clipcat CLI (macOS Intel)",
            },
            {
              "id": "download-linux-x64",
              "kind": "download",
              "os": ["linux"],
              "arch": ["x64"],
              "url": "https://static.clipcat.ai/public/cli/v1.0.24/clipcat_linux_amd64.tar.gz",
              "archive": "tar.gz",
              "bins": ["clipcat"],
              "label": "Install Clipcat CLI (Linux x86_64)",
            },
            {
              "id": "download-linux-arm64",
              "kind": "download",
              "os": ["linux"],
              "arch": ["arm64"],
              "url": "https://static.clipcat.ai/public/cli/v1.0.24/clipcat_linux_arm64.tar.gz",
              "archive": "tar.gz",
              "bins": ["clipcat"],
              "label": "Install Clipcat CLI (Linux arm64)",
            },
            {
              "id": "download-windows-x64",
              "kind": "download",
              "os": ["win32"],
              "arch": ["x64"],
              "url": "https://static.clipcat.ai/public/cli/v1.0.24/clipcat_windows_amd64.zip",
              "archive": "zip",
              "bins": ["clipcat.exe"],
              "label": "Install Clipcat CLI (Windows x86_64)",
            },
          ],
      },
    "homepage": "https://clipcat.ai",
  }
---

# Clipcat CLI

Use this skill when you need TikTok e-commerce video creation through `clipcat`.

Get API key: https://clipcat.ai/workspace?modal=settings&tab=apikeys

This skill is intentionally short. Detailed flags and supported values belong to the CLI itself — always treat `clipcat -h` and `clipcat <subcommand> -h` as the primary reference.

## Installation

This skill is auto-installed by OpenClaw using the declared `install` spec in the frontmatter above. OpenClaw downloads the platform-specific binary from versioned, immutable URLs under `https://static.clipcat.ai/public/cli/vX.Y.Z/` and places it under `~/.openclaw/tools/clipcat/`. No remote shell script is executed.

After installation, configure your API key once:

```bash
clipcat config --api-key <your-key> --base-url https://clipcat.ai
```

## What this CLI is for

`clipcat` is the local entrypoint for all Clipcat AI video generation workflows:

- Query TikTok e-commerce data across 6 entity domains: creators, products, shops, videos, lives, and keyword/image search (market intelligence, leaderboards, trends, relationships)
- Replicate viral videos with your product
- Generate product videos from images
- Generate AI images from text prompts using GPT Image 2 (with optional reference images)
- Analyze videos (script, scenes, music)
- Download TikTok/Douyin videos
- Query async task status

## Default agent workflow

1. Start with `clipcat -h` to see all commands.
2. Before using any command, run `clipcat <subcommand> -h` to see flags.
3. Default to JSON output. Only use `--pretty` when the result is meant for human terminal reading.
4. Before any credit-consuming video command, quote the exact cost with
   `clipcat quote`, confirm it with the user, and submit with
   `--expected-credits` (see "Confirming cost before paid video commands").

## Choosing the right command

### TikTok e-commerce data — entity commands

Noun-verb commands: `clipcat <entity> <verb>`. Run `clipcat <entity> -h` for verbs
and `clipcat <entity> <verb> -h` for flags.

- `creator <list|rank|detail|trend|videos|lives|products|followers|following|region|milestones>` — creators/influencers
- `product <list|rank|detail|trend|comments|creators|videos|lives>` — TikTok Shop products
- `seller <list|rank|detail|trend|products|creators|videos|lives>` — TikTok Shop shops
- `video <list|rank|detail|trend|comments|captions|products|hashtag>` — videos
- `live detail` — live-room detail (only while live)
- `find <creators|products|videos|lives|hashtags|music|photo|all>` — keyword/image search; `find all` is the broad fallback

**`--mode offline|realtime`** (only on `creator detail|videos`, `product comments`,
`seller products`, `video detail`): default is the safe choice — omit unless the
user needs latest/current (realtime) vs history/trend/leaderboard (offline). Never
say "offline/realtime" to users; phrase as latest vs historical.

**Pagination**: offline list/rank commands take `--page` / `--page-size` (and
`--max-pages` to auto-fetch several pages); realtime lists take `--offset` /
`--cursor` / `--scroll-param` echoed back from a prior page.

**Data-query playbook (dense):**

- **Chain ids, don't guess them.** Discover first (`<entity> list|rank`, `find …`),
  take the id from the result, then call `detail` / `trend` / relationship verbs.
  Detail verbs take **comma-separated batches** (`--user-ids`, `--product-ids`,
  `--video-ids`, ≤10).
- **Seed relationships from commerce-active entities.** Sub-resource verbs
  (`creator products|lives`, `product creators|videos|lives`, `seller lives`,
  `video products`) return `[]` for low-activity ids. Pull seeds from `… rank` or a
  sorted `… list` (top sales/followers), not an arbitrary row, or expect empties.
- **`… rank` needs a _recent_ `--date`.** Pass any day in the target period — the backend
  auto-snaps it to the period anchor (week→that week's Monday, month→that month's 1st) and
  back to the latest _complete_ period (data is T+1), so a mid-week / mid-month date, or even
  _today_, still resolves. But it must fall within the freshness window keyed to `--rank-type`:
  **day ≤30d, week ≤6mo, month ≤12mo** back from _today_. A too-**old** date (e.g. last year)
  is rejected upstream as `rant_type N only support …` — move it **forward toward today**;
  don't switch rank-type.
- **Category filtering is numeric and split by level.** To scope `rank` / `list` to a
  category, first run `category resolve --keyword <term>` (e.g. `lipstick` / `口红`; CJK
  auto-uses the zh tree). It returns each match's level + ancestor ids `{l1_id, l2_id?,
l3_id?}` (ids work for any region). Pass the id for the level the target command takes:
  **product/seller** rank/list use **L1→`--category-id`, L2→`--category-l2-id`,
  L3→`--category-l3-id`** (`--category-id` is L1-only — don't put an L2/L3 id there);
  **creator** rank takes any level via `--product-category-id`; **video** rank only
  accepts L1 (`l1_id`). Low-confidence `hint` → run `category tree` (L1+L2 overview), pick
  the branch by meaning, then `category tree --parent <that L2 id>` to drill into its L3
  leaves. For plain keyword _search_ (no leaderboard), `find products --keyword` needs no id.
- **`find products` returns product_id only** (it's a search index). For title /
  price / metrics, chain the ids into `product detail`.
- **Empty `[]` / `null` means "none", not an error.** Known thin/quirky:
  `creator region` (unreliable → read `region` from `creator detail` instead),
  `video captions` (many videos have none), `live detail` (only while a room is
  live), `seller products --mode realtime` (empty when no live inventory; the
  offline default already covers it).
- Responses are **server-trimmed to signal** (ids, core metrics, names, key links;
  images already converted to accessible URLs) — no raw-blob handling needed.

### Video generation & tools

- `quote` — return the exact credit cost of one specific generation (`--model` + `--resolution` + `--duration`, plus `--url`/`--social` for a TikTok/Douyin replicate, plus `--enhance` for super-resolution). The primary way to quote a paid command: the server does all the math and hands back `totalCredits` (already includes the enhance fee) plus `enhanceCredits` / `enhanceBlocked` (see "Confirming cost before paid video commands" and "Super-resolution").
- `models` — browse all available video models with their credit costs (discrete → `prices`, range → `creditsPerSecond`) and your balance. Use it when the user hasn't picked a model yet, or an unavailable one is reported.
- `replicate` — replicate a viral video with your product images (auto-detects URL type); images via `--image` (local) or `--image-url` (URL); local files and URLs can be mixed; supports `--model`, `--duration`, `--size` (only `9:16` or `16:9`), `--lang`, `--resolution`, `--enhance` (super-resolution, see below), `--character-id`, `--expected-credits`
- `product_video` — generate video from product images only (no reference video); images via `--image` (local) or `--image-url` (URL); local files and URLs can be mixed; `--size` only accepts `9:16` or `16:9`; supports `--enhance` (super-resolution, see below), `--expected-credits`
- `image` — generate an AI image from a text prompt using **GPT Image 2** model; optionally supply up to 5 reference images via `--image` (local file) or `--image-url` (URL). Use `--aspect-ratio` to pick `1:1` (default) / `16:9` / `9:16`. **Dimension hints (9:16/16:9/1:1, portrait/landscape/square, 竖版/横版/方图, banner, wallpaper) must appear in BOTH `--prompt` and `--aspect-ratio`** — `--aspect-ratio` sets canvas, the prompt hint anchors framing. Don't invent dimensions the user didn't ask for.
- `list_images` — list image generation tasks from server; supports `--status` / `--limit` / `--page` filters
- `breakdown` — analyze a video (script, scenes, music); returns cached result immediately if previously analyzed
- `download` — download TikTok/Douyin video (returns signed URL); cached results return immediately
- `query_task` — check status of a task by ID and type (`--type replicate | product | breakdown | download | image`). Omit `--task-id` to resume the latest local task. With `--enhance`, each `videos[]` item carries its own `status` / `enhanceStatus` (see "Super-resolution").
- `list_tasks` — list recent **video-related** tasks from server (`--type` required: `replicate | product | breakdown | download`). Image tasks use `list_images`.

## Confirming cost before paid video commands

`replicate` and `product_video` consume credits. Always confirm cost first — and
**never compute the credits yourself**, let `clipcat quote` return them:

1. Run `clipcat quote` with the SAME parameters you'll submit (`--model`,
   `--resolution`, `--duration`; for a TikTok/Douyin replicate also pass the
   `--url`, which auto-adds the download surcharge; for super-resolution also pass
   `--enhance`). It returns `totalCredits` (the server does all the math —
   per-second rates, download surcharge, deferred enhance fee) and your
   `remainingCredits`.
2. Show the user the model, duration, resolution and that `totalCredits`, and get
   explicit approval.
3. Submit with `--expected-credits <totalCredits>`. The server rejects the request
   only if the real cost is **higher** than what you pass, so you can never
   overcharge (a cheaper real cost — cache hit, promo — just goes through). On a
   rejection it returns the current cost — re-confirm that number with the user
   and resubmit with the updated `--expected-credits`.

When the user hasn't chosen a model yet (or you need the full menu), run `clipcat
models` to list every available model and its cost, then `clipcat quote` the pick.

Premium models (e.g. `seedance2`, `happyhorse10`) require a paid plan; `clipcat
quote` flags them (`premiumBlocked`) and the server rejects them for free users.

## Super-resolution (`--enhance`)

`replicate` and `product_video` accept `--enhance 720p|1080p|2k` to upscale the
finished video. Rules:

- **Tier must be strictly higher than the generated resolution**: 480p → 720p /
  1080p / 2k, 720p → 1080p / 2k, 1080p → 2k, 2k → no option. The CLI only
  enum-checks the value; the server enforces the tier ladder.
- **Paid plans only.** Free users are rejected on submit; `clipcat quote --enhance`
  flags this as `enhanceBlocked: true` (upgrade needed).
- **Cost** = ceil(duration_sec / 10) × tier rate (`720p`=10, `1080p`=20, `2k`=30
  credits per 10s). It is **deferred** — charged only after the base video
  succeeds. `quote` returns it as `enhanceCredits`, already folded into
  `totalCredits`; submit that `totalCredits` via `--expected-credits`.
- **Status semantics** (`query_task`): once the base video is ready it appears in
  `videos[]` with `status: enhancing` and a usable `videoUrl` (the original), but
  the **task reaches its final completed state only after enhance finishes** (a
  standard 1-min video takes ~6-10 min extra). `enhanceStatus: failed` → the task
  still completes and delivers the original video, and the enhance fee is refunded.

```bash
clipcat quote --model seedance2 --resolution 480p --duration 8 --enhance 1080p
# → seedance2 480p 8s → 320 credits  + 20 enhance (1080p) → total 340 credits
clipcat product_video --image product.jpg --model seedance2 --duration 8 \
  --resolution 480p --size 9:16 --enhance 1080p --expected-credits 340
```

## replicate: URL type auto-detection

`clipcat replicate` automatically detects the URL type:

- **TikTok/Douyin link** → calls `/replicate_from_social` (costs **10 extra credits** for download)
- **Direct video URL** → calls `/replicate`

Always inform the user about the extra credits before running with a social URL.

## clipcat:// asset references

`clipcat://...` strings seen in earlier turns are stable asset references. Pass them **verbatim** to any `--image-url` / `--character-id` flag — never prepend `https://` or modify them. See subcommand `-h` for details.

## Async task rules

`replicate`, `product_video`, `image`, and `breakdown` are async. All four
**submit and return immediately** with a task ID — they never block.

Typical durations: `image` ~3 min, `breakdown` a few minutes, `product_video` /
`replicate` 10+ min. **Never try to wait synchronously inside a single tool
call** — every realistic agent harness has a tool-call timeout (commonly 60s)
that will kill the call long before the task is done. Always go submit → return
→ poll across turns.

1. Task ID is saved locally to `~/.clipcat/tasks.json` automatically.
2. Check status with `clipcat query_task --task-id <id> --type <type>`. Each
   call returns immediately with the current status. Omit `--task-id` to resume
   the latest task. Re-invoke the command across turns (suggested cadence:
   ~30s for `image`, ~1-2 min for `breakdown` / `product_video` / `replicate`)
   until `status` is `completed` or `failed`.
3. Use `clipcat list_tasks --type <replicate|product|breakdown|download>` to
   see tasks of a given type from the server.

## query_task: auto-resume

`clipcat query_task` with no flags automatically reads the latest task from `~/.clipcat/tasks.json` and resumes it. No need to remember task IDs.

## Available models

Trial models are available to all users; standard models require a paid plan.

| Model ID             | Duration            | Resolution        | Notes                                                         |
| -------------------- | ------------------- | ----------------- | ------------------------------------------------------------- |
| `veo3.1fast`         | 8s, 16s, 24s        | 720p, 1080p       | **Trial**. Google Veo 3.1 Fast, balanced quality and cost     |
| `veo3.1pro`          | 8s, 16s, 24s        | 720p, 1080p       | **Trial**. Google Veo 3.1 Pro, high-quality variant           |
| `omini_flash`        | 10s                 | 720p, 1080p       | **Trial**. Gemini Omni Flash, Google's newest model           |
| `grok_imagine`       | 10s, 15s, 20s, 30s  | 720p              | **Trial**, default. 9:16 aspect ratio only, longer clips      |
| `seedance2`          | 4-15s (any integer) | 480p, 720p, 1080p | Standard (paid). ByteDance Seedance 2, top quality            |
| `seedance2_fast`     | 4-15s (any integer) | 480p, 720p, 1080p | Standard (paid). ByteDance Seedance 2 Fast, fast variant      |
| `happyhorse10`       | 3-15s (any integer) | 720p, 1080p       | Standard (paid). Alibaba HappyHorse 1.0                       |
| `sora2_official_exp` | 4s, 8s, 12s         | 720p              | Standard (paid). OpenAI Sora 2 official channel, 9:16 or 16:9 |

Always check `clipcat replicate -h` for the current model list, and `clipcat
models` for the authoritative live per-combination credit costs and your balance.

## Supported languages (`--lang`)

`en` `zh` `fr` `de` `ms` `vi` `th` `ja` `ko` `id` `fil` `es`

## Region (`--region`)

ISO 3166-1 alpha-2, uppercase: `US` `GB` `DE` `ES` `FR` `IT` `JP` `MX` `BR` `ID` `MY` `PH` `SG` `TH` `VN`. Server-enforced; an out-of-range code returns the current allowed list.

## Good agent behavior

- Run `clipcat -h` first if unsure which command to use.
- For paid video commands (`replicate`, `product_video`): quote the exact cost with `clipcat quote` (same params you'll submit), show the user the model / duration / resolution / `totalCredits`, get explicit approval, then submit with `--expected-credits <totalCredits>`. Never compute the credits yourself — let `clipcat quote` return them.
- Keep record of task IDs; re-invoke `query_task` across turns to track long-running tasks.
- Preserve signed video URLs intact — they contain `X-Amz-*` params that break if truncated.
- Agents should prefer the default JSON output.
- Use `--pretty` only for human-facing terminal display.