Clipcat CLI#

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

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

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

Installation#

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

After installation, configure your API key once:

bash

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

What this CLI is for#

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

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

Default agent workflow#

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

Choosing the right command#

TikTok e-commerce data — entity commands#

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

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

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

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

Data-query playbook (dense):

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

Video generation & tools#

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

Confirming cost before paid video commands#

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

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

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

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

Super-resolution ( --enhance)#

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

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

bash

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

replicate: URL type auto-detection#

clipcat replicate automatically detects the URL type:

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

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

clipcat:// asset references#

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

Async task rules#

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

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

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

query_task: auto-resume#

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

Available models#

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

Model IDDurationResolutionNotesveo3.1fast8s, 16s, 24s720p, 1080pTrial. Google Veo 3.1 Fast, balanced quality and costveo3.1pro8s, 16s, 24s720p, 1080pTrial. Google Veo 3.1 Pro, high-quality variantomini_flash10s720p, 1080pTrial. Gemini Omni Flash, Google's newest modelgrok_imagine10s, 15s, 20s, 30s720pTrial, default. 9:16 aspect ratio only, longer clipsseedance24-15s (any integer)480p, 720p, 1080pStandard (paid). ByteDance Seedance 2, top qualityseedance2_fast4-15s (any integer)480p, 720p, 1080pStandard (paid). ByteDance Seedance 2 Fast, fast varianthappyhorse103-15s (any integer)720p, 1080pStandard (paid). Alibaba HappyHorse 1.0sora2_official_exp4s, 8s, 12s720pStandard (paid). OpenAI Sora 2 official channel, 9:16 or 16:9

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

Supported languages ( --lang)#

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

Region ( --region)#

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

Good agent behavior#

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