TikTok e-commerce video generation, replication, and analysis SKILL
Catalog skill by Clipcat-ai: TikTok e-commerce video generation, replication, and analysis SKILL Install into Cursor, Claude, Codex, or VS Code from this page or review the source for clipcat-skill.
Ads
git clone https://github.com/Clipcat-ai/clipcat-skill
Install guides: Cursor skills, Claude Code skills, Codex skills, or VS Code Copilot skills.
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.
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:
curl -fsSL https://clipcat.ai/cli | bash
Windows (PowerShell, no bash):
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).
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.
Configure the key in the local config file — the only reliable method:
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.)
clipcat is the local entrypoint for all Clipcat AI video generation workflows:
clipcat -h to see all commands.clipcat <subcommand> -h to see flags.replicate / product_video / generate / tiktok publish submit in TWO calls:
the first charges nothing, creates nothing and returns a checklist + confirmId; you
show that checklist to the user, wait for an explicit yes, then run
--confirm <confirmId> (see "Two-step confirmation").⬆ 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.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/influencersproduct <list|rank|detail|trend|reviews|live-comments|creators|videos|lives> — TikTok Shop productsseller <list|rank|detail|trend|catalog|inventory|creators|videos|lives> — TikTok Shop shopsvideo <list|rank|snapshot|sales|trend|comments|captions|products|hashtag> — TikTok videoslive detail — live-room detail (only while live)find <creators|products|videos|lives|hashtags|music|photo|all> — keyword/image search; find all is the broad fallbackTwo 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):
<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).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.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.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.[] / 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).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.clipcat prompt searchClipcat'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.
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.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.
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:
--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 (required — pick it deliberately, the CLI has no default).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.product_video, passing the rewritten prompt via --prompt-file -.replicate --url <source_video_url> with the user's --images (a TikTok link adds the 10-credit
download surcharge).--confirm <confirmId> (see "Two-step confirmation").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 → step 1 (no charge):
clipcat product_video --image serum.jpg --model seedance2 --duration 8 \
--resolution 480p --size 9:16 --lang en --prompt-file - <<'EOF'
<the rewritten prompt>
EOF
# → confirmationRequired + confirmId. Show the checklist, wait for a yes, then:
clipcat product_video --confirm <confirmId>
Which video command: default to agent mode unless the user asked otherwise —
replicate when they want a viral video re-shot with their product, product_video
when they want the script written from product images. Those two do the scripting and
storyboarding for the user, who only has to bring product images and a one-line ask.
generate (raw) sends the prompt and assets to the model VERBATIM — no AI scripting,
no storyboard, no product-shot compositing — so the output is only as good as the
prompt and parameters you write: framing, camera moves, pacing and voice-over are all
on you, and the model's supported resolutions / durations / asset modes have to be
picked off clipcat models --raw yourself. Pick it only when the user already has the
exact instructions and assets, or explicitly does not want an agent rewriting their
idea. When unsure, ask ("should I generate exactly what you described, or have the
agent write a script for you?") — never default the user into raw mode.
generate — raw video generation: your --prompt and assets go to the model as given. Run clipcat models --raw FIRST — it is the only authority on which models support this and what each one accepts right now. Two asset modes, chosen automatically from your flags: reference images (--image local / --image-url URL or clipcat:// ref, optional --character-id, optional --ref-video, optional --ref-audio) or frames (--first-frame(-url) plus optional --last-frame(-url); no character, no reference video, no reference audio). Also takes --resolution, --duration, --size (9:16, 16:9, or adaptive on models whose Ratios column in clipcat models --raw lists it), --enhance, --dry-run, --expected-credits. Two-step submit via --confirm (see below). --character-id here accepts a numeric id only (no @sora names, no image URLs). --ref-audio takes only a clipcat:// reference — upload a local audio file first with clipcat asset upload <file> and pass the ref it prints (audio already in the library: clipcat asset list --type audio). Most models accept no audio at all (raw.maxAudios in clipcat models --raw), audio cannot be submitted alone (pair it with a reference image or video), and the server measures its duration itself — re-quote with --dry-run after adding one. Reference files and reference web links are still web-only — there are no flags for them.models --raw — the raw-generation capability table: per model, the image modes, image count range, frame slots, reference-video limit, prompt cap, character support, the Ratios column (the aspect ratios that model accepts — adaptive only shows up on models that support it), plus live per-combination credit costs. A model whose RefVideo column shows +output ≤Ns spends that budget on reference-video seconds and --duration together — go over it and the submission is rejected. These limits change with the providers enabled at that moment — read the table, never assume. If it reports raw generation is not open on this account, use replicate / product_video instead.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). Optional cost preview, not the confirmation step: the server does all the math and hands back totalCredits (already includes the enhance fee) plus enhanceCredits / enhanceBlocked. Useful for comparing models or for feeding --expected-credits; the checklist you actually show the user comes from the submit itself (see "Two-step confirmation" and "Super-resolution").models — browse all available video models with their credit costs (discrete → prices, range → creditsPerSecond), the image models with their per-image credit cost (imageModels), 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, direct URL, or a clipcat:// reference from an earlier upload — 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 (required, no default), --resolution, --enhance (super-resolution, see below), --character-id, --expected-credits. Two-step submit via --confirm (see below).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; --lang is required (no default — it is the video's spoken/subtitle language, confirm it with the user); supports --enhance (super-resolution, see below), --expected-credits. Two-step submit via --confirm (see below).image — generate an AI image from a text prompt using the GPT Image models; 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. --model picks the image model: gptimage2 | gptimage25flare (GPT Image 2.5 Flare) | gptimage25sunburst (GPT Image 2.5 Sunburst) | nanobana2 (Nano Banana Pro) — per-image credits are server config, so read them from the imageModels section of clipcat models. Do not pass --model unless the user asked for a specific model (omitting it uses the server default, which is configured server-side and is not necessarily gptimage2), and tell the user the per-image credit cost before submitting.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 analyzeddownload — download TikTok/Douyin video (returns signed URL); cached results return immediatelyquery_task — check status of a task by ID and type (--type replicate | product | raw | 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 | raw | 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.
taskId is the project id (the one in a /project/<id> link); each finished video inside it has its own videos[].videoTaskId. A project can hold several videos (one per script), so they never coincide. Anything that acts on one video — tiktok publish --video-task-id above all — takes videoTaskId, never taskId. query_task returns the same pair.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 / generate; 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).asset upload <file> — upload a local image (jpg/png/webp, ≤10 MB), video (mp4/mov, ≤150 MB) or audio (mp3/wav/m4a/aac, ≤10 MB) to the asset library, the same way the website does, and print its clipcat:// reference (plus the server-measured duration for audio/video). Pass an image ref verbatim to --image-url / --first-frame-url and an mp3/wav audio ref to --ref-audio (m4a/aac upload fine but --ref-audio refuses them — convert first); a video is kept in the library only — for generate --ref-video pass the local file itself. --name sets the display name. Free (uses storage quota, no credits).asset list — list the assets saved to your account (type, name, duration, size) with their clipcat:// references. That reference is what you pass to --image-url / --first-frame-url / --ref-audio, and to --ref-video only when it starts with clipcat://analyse/video/ (a video under clipcat://assets/ is refused there — pass the local file instead); copy it character-for-character, never retype or reconstruct one. This is how you find the reference for something the user uploaded on the website. Supports --type image|video|audio|document / --q <name> / --limit / --page, plus --scope all / --scope <member-user-id> (owners/admins only; adds creatorName). Free (account metadata, no credits).clipcat tiktokNoun-verb: clipcat tiktok <connect|connect-status|accounts|creator-info|publish|tasks|task|cancel>.
Publishing costs no credits — the quota is on connected accounts (free 0 / basic 3 / creator+ unlimited).
Only watermark-free renders can be published (TikTok forbids API clients stamping creator
content); a watermarked one is rejected at submit with watermarked_video.
connect — one-time authorization. The consent page opens in a browser; with no GUI (SSH / container) it degrades to printing the link on stderr, so --json stays parseable. The callback lands on the server, not on this machine, so the page may be opened on a phone. Poll connect-status --state <state>; a user who cancels shows up as denied, don't wait it out.accounts — connected accounts and their openId; every other subcommand takes --open-id.creator-info — run this before every direct post. privacyLevelOptions is the only authority on which --privacy values the account accepts (a private account offers SELF_ONLY alone). It also reports maxVideoPostDurationSec and whether the account disabled comment / duet / stitch. When a privacy level is rejected, read the options here instead of retrying the same value.publish — two-step, like the paid video commands (see "Two-step confirmation"), though for a different reason: it costs no credits, but it is the one command that pushes content to the user's own public TikTok account, and once a post is live nothing here can take it back. The first call validates and returns a checklist of everything that will be posted — account, video, post mode, caption, who can view, comment/duet/stitch, AIGC and brand-content disclosure, schedule — plus a confirmId. Exactly one video source: --video-task-id (a finished Clipcat video — videos[].videoTaskId from list_tasks / query_task, not the project-level taskId; passing a project id fails with errorCode=video_task_is_project_id and the error names the right ids), --asset-id (asset library), or --video <path> (local file, uploaded first, counts toward storage quota).
--mode direct (default) posts it now and requires --privacy. --mode draft delivers only the video to TikTok's drafts inbox — --title, --privacy, --allow-*, --brand-*, --aigc and --cover-ts-ms are ignored there; the user fills those in inside the TikTok app.--allow-comment / --allow-duet / --allow-stitch) are off by default, as TikTok's UX guidelines require; the server forces them off when the account disabled them.--brand-content (paid partnership) cannot be combined with SELF_ONLY.--schedule queues it for later (direct posts only, 5 min to 30 days ahead). The timezone offset is mandatory — 2027-03-01T20:00:00+08:00 is 20:00 Beijing time (UTC+8), 2027-03-01T12:00:00Z is that same moment in UTC; a bare 2027-03-01T20:00:00 is rejected. Most users say a wall-clock time in their own timezone, so append their offset rather than converting to Z in your head. --wait is ignored here — the task returns as SCHEDULED and cancel --task-id <id> calls it off.--wait blocks polling every 15s, so prefer submit → task --task-id <id> across turns rather than risking a tool-call timeout.tasks / task --task-id <id> / cancel --task-id <id> — list publish tasks, read one, cancel one that is still scheduled.clipcat scheduleNoun-verb: clipcat schedule <list|show|create|update|enable|disable|delete|run>.
A schedule is a saved prompt the Clipcat Agent runs by itself at --at (24h HH:mm) in
--timezone (IANA, e.g. Asia/Shanghai), every day or on --days (mon,wed,fri /
weekdays / weekends). Each run lands in a new chat on the website, plus an email
(--notify none turns it off).
run — is billed like a normal Agent chat turn and may submit up to 3 generation tasks with nobody confirming. Paid plans only; at most 100 schedules per account (disabled ones count).create needs --title, --prompt (or --prompt-file -), --at, --timezone. Ask the user for their timezone, never guess it. The run has no memory of this conversation: write the prompt as a complete standalone instruction and paste any clipcat:// refs verbatim. Confirm prompt, time, days and timezone with the user before creating.update --id changes only the flags you pass; --at or --days alone keeps the other half (--days daily = every day). It never turns a schedule on or off — use enable / disable.not_found.delete is permanent and run spends credits right away — get an explicit yes first. run returns immediately; follow up with show --id (lastStatus, lastResultUrl). schedule_running means a run is already in progress: don't retry in a loop.nextRunAt / lastRunAt are UTC.clipcat ttsTurns a script into an mp3 voice-over, synchronously (~2-10s), with a preset or a cloned voice. The mp3 lands in the
asset library; the returned ref (clipcat://…) is reference audio for clipcat generate --ref-audio as-is.
--dry-run / tts voices are authoritative — quote before synthesizing and tell the user.--model, usually omit): seed-tts-2.0 is the default, preset voices only, the only one with word timestamps. Cloned voices need cosyvoice-v3.5-plus (their default) or fish-s2.1-pro. A flag the model doesn't support is rejected, not charged.tts voices [--language en] [--model M] — models (presets / clone / supported flags / availability), recommended voice ids, --language values, price. Free. Unlisted voice ids go to seed-tts-2.0 unless --model is given.tts --voice <id|clone_<id>> --text "…" (long or quoted text: --text-file - <<'EOF' … EOF). Max 1000 characters per call — split longer scripts by sentence or scene. Optional --language (the text must be in it; seed-tts-2.0 + en / zh-cn also return words timestamps), --instruction (tone; its characters are billed too), --speed / --volume (-50..100, 0 = normal).--out <file> also saves the mp3 locally (never overwrites without --force). If saving fails the audio is still charged and in the library: reuse ref / audioUrl, never re-run.tts clone --audio <local file | clipcat://ref> [--start S] [--duration D] [--name N] [--transcript T] [--dry-run] — free; returns voice: clone_<id>. Sample: 10–60s, one speaker, clear speech; audio or video (mp3 wav m4a aac ogg flac mp4 mov webm, ≤20MB — the audio track is extracted). Bigger video: clipcat asset upload <file> (≤150MB) and pass the clipcat:// ref it prints; already in the library: clipcat asset list --type audio|video. Other URLs: download first. Only clone a voice the user has the right to use.tts clones [--q NAME] [--page N] [--limit N] [--scope mine|all|<userId>] — the user's cloned voices. Free.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:
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:
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.
Four commands submit in two calls, and you must never do both in one turn:
replicate, product_video and generate because they consume credits, tiktok publish
because it posts to the user's own public account and cannot be undone. Never compute
the credits yourself — let the server return them.
Step 1 — submit normally. Run the full command as you always would. The server
validates everything but charges nothing and creates no task; it returns
data.confirmationRequired: true with a confirmId and a confirmation snapshot
(generationType, model, resolution, duration, size, lang, imageCount, the full
prompt text, and the credit breakdown credits / downloadSurcharge /
enhanceCredits / totalCredits), plus an instruction string. Exit code is 0 —
this is not an error, so do not retry or change parameters.
Step 2 — put the checklist to the user and stop. Show the parameters, the full
prompt and totalCredits, print the instruction as-is, and wait for the user's
explicit reply in the conversation. Silence, "sounds good", or your own judgment
is not approval. Never chain step 3 into the same turn.
Step 3 — only after an explicit yes:
clipcat product_video --confirm cfm_7QK2M8 # or clipcat replicate / clipcat generate --confirm ...
--confirm cannot be combined with any business parameter — the server submits the
snapshot it stored in step 1, so passing one would silently do nothing (the CLI rejects
the combination locally rather than let you believe it took effect). Plumbing flags
(--output, --api-key, --base-url, --poll, and --wait / --timeout on
tiktok publish) are fine. To change any parameter, go back to step 1 with the new
values and get the new checklist approved.
Full example (Seedance 2, 480p default, 8s, TikTok link):
clipcat replicate --url "https://www.tiktok.com/@u/video/123" \
--image product.jpg --model seedance2 --duration 8 --resolution 480p \
--size 9:16 --lang en
# → confirmationRequired, confirmId cfm_7QK2M8, total 170 credits (160 + 10 download)
# → show the checklist, wait for the user's yes, then:
clipcat replicate --confirm cfm_7QK2M8
tiktok publish — same protocol, different checklistThe three steps are identical; what changes is what the user is being asked to approve.
data.confirmationType is tiktok_publish (it is video for the two generation
commands) and the confirmation snapshot carries the account, the video (source, title,
duration), the post mode, the caption, the privacy level, comment / duet / stitch, the
AIGC and brand-organic / brand-content disclosure flags, the schedule and the cover
frame — plus two lists the server computed for you:
forcedOff — interactions the user asked for that this account has disabled in its
own TikTok settings. They will be posted as off. Say so; do not retry.ignoredInDraft — settings that were passed but are not sent in --mode draft
(TikTok takes them from the app instead). Their values will not apply.clipcat tiktok publish --open-id _000abc... --video-task-id 4211 \
--privacy PUBLIC_TO_EVERYONE --title "New drop" --allow-comment
# → confirmationRequired, confirmId cfm_7QK2M8, plus the full post checklist
# → show it, say plainly that this posts to their public account, wait for a yes:
clipcat tiktok publish --confirm cfm_7QK2M8
A successful confirm returns a taskId; no taskId means nothing was published —
report that as a failure, never as a post. A CLI older than 1.0.43 cannot publish at all:
the server rejects it with an explicit "run clipcat update" message, because those
versions read the confirmation checklist as a created task and print a publish task that
does not exist. creator-info is still worth running before
step 1: it is the only authority on which --privacy values the account accepts, and it
saves a rejected upload when --video points at a large local file.
Optional extras, all independent of the confirmation:
clipcat quote previews the cost before step 1 (same parameters; add --url for
the download surcharge, --enhance for super-resolution). Useful to compare models
with the user. Never compute credits yourself — let quote or the step-1
checklist return them. For raw generation use clipcat generate --dry-run instead
(quote does not cover raw pricing).--dry-run also uploads the assets and returns clipcat:// references — pass
those into step 1 to skip re-uploading. It is not the confirmation step and
returns no confirmId.--expected-credits <n> on step 1 caps the cost: the server rejects the request
only if the real cost is higher (a cheaper real cost — cache hit, promo — just
goes through). On a rejection it returns the current cost; re-confirm and resubmit.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.
Premium models (e.g. seedance2, happyhorse10) require a paid plan; clipcat quote flags them (premiumBlocked) and the server rejects them for free users.
generate) quotes with --dry-run, not quoteclipcat quote does not cover generate. Instead, build the exact command you intend
to submit and add --dry-run: it validates everything, uploads/resolves your assets,
and returns the same totalCredits the submit will charge (the quote and the charge run
the same server-side calculation, so they cannot drift). It creates no task and spends
nothing. The response also hands back clipcat:// references for every asset it
uploaded — reuse them on the real submit so nothing is uploaded twice:
clipcat models --raw
clipcat generate --model seedance2 --resolution 720p --duration 10 \
--prompt "A cat drinking coffee, cinematic" --image ./cat.jpg --dry-run
# → TOTAL: 410 credits ... image ref: clipcat://<key>
# confirm 410 credits with the user, then submit the same command with the ref:
clipcat generate --model seedance2 --resolution 720p --duration 10 \
--prompt "A cat drinking coffee, cinematic" --image-url clipcat://<key> \
--expected-credits 410
Some models let the prompt name an individual asset by position. clipcat models --raw
reports this per model as raw.mention:
"mention": { "dialect": "at_en", "kinds": ["image", "video", "audio"],
"examples": { "image": "@image1", "video": "@video1", "audio": "@audio1" } }
@image1 / @video1 / @audio1. Write
that and nothing else. The server translates it into whatever the upstream model wants
(@图片1, 图1, [Image 1], <IMAGE_REF_0> …) at dispatch time, so a prompt you
wrote for one model works verbatim on any other.kinds still differs per model — it says which asset types that model can have
pointed at (Grok's upstream only has a notation for images, Omni has none for audio).
Mentioning a type that is not in kinds is read as plain text.@Image1 works), but emit the lowercase form.clipcat:// references keep the order you wrote them in, mixed or not. The
character image (--character) counts as the last reference image.media_duplicate), because the upstream
de-duplicates it and every later reference would then be off by one.mention field cannot have its assets pointed at at all — the
upstream never documented a notation for it. Do not mention assets in that prompt.@image1 → <IMAGE_REF_0>), and the
length limit applies to the translated text. --dry-run reports the real length,
so trust it over your own character count.--first-frame / --last-frame) are bound by role, not by number,
so they cannot be mentioned.A reference video (--ref-video) is uploaded and its duration is measured on the
server — on some models that duration changes the price (the model row says
repricedByReferenceVideo), so always re-run --dry-run after adding or changing one
and re-confirm the new total.
A reference audio (--ref-audio) takes only a clipcat:// reference: upload a local
file with clipcat asset upload <file> (it prints the reference), or take one from
clipcat asset list --type audio. Its duration is measured server-side
too, and on some models it also enters the price — re---dry-run after adding one.
Audio never stands alone: pair it with at least one reference image or reference video.
The per-clip length limit is per model, not global. Each model row in
clipcat models --raw carries maxClipSec — the longest a single reference clip may
be (Seedance 2.5 takes 30s, every other model 15s). It is separate from
maxVideoTotalSec, which caps the sum of all clips. The top-level
clipRules.maxClipSec is merely the widest value across all models (currently 30); it
exists for the upload step, which happens before a model is picked — never validate
against it, it waves through a 20s clip that a Seedance 2.0 model then rejects on
submit. Read the model row.
--enhance)replicate, product_video and generate accept --enhance 720p|1080p|2k to upscale
the finished video. Rules:
replicate /
product_video: 480p → 720p / 1080p / 2k, 720p → 1080p / 2k, 1080p → 2k, 2k →
no option. (generate only requires a valid output tier — it does not compare
against the generated resolution — but upscaling to a lower tier still costs
credits, so pick a higher one.) The CLI only
enum-checks the value; the server enforces the tier ladder.clipcat quote --enhance
flags this as enhanceBlocked: true (upgrade needed).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. On generate
the same figure comes back from --dry-run as enhanceCredits, already folded into
its totalCredits.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.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 --lang en --enhance 1080p --expected-credits 180
# → confirmationRequired; show the checklist, wait for a yes, then:
clipcat product_video --confirm <confirmId>
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://... strings seen in earlier turns are stable asset references. Pass them verbatim to any --image-url / --first-frame-url / --last-frame-url / --ref-video / --ref-audio / --character-id / replicate --url 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.
Don't have one? clipcat asset upload <file> uploads a local image / video / audio file and prints its reference; clipcat asset list prints the reference for every asset already on the account (--type audio for audio), including anything the user uploaded on the website.
--character-id accepts three forms on replicate / product_video: a numeric id from clipcat character list (never guess ids), @<sora-username>, or an image URL / clipcat:// reference. On generate only the numeric id is accepted.
replicate, product_video, generate, image, and breakdown are async. All of
them submit and return immediately with a task ID — they never block.
Typical durations: image ~3 min, breakdown a few minutes, product_video /
replicate / generate 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.
~/.clipcat/tasks.json automatically.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.clipcat list_tasks --type <replicate|product|raw|breakdown|download> to
see tasks of a given type from the server (raw = tasks from generate).clipcat query_task with no flags automatically reads the latest task from ~/.clipcat/tasks.json and resumes it. No need to remember task IDs.
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. 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, platform default (what an omitted --model resolves to). Seedance 2 Mini, value tier. Free plans are 480p only — that is also what an omitted --resolution gives |
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.
For clipcat generate (raw generation) this table does not apply — run clipcat models --raw. Raw generation supports a subset of these models, its duration tiers are
narrower (it calls the model directly, with no stitching), and what each model accepts —
image modes, image count range, frame slots, reference-video limit, prompt cap,
character support — changes with the providers enabled at that moment. Read that
table every time instead of memorizing limits; submitting something it does not list is
rejected, and the rejection tells you what the model actually accepts right now.
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.
Omit --resolution unless the user asked for a specific tier. The server then uses
that model's own default — the first resolution the model lists, which is 480p on the
value models (seedance2, seedance2_5, seedance2_fast, seedance2_mini,
mmh3_promo) and 720p on the rest. It is the same tier the web preselects, and
quote resolves it the same way, so the quote and the later charge cannot drift apart.
Passing a higher tier than the user asked for silently costs them more credits.
clipcat image --model)Prices below are the shipped defaults; they are server-side config and can be
changed without a release, so quote from clipcat models (imageModels), not
from this table.
| Model ID | Name | Credits / image |
|---|---|---|
gptimage2 | GPT Image 2 | 20 (default) |
gptimage25flare | GPT Image 2.5 Flare | 22 |
gptimage25sunburst | GPT Image 2.5 Sunburst | 22 |
nanobana2 | Nano Banana Pro | 20 |
Image generation is charged per model, per image. Only pass --model when the
user asked for a specific model — omit it and the server uses gptimage2. Tell
the user the per-image cost before submitting; the costCredits field in the
submit response is what was actually charged. As with video, the imageModels
section of clipcat models is the live authority on the list and the prices.
--lang)en zh fr de ms vi th ja ko id fil es pt ar
--lang is required on replicate and product_video — there is no default. It sets
the spoken/subtitle language of the finished video, so confirm it with the user (alongside
model / duration / resolution / credits) before submitting. A value outside this list is
rejected by both the CLI and the server.
--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.
clipcat -h first if unsure which command to use.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.replicate, product_video, generate, tiktok publish): submit once to get the checklist + confirmId (no charge, nothing created), show the user what came back — parameters / full prompt / totalCredits for a generation, account / caption / privacy / schedule for a publish — wait for an explicit yes in the conversation, then run --confirm <confirmId> in a later turn. Never confirm on your own and never chain the two calls in one turn. Never compute the credits yourself — let the checklist (or clipcat quote) return them. For tiktok publish, say plainly that it posts to the user's own public account and cannot be taken back, and treat a confirm that returns no taskId as a failure, never as a post.generate: read clipcat models --raw first (its limits are the only authority), then the same two-step flow as the other paid video commands — submit once for the checklist + confirmId, wait for an explicit yes, then --confirm <confirmId>. --dry-run is an optional preview that also returns reusable clipcat:// refs; it is not the confirmation.schedule create / delete / run: confirm with the user first — a schedule spends credits on every run without asking again.--resolution unless the user explicitly asked for a tier — the server applies that model's own default (480p on the value models, 720p on the rest), and quote resolves it identically. Never silently upgrade to 720p/1080p — higher resolution costs more credits.--prompt-file - with a quoted heredoc (see "Passing prompts"); verify the Prompt sent (N chars) echo after submit.query_task across turns to track long-running tasks.X-Amz-* params that break if truncated.