From 66dfe5d74db4143ff0a0d41d6c4bd9ab4f74e904 Mon Sep 17 00:00:00 2001 From: 19926533763 <19926533763@163.com> Date: Wed, 2 Sep 2026 14:17:59 +0800 Subject: [PATCH] feat: add Clipcat skill --- README.md | 152 +++++++++++++ SKILL.md | 517 +++++++++++++++++++++++++++++++++++++++++++++ SKILL_README_ZH.md | 152 +++++++++++++ 3 files changed, 821 insertions(+) create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 SKILL_README_ZH.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1dd0dda --- /dev/null +++ b/README.md @@ -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 ` 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 -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 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..791b21c --- /dev/null +++ b/SKILL.md @@ -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 -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 --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 -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 `. Run `clipcat -h` +to list verbs and `clipcat -h` for flags. + +- `creator ` — TikTok creators/influencers +- `product ` — TikTok Shop products +- `seller ` — TikTok Shop shops +- `video ` — TikTok videos +- `live detail` — live-room detail (only while live) +- `find ` — 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 (` 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 ` (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 ` 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 ""` — 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 ` 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 --prompt-file - <<'EOF' + +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 ` (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 ` 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 ` (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 --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 --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 `. 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), `@`, 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 --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 ` 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 `. 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. diff --git a/SKILL_README_ZH.md b/SKILL_README_ZH.md new file mode 100644 index 0000000..4ec3ce4 --- /dev/null +++ b/SKILL_README_ZH.md @@ -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`