19926533763/clipcat-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Clipcat skill

Browse Source
This commit is contained in:
19926533763
2026-09-02 14:17:59 +08:00
commit 66dfe5d74d
3 changed files with 821 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+152
View File
@@ -0,0 +1,152 @@
# Clipcat Skill
Clipcat is a TikTok e-commerce AI video creation skill that **any AI agent can integrate** — Claude Code, OpenClaw, Cursor, or your own custom agent. It ships as a single cross-platform `clipcat` CLI plus a `SKILL.md` manifest: the agent calls `clipcat` commands to complete viral video discovery, TikTok Shop market intelligence, video analysis, viral replication, product video generation, AI image generation, and TikTok video download — all in one workflow.
For the latest guide and examples, see: [https://clipcat.ai](https://clipcat.ai)
## How It Works
Clipcat is just a small CLI binary and a `SKILL.md` skill manifest, so any agent that can run shell commands can drive it:
- The agent reads `SKILL.md` to learn the available commands and conventions.
- It runs `clipcat <command>` and parses the JSON output (default).
- Async tasks (video / image generation) submit immediately and are polled across turns.
OpenClaw auto-installs the skill from the manifest; any other agent installs the CLI manually (see below). Either way the runtime is the same `clipcat` binary.
## Core Capabilities
- **TikTok E-commerce Data Intelligence**: Query 6 entity domains — creators, products, shops, videos, lives, and keyword/image search — covering leaderboards, multi-filter discovery, trends, detail, reviews, comments, and cross-entity relationships (the agent picks the exact command via `clipcat <entity> -h`)
- **Video Analysis**: Extract scripts, scenes, hooks, and music from TikTok or Douyin videos
- **Viral Replication**: Recreate proven viral structures with your own product assets (auto-detects TikTok/Douyin links vs direct video URLs)
- **Product to Video**: Turn product images into UGC-style TikTok videos
- **AI Image Generation**: Generate AI images from text prompts using GPT Image 2, with optional reference images (up to 5)
- **Video Download**: Download TikTok or Douyin videos through the Clipcat API
## Installation
### 1. Install the CLI
**OpenClaw** — auto-installed from the skill manifest; no manual step needed.
**Any other agent / manual** — install the CLI binary:
```bash
# Install the clipcat CLI
curl -fsSL https://clipcat.ai/cli | bash
```
### 2. Get Your API Key
Sign up or log in, then generate an API key in your personal center:
[Generate API Key](https://clipcat.ai/workspace?modal=settings&tab=apikeys)
### 3. Configure Your API Key
Configure the key once on the machine the agent runs on:
```bash
clipcat config --api-key your_api_key_here --base-url https://clipcat.ai
```
Agents that manage secrets via environment variables can instead set `CLIPCAT_API_KEY` (e.g. OpenClaw: `openclaw env set CLIPCAT_API_KEY your_api_key_here`).
## Usage
Once installed, you can ask your agent to:
- "Search viral TikTok videos about lip gloss this week"
- "Search TikTok Shop for trending pet products and show me competitor shops"
- "Replicate this TikTok video with my product images"
- "Generate a product video from these images"
- "Generate an AI image of a model holding my product"
- "Analyze this video and extract the script"
- "Show me this TikTok user's recent videos with engagement stats"
- "Download this TikTok video"
- "Fetch TikTok Shop product detail and review highlights for this product URL"
## Important Notes
- Video generation tasks are asynchronous and may take several minutes
- Before submitting a task that consumes credits, the agent quotes the exact cost with `clipcat quote`, shows you the model / duration / resolution / credits, and waits for your confirmation
- Do not retry tasks manually; Clipcat already includes retry handling
- Preserve complete TikTok or Douyin URLs, including signed parameters when present
## Supported Models
- `grok_imagine` - 10s, 15s, 20s, 30s (720p, 9:16 only) — default, longer clips
- `veo3.1fast` - 8s, 16s, 24s (720p, 1080p) — balanced quality and cost
- `sora2_official_exp` - 4s, 8s, 12s (720p, 9:16 or 16:9) — paid only, OpenAI Sora 2 official channel
Run `clipcat models` for the full available-model list with the exact per-combination credit cost and your balance; `clipcat replicate -h` also lists models.
## Supported Languages
English, Chinese, French, German, Malay, Vietnamese, Thai, Japanese, Korean, Indonesian, Filipino
## Usage Examples
### Example 1: Search for Viral TikTok Videos
```
Search for viral TikTok videos about lip gloss in the US market this week.
Show me the top 10 results sorted by likes.
```
Returns a ranked list of relevant viral videos, including core metrics and source links for further analysis.
### Example 2: Replicate a TikTok Video
```
Replicate this TikTok video with my product:
https://www.tiktok.com/@username/video/123456789
Use these product images:
- /path/to/product1.jpg
- /path/to/product2.jpg
Generate a 16-second video in English using veo3.1fast model.
```
The agent will display the parameters and wait for confirmation before submitting the task.
### Example 3: Generate Product Video from Scratch
```
Create a 10-second OOTD video featuring a British girl showcasing my product.
Product image: /path/to/dress.jpg
Use veo3.1fast model, 9:16 aspect ratio, English language.
```
### Example 4: Analyze a Video
```
Analyze this video and extract the script, scenes, and music information:
https://www.tiktok.com/@username/video/987654321
```
Returns structured data including scene-by-scene breakdown, visual descriptions, voiceover content, and background music.
### Example 5: Download a TikTok Video
```
Download this TikTok video:
https://www.tiktok.com/@username/video/111222333
```
Synchronous operation, returns direct video URL immediately.
## Tips
- Always provide complete TikTok/Douyin URLs
- Be specific with prompts for better results
- Wait for task completion - video generation takes time
- Preserve complete video URLs with all signed parameters
- Choose appropriate models based on duration and quality needs
## Links
- Homepage: https://clipcat.ai
- OpenClaw one-click install: https://clipcat.ai/tiktok/openclaw
- Command reference: See SKILL.md for the detailed command reference
SKILL.md
+517
View File
@@ -0,0 +1,517 @@
---
name: clipcat
description: All-in-one TikTok Shop selling-video skill for any AI agent (Claude Code, Codex, WorkBuddy, OpenClaw). Find viral TikTok videos, research TikTok Shop products, shops, creators and live rooms, break down why a video sells (script, scenes, hooks, music), search the largest library of real high-GMV AI selling videos and their reverse-engineered prompts and turn the closest match into a ready-to-shoot prompt for your own product, replicate a winning video with your own product, turn product photos into AI selling / UGC / talking-head / product-demo videos, generate e-commerce images from a text prompt, upscale results to 1080p or 2K, and download TikTok or Douyin videos. Keywords — AI selling video, TikTok viral replication, find viral TikTok videos, TikTok Shop product research, competitor shop analysis, creator and influencer ranking, viral selling-prompt generator, AI selling video prompt library, TikTok video prompt search, product-to-video, UGC video generator, talking-head video, AI product image, TikTok video downloader. Use whenever the user needs TikTok e-commerce data, viral video research, or AI video/image generation.
user-invocable: true
metadata:
{
"openclaw":
{
"requires": { "env": ["CLIPCAT_API_KEY"] },
"primaryEnv": "CLIPCAT_API_KEY",
},
"homepage": "https://clipcat.ai",
}
---
# Clipcat CLI
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. The one thing `-h` cannot be current about is the model catalog: models come and go between releases, so `clipcat models` is the authority on which models, resolutions and durations exist right now.
## Installation
Run `clipcat --version` first — if it prints a version, clipcat is installed; skip to API key. If the command is missing, install for the platform:
macOS / Linux / Git Bash:
```bash
curl -fsSL https://clipcat.ai/cli | bash
```
Windows (PowerShell, no bash):
```powershell
irm https://clipcat.ai/cli.ps1 | iex
```
Then set the API key (see below). Update later with `clipcat update` (re-runs the installer; your saved config is preserved).
### Windows sandbox note (Codex etc.)
If the Windows install fails with `SEC_E_NO_CREDENTIALS`, `AcquireCredentialsHandle`, `0x8009030E`, "The underlying connection was closed", or 「基础连接已经关闭」, you are in a restricted sandbox (e.g. the Codex Windows sandbox) where the Windows TLS stack (Schannel) can't open credentials — `Invoke-WebRequest` and system `curl.exe` both fail there. The installer automatically retries the download through Node (its OpenSSL bypasses Schannel), so installing Node in the sandbox usually fixes it. If it still fails, **show the install command to the user and ask them to run it in a normal PowerShell outside the sandbox, or to approve running it outside the sandbox — do not keep retrying with different commands.**
## API key
Configure the key in the local config file — the only reliable method:
```bash
clipcat config --api-key <your-key> --base-url https://clipcat.ai
```
Get the key at https://clipcat.ai/workspace?modal=settings&tab=apikeys. Prefer the config file over the `CLIPCAT_API_KEY` environment variable: sandboxed agents (e.g. Codex) filter out env vars whose names contain KEY/SECRET/TOKEN, so it is usually invisible there. (OpenClaw injects `CLIPCAT_API_KEY` automatically; when set, it overrides the config file.)
## What this CLI is for
`clipcat` is the local entrypoint for all Clipcat AI video generation workflows:
- Query TikTok e-commerce data: creators, products, shops, videos, lives, search
- Generate a ready-to-shoot selling-video prompt from the viral prompt library
- 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.
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").
5. If any command prints an update notice on stderr (`⬆ clipcat X is
available … Run: clipcat update`), run `clipcat update` once, then continue.
It self-skips when already up to date, so it is safe to run.
## Choosing the right command
### TikTok e-commerce data — entity commands
These are noun-verb commands: `clipcat <entity> <verb>`. Run `clipcat <entity> -h`
to list verbs and `clipcat <entity> <verb> -h` for flags.
- `creator <list|rank|profile|enrich|trend|posts|sales-videos|lives|products|followers|following|region|milestones>` — TikTok creators/influencers
- `product <list|rank|detail|trend|reviews|live-comments|creators|videos|lives>` — TikTok Shop products
- `seller <list|rank|detail|trend|catalog|inventory|creators|videos|lives>` — TikTok Shop shops
- `video <list|rank|snapshot|sales|trend|comments|captions|products|hashtag>` — TikTok 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
**Two data sources, and the command name already picks one for you.** There is no
`--mode` flag to reason about — pick by what you need back:
| You need | Command | What you get | What you don't |
|---|---|---|---|
| A creator's recent posts | `creator posts` | any public creator, newest first | no per-video sales/GMV |
| A creator's shoppable videos | `creator sales-videos` | sales + GMV per video, sortable | only creators in the historical dataset |
| A creator's profile now | `creator profile` | any public creator | no cumulative commerce metrics |
| Commerce metrics for many creators | `creator enrich` | batch ≤10, cumulative metrics | only collected creators |
| One video's current state | `video snapshot` | any public video | no sales/GMV |
| Sales for videos you already have ids for | `video sales` | batch ≤10, sales + GMV | only collected videos |
| Reviews you can filter by rating | `product reviews` | rating filters, paging | slightly staler |
| The freshest comments | `product live-comments` | latest, needs `--region` | no rating filter |
| A shop's history incl. removed items | `seller catalog` | sales + GMV, sortable | not what's listed right now |
| What a shop lists right now | `seller inventory` | current, needs `--region` | no sales/GMV |
**The historical dataset does not cover everything** (collection is capped by cost),
so the `sales` / `catalog` / `enrich` side answers "not collected" fairly often —
roughly 4-6 times in 10 when the id came from a live search. Ids taken from
`… rank` / `… list` are in the dataset by construction and hit nearly every time.
An empty result there means *not collected*, not *does not exist* — check with the
live command instead of retrying. Never expose the words offline/realtime to end
users; say historical vs. latest data.
**Pagination**: each call returns one page and is billed once. Historical
list/rank commands take `--page` / `--page-size` (**`--page-size` maxes out at 10**;
larger values are clamped and the response says so in `pagination_corrected` — get
more rows with `--page 2`, `--page 3`, …); live lists take `--offset` /
`--cursor` / `--scroll-param` echoed back from a prior page. Fetch more by
repeating the command page by page (`--max-pages` is deprecated and ignored).
**The two data sources do not share a paging scheme.** Historical commands
(`creator sales-videos`, `product reviews`, `seller catalog`) page by number; their
live counterparts (`creator posts`, `product live-comments`, `seller inventory`)
page by cursor, and a page number cannot become a cursor. If you page a live list
with `--page`, the CLI rejects it outright; if an older client sends it anyway,
the response carries `pagination_ignored` — that means **this is the source's first
page**, not the page you asked for. Stop paging by your original number and continue
with the token in `next`; repeating the number returns the same rows and bills 6
credits again.
**Empty is an answer, not a failure.** The historical dataset does not cover
everything, so an empty result usually means "not in that dataset" rather than "no
such thing". The response then carries `try_instead` with a ready-to-run command for
the other source, plus what you gain (live: full coverage, no sales/GMV; historical:
sales/GMV and sorting, covered entities only) and any flags you still need to add.
Switching sources is a separate billed call — switch only if you need those fields.
Do not retry the same empty query.
**Errors tell you whether to retry.** Failures carry `error_kind` and `retryable`:
`transient` (rate limit or a brief wobble — retry the same command in a few
seconds), `invalid_params` (the message says exactly what is wrong — fix the flag,
never retry as-is), `temporarily_unavailable` (retrying will not help; change the
query or come back later).
**Insufficient credits**: read commands cost 6 credits each (`prompt search` is 3, charged only after the free allowance included with your plan is used up); below that balance they error out and return no data.
**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.
Batch verbs take **comma-separated ids** (`--user-ids`, `--product-ids`,
`--video-ids`, ≤10).
- **Where the id came from decides which command can answer.** Ids from `find …`
(live search) are any public entity, so follow them with the live commands —
`video snapshot`, `creator posts`, `creator profile`. Ids from `… rank` / `… list`
are in the historical dataset by construction, so those are the ones to follow with
`video sales`, `creator sales-videos`, `creator enrich`, `seller catalog`. Running a
live-search id straight into a sales command is the single most common way to burn
credits on empty results — a `find videos` id misses the sales dataset about 4 times
in 10. If you need sales figures for something you found live, say so plainly rather
than paging for data that was never collected.
- **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).
It never silently serves a *different* period: if the period hasn't ended, or its data
isn't generated yet (T+1, usually after midday), you get `data: []` plus `period`
(`requested` / `latest_available` / `previous`, each with `anchor`/`start`/`end`) and a
`hint` naming the exact `--date` to retry with — follow it instead of re-querying the same
period. The date 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).
The levels you pass must form **one parent-child chain**; a repeated or mismatched id is
rejected locally (costs nothing) with the offending fields in `issues` and the correct ids
in `suggested` — copy those and resend. Each entry in `issues` carries `field`, `reason`,
`value`, a localized `message`, and a structured `detail` (the machine-readable form of
the same thing — prefer `detail` when branching in code, `message` when showing a human). Then:
**creator** rank takes any level via `--product-category-id`; **video** rank only
accepts L1 (`l1_id`) — pass an L2/L3 id there and it is auto-lifted to its L1 ancestor,
which **widens** the filter (the response says so in `category_level_corrected`). 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.** A repeat of the same empty query may
come back with `cached: true` + `retry_after` (an ISO timestamp): the backend remembered
that this filter has no data and re-probes automatically after that time — don't poll it,
change the filter or move on. Known thin/quirky:
`creator region` (unreliable → read `region` from `creator profile` instead),
`video captions` (many videos have none), `live detail` (only while a room is
live), `seller inventory` (empty when a shop lists nothing right now — use
`seller catalog` for its history).
- Responses are **server-trimmed to signal** (ids, core metrics, names, key links;
images already converted to accessible URLs) — no raw-blob handling needed.
- **All monetary values are USD.** Every price / avg-price / GMV field (`min_price`,
`max_price`, `spu_avg_price`, `*_gmv_*_amt`, …) is a USD-converted number, regardless
of `--region`; the response carries `"currency": "USD"` to confirm it. Never label
them with a local symbol like `¥`/`円`. If a report needs the local currency (e.g.
JPY for a Japan market study), convert from USD using a current FX rate and mark the
result approximate.
### Viral selling-prompt generator — `clipcat prompt search`
Clipcat's own library of **structured prompts**, each reverse-engineered from a TikTok
video that actually drove sales — every TikTok market and category, ranked by real GMV.
This is not TikTok search: entries here are already broken down and rewritten into a
prompt you can hand to a video model as-is.
**When the user asks for a prompt, idea, script or angle for a selling video, start here
instead of writing one from scratch.** A prompt with a proven video behind it is the whole
point; an invented one is only a guess, and the user cannot tell the two apart.
#### Step 1 — find the closest proven videos
- `prompt search --query "<what you want>"` — semantic + keyword search over the library.
Describe a feel ("warm indoor light, handheld close-up, real person on camera") or
name something exact (a brand, `ASMR`, `OOTD`) — both work; the two are fused, so you
do not have to guess which style of query fits. Optional filters: `--region` (lowercase
market code), `--category` (TikTok Shop L1 code, e.g. `beauty-personal-care`),
`--video-type` (`real-review` | `ootd` | `asmr` | `unboxing-pov` | …), `--limit` (1-20).
Build the query from the user's own product and audience — what it is, who it is for,
the market, the vibe they asked for. A bare category name ("skincare") retrieves the
generic middle of the library.
Priced apart from the other read commands: each paid plan comes with an allowance of
free searches, and calls beyond it cost 3 credits each (other reads are a flat 6).
The response carries `quota.remaining` / `quota.free_quota` / `quota.cost_after_quota` —
tell the user what is left when it runs low instead of letting the next call surprise them.
- **Check `weak_match` and `degraded` before you trust the hits.** The library returns the
nearest entries it has, so a full result list does not by itself mean the results fit.
`weak_match: true` means nothing closely matches — say so and suggest rewording or
dropping a filter, rather than presenting the nearest entries as the answer.
`degraded: true` means semantic search was unavailable and only keyword matching ran:
results may be incomplete, and **that search is not charged** (quota is refunded).
Fewer hits than `--limit` is normal and healthy — only entries relevant enough are
returned, so a narrow `--region` + `--category` combination legitimately returns a few.
Each hit carries the full `prompt` text (`prompt_en` for the English version), the metrics
of the original video (GMV, sales, views), `matched_facet` (which part of the prompt your
query hit — style / camera / voiceover / …), `source_video_url` for the original TikTok
video, and `detail_url` for the public page.
#### Step 2 — rewrite the hit into the user's own prompt
Never hand back a library prompt unchanged: it sells someone else's product. Rewrite the
best hit (or 2-3 hits that agree on structure — averaging ones that disagree yields a
template) into a prompt for this user's product:
- **Keep what made it sell**: the opening hook and what happens in its first 1-2 seconds,
shot order and pacing, camera language, lighting, whether a presenter is on camera and
what kind, voiceover tone, promo mechanic, closing CTA.
- **Swap** the product and its selling points, on-screen text, voiceover lines, and
anything market-specific (language, currency, local wording).
- **Carry over no claim you cannot back.** Ratings, sales numbers, awards, before/after and
efficacy claims belong to the original product — drop them, or ask the user for their own.
- **Fit the target model**: keep the prompt inside the `--duration` you will submit and the
shot count it implies (a 5s clip holds 2 shots, not 6), and pick the voiceover language
with `--lang`.
- Show the user the finished prompt with the `detail_url` (and `source_video_url`) it was
built from **before** spending credits — citing the real video is what separates this
from a prompt you made up.
#### Step 3 — shoot it
- Product images only → `product_video`, passing the rewritten prompt via `--prompt-file -`.
- Want the original video's motion and cuts as the reference → `replicate
--url <source_video_url>` with the user's `--image`s (a TikTok link adds the 10-credit
download surcharge).
- Both are paid: `quote` with the exact parameters → confirm with the user → submit with
`--expected-credits` (see "Confirming cost before paid video commands").
```bash
clipcat prompt search --query "handheld close-up of a serum bottle, warm bathroom light, real user voiceover" \
--region us --category beauty-personal-care --limit 5
# pick a hit → rewrite its prompt for the user's product → quote and confirm:
clipcat quote --model seedance2 --resolution 480p --duration 8
clipcat product_video --image serum.jpg --model seedance2 --duration 8 \
--resolution 480p --size 9:16 --expected-credits <totalCredits> --prompt-file - <<'EOF'
<the rewritten prompt>
EOF
```
### 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. **The listing is live and only contains tiers that currently have a provider** — a resolution or duration missing from `resolutions` / `prices` is rejected on submit, so never submit a combination you did not see here.
- `replicate` — replicate a viral video with your product images. Reference video via **`--url`** (TikTok/Douyin link or direct URL, auto-detects type) **or `--video`** (local video file, max 100MB, uploaded via presigned URL then downscaled server-side; re-replicating the same file reuses the upload; no download surcharge) — provide exactly one. Product 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, plus `--scope all` / `--scope <member-user-id>` (owners/admins only; adds `creatorName`)
- `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"). Workspace owners/admins may also query their members' tasks.
- `list_tasks` — list recent **video-related** tasks from server (`--type` required: `replicate | product | breakdown | download`). Image tasks use `list_images`. `--scope all` / `--scope <member-user-id>` widens to the workspace (owners/admins only; adds `creatorName`), default is your own tasks.
- `character list` — list the characters saved to your account (`id`, `name`, `status`, `type`). The `id` is what you pass to `--character-id` on `replicate` / `product_video`; only `status: completed` characters are usable. Supports `--status` / `--limit` / `--page` / `--sort-by` / `--sort-order`, plus `--scope all` / `--scope <member-user-id>` (owners/admins only; adds `creatorName`). Free (account metadata, no credits).
## Passing prompts (never let the shell mangle them)
A mis-escaped `--prompt \"Create a 5s video\"` reaches the CLI as `"Create` — cut at the
first space. Both the CLI and the server now reject that instead of charging for a garbage
video, but the fix is to pass prompts so it cannot happen:
- Prompt contains quotes, newlines, `$`, or backticks → use stdin, not an inline flag:
```bash
clipcat product_video --image-url <url> --model seedance2 --duration 5 \
--expected-credits 100 --prompt-file - <<'EOF'
Create a 5-second UGC demo. The narrator says "this changed my routine".
EOF
```
The quoted delimiter `<<'EOF'` disables every kind of expansion — zero escaping needed.
This works in bash / zsh / Git Bash. **On Windows PowerShell, do NOT pipe — write a UTF-8
file and pass its path:**
```powershell
Set-Content -Encoding utf8 prompt.txt @'
Create a 5-second UGC demo. The narrator says "this changed my routine".
'@
clipcat product_video --image-url <url> --prompt-file prompt.txt
```
Why not pipe on Windows: **Windows PowerShell 5.1** encodes pipe output to native programs
with `$OutputEncoding`, which **defaults to ASCII** — every Chinese/non-ASCII character
silently becomes `?`, and a prompt of `????????` looks perfectly valid to every quoting check.
If you must pipe, run `$OutputEncoding = [System.Text.Encoding]::UTF8` first. (PowerShell 7
defaults to UTF-8 everywhere and is not affected, but the file-based form above works on both,
so just use it.) Also note `@'` must end its line and `'@` must start its own line — a
single-line `@' … '@` is a syntax error. On 5.1, `Out-File` is not a substitute for
`Set-Content -Encoding utf8`: it defaults to UTF-16, which the CLI rejects outright.
- **Never read a file into a string and pass it inline** — no `--prompt (Get-Content p.txt)`.
On PowerShell 5.1 `Get-Content` decodes a UTF-8 file as ANSI, producing mojibake that is
valid UTF-8 with no quoting anomaly: every check passes and you get charged for a garbage
video. Pass the **path** (`--prompt-file p.txt`) and let the CLI read the bytes.
- Short single-line prompts may stay inline as `--prompt "…"`. Never backslash-escape the
outer quotes, and never wrap an already-quoted string in another layer of quotes.
- `--prompt` and `--prompt-file` are mutually exclusive (`-` = stdin, otherwise a file path).
- After submit the CLI prints `Prompt sent (N chars): …`. Check it against what you intended;
a wrong N means the command line was mangled, not the prompt you wrote.
- If a submit is rejected for a mis-quoted prompt, do NOT retry the same command — re-send it
via `--prompt-file -`. Rejections happen before any charge.
## 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`.
Example — quote, then submit the confirmed cost (Seedance 2, 480p default, 8s, TikTok link):
```bash
clipcat quote --model seedance2 --resolution 480p --duration 8 \
--url "https://www.tiktok.com/@u/video/123"
# → seedance2 480p 8s → 160 credits + 10 download → total 170 credits
clipcat replicate --url "https://www.tiktok.com/@u/video/123" \
--image product.jpg --model seedance2 --duration 8 --resolution 480p \
--size 9:16 --expected-credits 170
```
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 → 160 credits + 20 enhance (1080p) → total 180 credits
clipcat product_video --image product.jpg --model seedance2 --duration 8 \
--resolution 480p --size 9:16 --enhance 1080p --expected-credits 180
```
## replicate: reference video source
`clipcat replicate` takes the reference video via **exactly one** of `--url` / `--video`:
- `--url` **TikTok/Douyin link** → calls `/replicate_from_social` (costs **10 extra credits** for download)
- `--url` **direct video URL** → calls `/replicate`
- `--video` **local file** (max 100MB) → uploaded via presigned URL, then `/replicate` (no download surcharge). Uploading the same file again is deduplicated (content-hashed, per-user), so repeat replications skip the upload.
Always inform the user about the extra 10 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; the server resolves them to a signed URL. A mistyped reference is rejected up front (no credits charged), so never retype one from memory. See subcommand `-h` for details.
`--character-id` accepts three forms: a numeric id from `clipcat character list` (never guess ids), `@<sora-username>`, or an image URL / `clipcat://` reference.
## 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 |
| -------------------- | --------------------- | ----------------- | ----------------------------------------------------------------- |
| `grok_imagine` | 10s, 15s | 480p, 720p | **Trial**, default. xAI Grok Imagine 1.5, 9:16 aspect ratio only |
| `veo3.1fast` | 8s, 16s, 24s | 720p | **Trial**. Google Veo 3.1 Fast, balanced quality and cost |
| `omini_flash` | 10s, 20s | 720p, 1080p | **Trial**. Gemini Omni Flash, Google's newest model |
| `seedance2_mini` | 4-15s (any integer) | 480p, 720p | **Trial**. Seedance 2 Mini, value tier. Free plans are 480p only — **pass `--resolution 480p` explicitly** |
| `mmh3_promo` | 10s, 15s | 480p, 720p, 2K | **Trial**. Subsidized MiniMax H3 channel, open to free plans |
| `seedance2` | 4-15s (any integer) | 480p, 720p, 1080p | Standard (paid). ByteDance Seedance 2, top quality. **Default 480p** |
| `seedance2_5` | 4-30s (any integer) | 480p, 720p | Standard (paid). ByteDance Seedance 2.5, newest generation, clips up to 30s. **Default 480p** |
| `seedance2_fast` | 4-15s (any integer) | 480p, 720p | Standard (paid). ByteDance Seedance 2 Fast, fast variant. **Default 480p** |
| `wan30` | 5-30s (any integer) | 480p, 720p, 1080p | Standard (paid). Alibaba Wan 3.0, clips up to 30s |
| `minimax_h3` | 10s, 15s | 768p, 2K | Standard (paid). MiniMax H3 |
| `happyhorse10` | 3-15s (any integer) | 720p, 1080p | Standard (paid). Alibaba HappyHorse 1.1 |
`clipcat models` is the authority on both the model list and the live
per-combination credit costs — a model missing there has been retired and is
rejected on submit, whatever `-h` or this table says. Prefer `mmh3_promo` over
`minimax_h3` whenever `clipcat models` lists it: same model on a limited-time
subsidized channel, a fraction of the credits, and free plans may use it.
The tiers in this table are what each model *offers*; `clipcat models` is what is
*available right now*. Providers get disabled for maintenance, so a listed tier can
temporarily disappear. If a submit is rejected with **"no available channel"**, the
parameters were valid but that tier has no provider at the moment — re-run `clipcat
models`, pick another resolution/duration/model from the fresh listing, re-quote and
re-confirm with the user. Do not retry the same combination.
**`seedance2`, `seedance2_5` and `seedance2_fast` default to `--resolution 480p`** (the CLI
applies this in `quote`, `replicate` and `product_video` when `--resolution` is
omitted). Only pass a higher resolution when the user explicitly asks for one,
and keep `quote` and the submit on the same value.
`seedance2_mini` is **not** covered by that automatic default: free plans can only
use its 480p tier, so omitting `--resolution` sends the server default (720p) and
the submit is rejected. Pass `--resolution 480p` explicitly on both the `quote` and
the submit.
## 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.
- Asked for a selling-video prompt / idea / script: run `clipcat prompt search` first,
rewrite the closest proven hit for the user's product, and cite its `detail_url`.
Writing one from imagination throws away the only thing that makes it a viral prompt.
- 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.
- Resolution: always quote and submit at the model's default (`480p` for `seedance2` / `seedance2_5` / `seedance2_fast`) unless the user explicitly asked for a higher one. Never silently upgrade to 720p/1080p — higher resolution costs more credits.
- Pass any non-trivial prompt via `--prompt-file -` with a quoted heredoc (see "Passing prompts"); verify the `Prompt sent (N chars)` echo after submit.
- 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.
SKILL_README_ZH.md
+152
View File
@@ -0,0 +1,152 @@
# Clipcat Skill
Clipcat 是一个 TikTok 电商 AI 视频创作 Skill，**任何 AI Agent 都可以集成**——Claude Code、OpenClaw、Cursor，或你自研的 Agent 均可。它以一个跨平台的 `clipcat` CLI 加一份 `SKILL.md` 清单的形式提供：Agent 通过调用 `clipcat` 命令，在同一套工作流中完成爆款视频发现、TikTok Shop 市场情报分析、视频分析、爆款复刻、商品视频生成、AI 图片生成以及 TikTok 视频下载。
最新指南和示例请查看：[https://clipcat.ai](https://clipcat.ai)
## 工作原理
Clipcat 本质上只是一个小巧的 CLI 二进制 + 一份 `SKILL.md` 技能清单，任何能执行 shell 命令的 Agent 都能驱动它：
- Agent 读取 `SKILL.md` 了解可用命令与约定。
- 调用 `clipcat <命令>` 并解析其 JSON 输出（默认格式）。
- 异步任务（视频/图片生成）提交后立即返回，由 Agent 跨轮次轮询。
OpenClaw 会依据清单自动安装该 Skill；其他 Agent 则手动安装 CLI（见下文）。无论哪种方式，底层运行的都是同一个 `clipcat` 二进制。
## 核心能力
- **TikTok 电商数据情报**：覆盖达人、商品、店铺、视频、直播、关键词/图片搜索 6 大实体域，支持榜单、多维筛选发现、趋势、详情、评价、评论与跨实体关系查询（Agent 通过 `clipcat <实体> -h` 选择具体命令）
- **视频分析**：提取 TikTok 或抖音视频中的脚本、分镜、钩子和音乐信息
- **爆款复刻**：基于已验证的爆款结构，结合你的商品素材进行复刻生成（自动识别 TikTok/抖音链接与直链视频 URL）
- **商品生视频**：将商品图片生成 UGC 风格的 TikTok 视频
- **AI 图片生成**：基于 GPT Image 2 模型，根据文本提示生成 AI 图片，并可选上传参考图（最多 5 张）
- **视频下载**：通过 Clipcat API 下载 TikTok 或抖音视频
## 安装
### 1. 安装 CLI
**OpenClaw**：依据 Skill 清单自动安装，无需手动操作。
**其他 Agent / 手动安装**：安装 CLI 二进制：
```bash
# 安装 clipcat CLI
curl -fsSL https://clipcat.ai/cli | bash
```
### 2. 获取 API Key
注册或登录后，在个人中心生成 API Key：
[生成 API Key](https://clipcat.ai/workspace?modal=settings&tab=apikeys)
### 3. 配置 API Key
在 Agent 运行的机器上配置一次即可：
```bash
clipcat config --api-key your_api_key_here --base-url https://clipcat.ai
```
通过环境变量管理密钥的 Agent 也可改为设置 `CLIPCAT_API_KEY`（例如 OpenClaw：`openclaw env set CLIPCAT_API_KEY your_api_key_here`）。
## 使用方式
安装完成后，你可以直接让你的 Agent 帮你：
- “搜索本周关于 lip gloss 的 TikTok 爆款视频”
- “搜索 TikTok Shop 里热门宠物产品，并展示竞品店铺”
- “用我的商品图片复刻这个 TikTok 视频”
- “用这些图片生成一个商品视频”
- “生成一张模特手持我商品的 AI 图片”
- “分析这个视频并提取脚本”
- “展示这个 TikTok 用户最近的视频及互动数据”
- “下载这个 TikTok 视频”
- “拉取这个商品链接对应的 TikTok Shop 商品详情和评论亮点”
## 重要说明
- 视频生成任务是异步执行的，通常需要几分钟
- 提交消耗算力的任务前，Agent 会先用 `clipcat quote` 报出精确算力，向你展示模型/时长/分辨率/算力，并等待你确认
- 不要手动重复提交任务，Clipcat 已内置重试处理
- 请保留完整的 TikTok 或抖音链接，尤其是带签名参数的 URL
## 支持模型
- `grok_imagine` - 10s, 15s, 20s, 30s（720p，仅 9:16）—— 默认模型，支持更长时长
- `veo3.1fast` - 8s, 16s, 24s（720p, 1080p）—— 质量与成本均衡
- `sora2_official_exp` - 4s, 8s, 12s（720p，9:16 或 16:9）—— 仅付费用户，OpenAI Sora 2 官方通道
用 `clipcat models` 查看完整可用模型列表、每个「分辨率 × 时长」组合的精确算力和你的余额；`clipcat replicate -h` 也会列出模型。
## 支持语言
英语、中文、法语、德语、马来语、越南语、泰语、日语、韩语、印尼语、菲律宾语
## 使用示例
### 示例 1：搜索 TikTok 爆款视频
```text
Search for viral TikTok videos about lip gloss in the US market this week.
Show me the top 10 results sorted by likes.
```
会返回按热度排序的相关爆款视频列表，包含核心指标和源链接，便于进一步分析。
### 示例 2：复刻 TikTok 视频
```text
Replicate this TikTok video with my product:
https://www.tiktok.com/@username/video/123456789
Use these product images:
- /path/to/product1.jpg
- /path/to/product2.jpg
Generate a 16-second video in English using veo3.1fast model.
```
Agent 会先展示参数，并等待你确认后再提交任务。
### 示例 3：从零生成商品视频
```text
Create a 10-second OOTD video featuring a British girl showcasing my product.
Product image: /path/to/dress.jpg
Use veo3.1fast model, 9:16 aspect ratio, English language.
```
### 示例 4：分析视频
```text
Analyze this video and extract the script, scenes, and music information:
https://www.tiktok.com/@username/video/987654321
```
会返回结构化数据，包括逐镜头拆解、画面描述、口播内容和背景音乐信息。
### 示例 5：下载 TikTok 视频
```text
Download this TikTok video:
https://www.tiktok.com/@username/video/111222333
```
该操作为同步执行，会立即返回视频直链 URL。
## 使用建议
- 始终提供完整的 TikTok/抖音链接
- Prompt 越具体，结果通常越好
- 视频生成需要时间，请等待任务完成
- 带签名参数的视频链接请完整保留
- 根据时长和质量需求选择合适模型
## 相关链接
- 官网：https://clipcat.ai
- OpenClaw 一键安装：https://clipcat.ai/tiktok/openclaw
- 命令参考：详细命令说明请查看 `SKILL.md`