clipcat

Clipcat CLI

此技能刻意保持简短。详细的标志和支持的取值应以 CLI 本身为准——始终将 clipcat -h 和 clipcat <subcommand> -h 视为首要参考。唯一可能无法通过 -h 获取最新信息的是模型目录：模型会在不同版本之间上架或下架，因此，当前有哪些模型、分辨率和时长，应以 clipcat models 为准。

安装

先运行 clipcat --version——如果显示版本号，说明已安装 clipcat；跳到 API 密钥部分。如果找不到此命令，请根据平台进行安装：

macOS / Linux / Git Bash：

curl -fsSL https://clipcat.ai/cli | bash

Windows（PowerShell，不使用 bash）：

irm https://clipcat.ai/cli.ps1 | iex

然后设置 API 密钥（见下文）。稍后可通过 clipcat update 更新（会重新运行安装程序；已保存的配置会保留）。

Windows 沙盒说明（Codex 等）

如果 Windows 安装失败，并出现 SEC_E_NO_CREDENTIALS、AcquireCredentialsHandle、0x8009030E、"The underlying connection was closed" 或「基础连接已经关闭」，说明你处于受限沙盒（例如 Codex Windows 沙盒）中，Windows TLS 堆栈（Schannel）无法打开凭据——Invoke-WebRequest 和系统 curl.exe 在此环境中都会失败。安装程序会自动改用 Node 重试下载（其 OpenSSL 不受 Schannel 限制），因此在沙盒中安装 Node 通常就能解决问题。如果仍然失败，请向用户显示安装命令，并让他们在沙盒外的常规 PowerShell 中运行，或请他们批准在沙盒外运行——不要继续尝试不同的命令。

API 密钥

在本地配置文件中设置密钥——这是唯一可靠的方法：

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

前往 https://clipcat.ai/workspace?modal=settings&tab=apikeys 获取密钥。优先使用配置文件，而不是 CLIPCAT_API_KEY 环境变量：沙盒中的 Agent（例如 Codex）会过滤掉名称中包含 KEY/SECRET/TOKEN 的环境变量，因此通常无法看到该变量。（OpenClaw 会自动注入 CLIPCAT_API_KEY；设置后，它会覆盖配置文件中的值。）

此 CLI 的用途

clipcat 是所有 Clipcat AI 视频生成工作流的本地入口：

• 查询 TikTok 电商数据：创作者、商品、店铺、视频、直播、搜索
• 从爆款提示词库生成可直接用于拍摄的带货视频提示词
• 使用你的商品复刻爆款视频
• 根据图片生成商品视频
• 直接使用你自己的提示词和素材生成视频，并将内容原样发送给模型
• 使用文本提示词生成 AI 图像，支持 GPT Image 2 / GPT Image 2.5（Flare / Sunburst），并可选提供参考图像
• 将脚本转换为 mp3 配音（文本转语音，可选预设或克隆语音），可重复用作参考音频
• 分析视频（脚本、场景、音乐）
• 下载 TikTok/Douyin 视频
• 将完成的视频发布到你自己的 TikTok 账号（直接发布或保存到草稿箱）
• 安排 Agent 提示词，让其每天或在选定的星期几自动运行
• 查询异步任务状态

默认 Agent 工作流

1. 从 clipcat -h 开始，查看所有命令。
2. 使用任何命令前，先运行 clipcat <subcommand> -h 查看标志。
3. 默认使用 JSON 输出。
4. replicate / product_video / generate / tiktok publish 需要分两次调用提交： 第一次调用不会收费，也不会创建任何内容，而是返回清单和 confirmId；你需要 向用户展示该清单，等待明确确认，然后再运行 --confirm <confirmId>（参见“双步确认”）。
5. 如果任何命令在标准错误输出中显示更新提示（⬆ clipcat X is available … Run: clipcat update），运行一次 clipcat update，然后继续。 如果已是最新版本，该命令会自动跳过，因此可以放心运行。

选择合适的命令

TikTok 电商数据——实体命令

这些是名词-动词命令：clipcat <entity> <verb>。运行 clipcat <entity> -h 可列出动词，运行 clipcat <entity> <verb> -h 可查看标志。

• creator <list|rank|profile|enrich|trend|posts|sales-videos|lives|products|followers|following|region|milestones> — TikTok 创作者／网红
• product <list|rank|detail|trend|reviews|live-comments|creators|videos|lives> — TikTok Shop 商品
• seller <list|rank|detail|trend|catalog|inventory|creators|videos|lives> — TikTok Shop 店铺
• video <list|rank|snapshot|sales|trend|comments|captions|products|hashtag> — TikTok 视频
• live detail — 直播间详情（仅在直播期间）
• find <creators|products|videos|lives|hashtags|music|photo|all> — 关键词／图片搜索；find all 是范围最广的备用选项

有两个数据源，命令名称已替你选好数据源。 无需考虑 --mode 标志——根据你需要的数据选择：

你需要	命令	可获取内容	不可获取内容
创作者的近期帖子	creator posts	任意公开创作者的帖子，按时间从新到旧排列	无逐条视频的销售额／GMV
创作者的可购物视频	creator sales-videos	每条视频的销售额和 GMV，可排序	仅限历史数据集中的创作者
创作者当前的个人资料	creator profile	任意公开创作者	无累计商务指标
多位创作者的商务指标	creator enrich	批量查询，最多 10 位，提供累计指标	仅限已收集的创作者
单条视频的当前状态	video snapshot	任意公开视频	无销售额／GMV
查询已有视频 ID 的销售额	video sales	批量查询，最多 10 条，提供销售额和 GMV	仅限已收集的视频
可按评分筛选的评价	product reviews	评分筛选、分页	数据略旧
最新评论	product live-comments	最新评论，需指定 --region	无评分筛选
店铺的历史记录（含已移除商品）	seller catalog	销售额和 GMV，可排序	不包括当前上架商品
店铺当前上架的商品	seller inventory	当前商品，需指定 --region	无销售额／GMV

历史数据集并未涵盖所有内容（数据收集受成本限制），因此 sales／catalog／enrich 相关命令经常返回“未收集”——当 ID 来自实时搜索时，约 10 次中有 4 到 6 次如此。通过 … rank／… list 获取的 ID 本身就在数据集中，几乎每次都能查到。空结果表示未收集，而非不存在——请改用实时命令查询，不要重试。绝不要向最终用户透露“离线”／“实时”这些字眼；应表述为“历史数据”和“最新数据”。

分页：每次调用返回一页，并计费一次。历史列表／排名命令使用 --page／--page-size（--page-size 最大为 10；超过上限的值会被截断，响应会在 pagination_corrected 中说明；如需查看更多行，请使用 --page 2、--page 3……）；实时列表使用前一页返回的 --offset／--cursor／--scroll-param。逐页重复命令即可获取更多内容（--max-pages 已弃用且会被忽略）。

两个数据源的分页机制不通用。 历史命令（creator sales-videos、product reviews、seller catalog）按页码分页；对应的实时命令（creator posts、product live-comments、seller inventory）按游标分页，页码不能转换为游标。如果对实时列表使用 --page，CLI 会直接拒绝；如果旧版客户端仍发送该参数，响应中会包含 pagination_ignored——这表示返回的是数据源的第一页，而非你请求的页码。请停止按原页码翻页，改用 next 中的令牌继续；重复使用页码会返回相同的行，并再次扣除 6 点额度。 空结果也是一种答案，而不是失败。 历史数据集并未涵盖所有内容，因此空结果通常表示“该数据集未收录”，而不是“不存在”。响应会附带 try_instead，其中包含可直接运行的另一数据源命令，以及你能获得的内容（实时：覆盖范围完整，不含销售额/GMV；历史：包含销售额/GMV 和排序，但仅限已覆盖的实体）和仍需添加的任何标志。切换数据源需要单独计费——只有在需要这些字段时才切换。不要重复查询同一空结果。

错误会告诉你是否应该重试。 失败时会附带 error_kind 和 retryable： transient（速率限制或短暂波动——几秒后重试同一命令）、invalid_params（消息会明确指出错误所在——修正标志，切勿原样重试）、temporarily_unavailable（重试无济于事；更改查询或稍后再试）。

额度不足：读取命令每次需 6 个额度（prompt search 需 3 个，仅在用完套餐包含的免费额度后扣除）；余额不足时，命令会报错且不返回数据。

数据查询指南（精简版）：

• 按链式流程传递 ID，不要猜。 先发现实体（<entity> list|rank、find …），从结果中获取 ID，再调用详情、趋势或关系类操作。 批量操作使用逗号分隔的 ID（--user-ids、--product-ids、 --video-ids，≤10）。
• ID 的来源决定了哪些命令能回答问题。 来自 find … （实时搜索）的 ID 可以对应任何公开实体，因此要接着使用实时命令： video snapshot、creator posts、creator profile。来自 … rank / … list 的 ID 按定义属于历史数据集，因此要接着使用 video sales、creator sales-videos、creator enrich、seller catalog。将实时搜索得到的 ID 直接用于销售数据命令，是最常见的浪费积分方式——find videos 得到的 ID 约有十分之四不在销售数据集中。如果需要查询实时发现对象的销售数据，请明确说明，而不要翻页查询从未采集过的数据。
• 从有商业活动的实体开始获取关系查询的种子。 子资源操作 （creator products|lives、product creators|videos|lives、seller lives、 video products）对活动较少的 ID 会返回 []。从 … rank 或按销售额／粉丝数排序的 … list 获取种子，不要随便选一行，否则可能得到空结果。
• … rank 需要较近的 --date。 传入目标时段中的任意一天，后端会自动对齐到该时段的锚点（周→该周的周一，月→该月的 1 日）。 它绝不会静默返回其他时段的数据：如果该时段尚未结束，或数据尚未生成（T+1，通常在午后生成），你会得到 data: []，以及包含 anchor/start/end 的 period（requested / latest_available / previous）和一个指出应重试的确切 --date 的 hint——按提示重试，不要重复查询同一时段。日期必须落在由 --rank-type 决定的新鲜度窗口内，窗口从今天向前计算：day ≤30d、week ≤6mo、month ≤12mo。过于久远的日期（例如去年）会在上游被拒绝，并报错 rant_type N only support …——将日期向今天方向调整，不要切换 rank-type。
• 类别筛选使用数字 ID，并按层级区分。 要将 rank / list 限定到某个类别，先运行 category resolve --keyword <term>（例如 lipstick / 口红；CJK 会自动使用 zh 类别树）。它会返回每个匹配项的层级和祖先 ID {l1_id, l2_id?, l3_id?}（任意地区都可使用这些 ID）。传入目标命令接受的层级 ID： product/seller 的 rank/list 使用 L1→--category-id、L2→--category-l2-id、 L3→--category-l3-id（--category-id 仅接受 L1——不要在此处传入 L2/L3 ID）。 传入的层级必须构成同一条父子链；重复或不匹配的 ID 会在本地被拒绝（不耗费积分），issues 中会列出出错字段，suggested 中会给出正确 ID——复制后重新发送。issues 中的每项都包含 field、reason、value、本地化的 message，以及结构化的 detail（同一信息的机器可读形式——代码中进行分支判断时优先使用 detail，向用户展示时使用 message）。然后： creator rank 可通过 --product-category-id 接受任意层级；video rank 只接受 L1（l1_id）——传入 L2/L3 ID 时，会自动提升到其 L1 祖先，导致筛选范围扩大（响应会在 category_level_corrected 中说明）。如果 hint 的置信度较低，则运行 category tree（查看 L1+L2 概览），按含义选择分支，再运行 category tree --parent <that L2 id> 展开其 L3 子类。普通关键词搜索（非排行榜）使用 find products --keyword，无需 ID。
• find products 只返回 product_id（这是一个搜索索引）。要获取标题、价格和指标，请将这些 ID 传给 product detail。
• 空的 [] / null 表示“没有”，不是错误。 重复相同的空结果查询时，可能会返回 cached: true 和 retry_after（ISO 时间戳）：后端已记住该筛选条件没有数据，并会在该时间后自动重新探测——不要反复查询，改用其他筛选条件或继续下一步。已知数据稀少／行为特殊的项： creator region（结果不可靠 → 改为从 creator profile 读取 region）、 video captions（许多视频没有字幕）、live detail（仅在直播间正在直播时可用）、 seller inventory（店铺当前没有上架商品时为空——要查看历史记录，请使用 seller catalog）。
• 响应已由服务端筛选，仅保留关键信息（ID、核心指标、名称、重要链接； 图片已转换为可访问的 URL）——无需处理原始数据块。
• 所有金额均为 USD。 所有价格／平均价格／GMV 字段（min_price、 max_price、spu_avg_price、*_gmv_*_amt 等）都是换算为 USD 的数值，与 --region 无关；响应会附带 "currency": "USD" 以作确认。绝不要使用 ¥／円 等本地货币符号标注这些数值。如果报告需要当地货币（例如日本市场研究需要 JPY），请使用当前汇率从 USD 换算，并注明结果为近似值。

爆款带货提示词生成器 — clipcat prompt search

Clipcat 自有的结构化提示词库，每条提示词都根据一条真正带动销量的 TikTok 视频反向拆解而来，覆盖各个 TikTok 市场和品类，并按真实 GMV 排名。 这不是 TikTok 搜索：这里的条目已经拆解并改写成提示词，可直接交给视频模型使用。

用户询问带货视频的提示词、创意、脚本或切入角度时，请先从这里查找， 不要从头编写。 背后有成功视频佐证的提示词才是关键；凭空编写的提示词只是猜测， 而用户无法分辨两者的区别。

第 1 步 — 查找最匹配的已验证视频

• prompt search --query "<what you want>" — 对提示词库进行语义 + 关键词搜索。 描述一种感觉（“温暖的室内光线、手持近景、真人出镜”），或指定确切内容（品牌、ASMR、 OOTD）都可以；两种方式会融合使用，因此不必猜测哪种查询风格更合适。可选筛选条件：--region（小写的 市场代码）、--category（TikTok Shop L1 代码，例如 beauty-personal-care）、 --video-type（real-review | ootd | asmr | unboxing-pov | …）、--limit（1-20）。 根据用户自己的产品和受众构建查询内容——说明产品是什么、面向谁、所在市场，以及用户想要的氛围。 只用宽泛的品类名称（“护肤”）查询，会检索到提示词库中最普通的内容。 该命令的定价不同于其他读取命令：每个付费方案都包含一定数量的免费搜索，超出额度后每次调用收费 3 个积分（其他读取命令统一收费 6 个积分）。 响应中会包含 quota.remaining / quota.free_quota / quota.cost_after_quota — 额度所剩不多时，请告知用户剩余额度，避免下一次调用带来意外。
• 在信任搜索结果之前，先检查 weak_match 和 degraded。 提示词库会返回现有的最相近条目，因此结果列表完整并不代表结果一定匹配。 weak_match: true 表示没有接近匹配的条目——请说明这一点，并建议改写查询或移除筛选条件，而不要把最接近的条目当作答案。 degraded: true 表示语义搜索不可用，仅运行了关键词匹配： 结果可能不完整，并且该次搜索不收费（会退还额度）。 命中数量少于 --limit 很正常，也说明检索结果较为准确——系统只会返回足够相关的条目，因此，较窄的 --region + --category 组合确实可能只返回少数结果。

每条命中结果都包含完整的 prompt 文本（英文版本为 prompt_en）、原视频的指标（GMV、销量、播放量）、matched_facet（查询命中的提示词部分 — 风格 / 摄像 / 画外音 / …）、原始 TikTok 视频的 source_video_url，以及公开页面的 detail_url。

步骤 2 — 将热门视频改写成适合用户自己的提示词

切勿原样返回素材库中的提示词：那是在推销别人的产品。将最佳结果（或 2–3 个结构一致的结果；若结构各异，则综合提炼成一个模板）改写成适用于这位用户产品的提示词：

• 保留促成销售的要素：开场钩子及前 1–2 秒的内容、镜头顺序和节奏、摄影语言、灯光、是否有出镜主持人及其类型、旁白语气、促销机制、结尾的 CTA。
• 替换产品及其卖点、屏幕文字、旁白内容，以及任何因市场而异的元素（语言、货币、本地化措辞）。
• 不要沿用无法证实的宣传说法。 评分、销量数据、奖项、前后对比和功效声明都属于原产品——删除，或向用户询问其自有信息。
• 适配目标模型：提示词必须符合你将提交的 --duration，并匹配其所包含的镜头数量（5 秒的视频只能容纳 2 个镜头，而不是 6 个）；使用 --lang 指定旁白语言（必填——请谨慎选择，CLI 没有默认值）。
• 在消耗额度之前，先向用户展示最终提示词，以及作为依据的 detail_url（和 source_video_url）——引用真实视频，才能证明这不是你凭空编造的提示词。

步骤 3 — 开始生成

• 只有产品图片 → 使用 product_video，通过 --prompt-file - 传入改写后的提示词。
• 想以原视频的动作和剪辑为参考 → 使用用户的 --images，通过 replicate --url <source_video_url> 执行（TikTok 链接会额外收取 10 个额度的下载费用）。
• 这两种方式都需要付费，且都分两步操作：提交 → 向用户展示返回的检查清单 → 等待用户明确同意 → 执行 --confirm <confirmId>（参见“两步确认”）。

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>

视频生成与工具

选择视频命令：除非用户另有要求，否则默认使用 Agent 模式——如果用户想用自己的产品重拍热门视频，则使用 replicate；如果用户想根据产品图片编写脚本，则使用 product_video。这两种方式都会为用户完成脚本编写和分镜，用户只需提供产品图片和一句话需求。

generate（原始模式）会将提示词和素材原封不动地发送给模型——不会使用 AI 编写脚本、制作分镜或合成产品镜头——因此，输出效果完全取决于你编写的提示词和参数：构图、镜头运动、节奏和旁白都由你负责；模型支持的分辨率、时长和素材模式也必须由你自行通过 clipcat models --raw 查询后选择。仅当用户已经准备好确切的说明和素材，或明确表示不希望 Agent 改写其想法时，才选择此模式。如果不确定，请询问：“你希望我严格按照你的描述生成，还是让 Agent 为你编写脚本？”——绝不要默认让用户使用原始模式。

• generate — 原始视频生成：按原样将你的 --prompt 和素材发送给模型。先运行 clipcat models --raw——它是当前哪些模型支持此功能以及各模型接受哪些内容的唯一权威依据。根据你设置的标志自动选择两种素材模式之一：参考图像（--image 本地文件 / --image-url URL 或 clipcat:// 引用，可选 --character-id、可选 --ref-video、可选 --ref-audio），或帧（--first-frame(-url)，以及可选的 --last-frame(-url)；不支持角色、参考视频或参考音频）。还支持 --resolution、--duration、--size（9:16、16:9，或在 clipcat models --raw 的 Ratios 列列出 adaptive 的模型上使用 adaptive）、--enhance、--dry-run、--expected-credits。通过 --confirm 分两步提交（见下文）。此处的 --character-id 仅接受数字 ID（不接受 @sora 名称或图像 URL）。--ref-audio 仅接受 clipcat:// 引用——先用 clipcat asset upload <file> 上传本地音频文件，并传入输出的 ref（若音频已在素材库中：clipcat asset list --type audio）。大多数模型完全不接受音频（查看 clipcat models --raw 中的 raw.maxAudios）；不能单独提交音频（需与参考图像或视频配对），且服务器会自行测量音频时长——添加音频后请使用 --dry-run 重新报价。参考文件和参考网页链接仍仅限网页端使用——没有对应的标志。
• models --raw — 原始生成能力表：按模型列出图像模式、图像数量范围、帧槽位、参考视频限制、提示词上限、角色支持情况、Ratios 列（该模型接受的宽高比——只有支持的模型才会显示 adaptive），以及各组合的实时积分费用。若模型的 RefVideo 列显示 +output ≤Ns，则参考视频秒数与 --duration 共用此额度——超出后提交会被拒绝。这些限制会随着当前启用的提供商而变化——请查看表格，切勿想当然。 如果显示此账号未开放原始生成，请改用 replicate / product_video。
• quote — 返回某个特定生成任务的准确积分费用（--model + --resolution + --duration，TikTok/Douyin 复刻还需 --url/--social，超分辨率还需 --enhance）。可选的费用预览，不是确认步骤：服务器会完成所有计算，并返回 totalCredits（已包含增强费用）以及 enhanceCredits / enhanceBlocked。适合比较模型或为 --expected-credits 提供数值；实际向用户展示的确认清单来自提交本身（见“分两步确认”和“超分辨率”）。
• models — 浏览所有可用的视频模型及其积分费用（离散价格使用 prices，范围价格使用 creditsPerSecond）、图像模型及其单张图像积分费用（imageModels），以及你的余额。用户尚未选择模型或报告的模型不可用时使用。此列表为实时信息，仅包含当前有提供商的档位——若某个分辨率或时长未出现在 resolutions / prices 中，提交时就会被拒绝，因此切勿提交此处未列出的组合。
• replicate — 使用你的产品图像复刻热门视频。通过 --url（TikTok/Douyin 链接、直接 URL，或先前上传所得的 clipcat:// 引用——自动检测类型）或 --video（本地视频文件，最大 100MB；通过预签名 URL 上传，然后在服务器端缩小；重新复刻同一文件会复用上传内容；不收取下载附加费）提供参考视频——必须且只能提供其中一种。通过 --image（本地文件）或 --image-url（URL）提供产品图像；本地文件和 URL 可以混用。支持 --model、--duration、--size（仅接受 9:16 或 16:9）、--lang（必填，无默认值）、--resolution、--enhance（超分辨率，见下文）、--character-id、--expected-credits。通过 --confirm 分两步提交（见下文）。
• product_video — 仅根据产品图像生成视频（无参考视频）；通过 --image（本地文件）或 --image-url（URL）提供图像；本地文件和 URL 可以混用；--size 仅接受 9:16 或 16:9；--lang 必填（无默认值——这是视频的口播/字幕语言，请与用户确认）；支持 --enhance（超分辨率，见下文）、--expected-credits。通过 --confirm 分两步提交（见下文）。
• image — 使用 GPT Image 模型，根据文本提示词生成 AI 图像；可通过 --image（本地文件）或 --image-url（URL）提供最多 5 张参考图像。使用 --aspect-ratio 选择 1:1（默认）/ 16:9 / 9:16。尺寸提示（9:16/16:9/1:1、portrait/landscape/square、竖版/横版/方图、banner、wallpaper）必须同时出现在 --prompt 和 --aspect-ratio 中——--aspect-ratio 设置画布，提示词中的尺寸提示用于确定构图。不要擅自添加用户未要求的尺寸。--model 用于选择图像模型：gptimage2 | gptimage25flare（GPT Image 2.5 Flare）| gptimage25sunburst（GPT Image 2.5 Sunburst）| nanobana2（Nano Banana Pro）——每张图像的积分费用由服务器配置，因此请从 clipcat models 的 imageModels 部分读取。除非用户指定了具体模型，否则不要传入 --model（省略时使用服务器默认模型，该默认模型由服务器端配置，不一定是 gptimage2），并且提交前要告知用户每张图像的积分费用。
• list_images — 列出服务器上的图像生成任务；支持 --status / --limit / --page 筛选条件，以及 --scope all / --scope <member-user-id>（仅限所有者/管理员；会添加 creatorName）
• breakdown — 分析视频（脚本、场景、音乐）；若之前已分析过，会立即返回缓存结果
• download — 下载 TikTok/Douyin 视频（返回签名 URL）；缓存结果会立即返回
• query_task — 按 ID 和类型检查任务状态（--type replicate | product | raw | breakdown | download | image）。省略 --task-id 可恢复最新的本地任务。使用 --enhance 时，每个 videos[] 项都会包含自己的 status / enhanceStatus（见“超分辨率”）。工作区所有者/管理员也可以查询其成员的任务。
• list_tasks — 列出服务器上最近的视频相关任务（必须指定 --type：replicate | product | raw | breakdown | download）。图像任务使用 list_images。--scope all / --scope <member-user-id> 可将范围扩展到整个工作区（仅限所有者/管理员；会添加 creatorName）；默认只列出你自己的任务。
  • 每行有两个不同的 ID。 taskId 是项目 ID（即 /project/<id> 链接中的 ID）；其中每个已完成的视频都有自己的 videos[].videoTaskId。一个项目可以包含多个视频（每个脚本对应一个），因此两者绝不会相同。任何针对单个视频执行操作的命令——尤其是 tiktok publish --video-task-id——都必须使用 videoTaskId，而不是 taskId。query_task 返回相同的一对 ID。
• character list — 列出保存到你账号中的角色（id、name、status、type）。id 是你在 replicate / product_video / generate 中传给 --character-id 的值；只有 status: completed 的角色可用。支持 --status / --limit / --page / --sort-by / --sort-order，以及 --scope all / --scope <member-user-id>（仅限所有者/管理员；会添加 creatorName）。免费（账号元数据，不消耗积分）。
• asset upload <file> — 将本地图像（jpg/png/webp，≤10 MB）、视频（mp4/mov，≤150 MB）或音频（mp3/wav/m4a/aac，≤10 MB）上传到素材库，方式与网站相同，并打印其 clipcat:// 引用（以及服务器测得的音频/视频时长）。将图像的 ref 原样传给 --image-url / --first-frame-url，将 mp3/wav 音频的 ref 传给 --ref-audio（可以上传 m4a/aac，但 --ref-audio 不接受这些格式——请先转换）；视频只会保留在素材库中——对于 generate --ref-video，请直接传入本地文件。--name 用于设置显示名称。免费（占用存储配额，不消耗积分）。
• asset list — 列出保存到你账号中的素材（type、name、时长、大小）及其 clipcat:// 引用。将此引用传给 --image-url / --first-frame-url / --ref-audio；仅当它以 clipcat://analyse/video/ 开头时，才能传给 --ref-video（clipcat://assets/ 下的视频会被拒绝——请改为传入本地文件）；请逐字符复制，切勿重新输入或拼接。这是查找用户在网站上上传内容的引用的方法。支持 --type image|video|audio|document / --q <name> / --limit / --page，以及 --scope all / --scope <member-user-id>（仅限所有者/管理员；会添加 creatorName）。免费（账号元数据，不消耗积分）。

发布到 TikTok — clipcat tiktok

名词-动词结构：clipcat tiktok <connect|connect-status|accounts|creator-info|publish|tasks|task|cancel>。 发布不消耗积分——配额限制的是已连接的账号（免费版 0 个 / 基础版 3 个 / 创作者版及以上不限）。 只有无水印的渲染视频才能发布（TikTok 禁止 API 客户端给创作者内容添加水印）；带水印的视频会在提交时被拒绝，并返回 watermarked_video。

• connect — 一次性授权。授权页面会在浏览器中打开；如果没有图形界面（SSH / 容器），则会降级为在标准错误输出中打印链接，这样 --json 仍可正常解析。回调会发送到服务端，而不是这台机器，因此可以在手机上打开页面。轮询 connect-status --state <state>；如果用户取消，状态会显示为 denied，无需继续等待。
• accounts — 查看已连接的账号及其 openId；其他所有子命令都需要 --open-id。
• creator-info — 每次直接发布前都要运行此命令。 privacyLevelOptions 是判断账号接受哪些 --privacy 值的唯一依据（私密账号只提供 SELF_ONLY）。它还会报告 maxVideoPostDurationSec，以及账号是否禁用了评论 / 合拍 / 拼接功能。如果隐私级别被拒绝，请在此查看可用选项，不要重试相同的值。
• publish — 分两步操作，与付费视频命令类似（参见“两步确认”），但原因不同：此操作不消耗积分，但它是唯一会将内容推送到用户自己的公开 TikTok 账号的命令；一旦帖子上线，此处就无法撤回。首次调用会进行校验，并返回一份清单，列出即将发布的所有内容——账号、视频、帖子模式、说明文字、可见对象、评论 / 合拍 / 拼接设置、AIGC 和品牌内容披露信息、发布时间——以及一个 confirmId。视频来源必须且只能指定一个：--video-task-id（已完成的 Clipcat 视频——list_tasks / query_task 返回的 videos[].videoTaskId，而非项目级 taskId；传入项目 ID 会报错 errorCode=video_task_is_project_id，错误信息中会给出正确的 ID）、--asset-id（素材库），或 --video <path>（本地文件，会先上传并计入存储配额）。
  • --mode direct（默认）会立即发布，并且必须指定 --privacy。--mode draft 只会将视频发送到 TikTok 的草稿箱——--title、--privacy、--allow-*、--brand-*、--aigc 和 --cover-ts-ms 在此模式下均会被忽略；用户需要在 TikTok 应用中自行填写这些内容。
  • 互动选项（--allow-comment / --allow-duet / --allow-stitch）默认关闭，符合 TikTok 的用户体验指南；如果账号禁用了这些功能，服务端会强制关闭。
  • --brand-content（付费合作）不能与 SELF_ONLY 一起使用。
  • --schedule 可将帖子排入稍后发布的队列（仅限直接发布，时间范围为 5 分钟至 30 天后）。必须指定时区偏移量——2027-03-01T20:00:00+08:00 表示北京时间 20:00（UTC+8），2027-03-01T12:00:00Z 表示同一时刻的 UTC 时间；不带偏移量的 2027-03-01T20:00:00 会被拒绝。大多数用户说的是自己时区的当地时间，因此应附上其时区偏移量，而不要在心里将时间换算为 Z。此处会忽略 --wait——任务会返回为 SCHEDULED，可用 cancel --task-id <id> 取消。
  • 与生成命令一样，此操作是异步的：上传会在服务端运行，命令会在任务创建后立即返回。--wait 会每隔 15 秒轮询一次，因此建议先提交，再在后续轮次调用 task --task-id <id>，以免工具调用超时。
• tasks / task --task-id <id> / cancel --task-id <id> — 列出发布任务、查看单个任务，或取消仍处于已安排状态的任务。

定时任务 — clipcat schedule

名词-动词结构：clipcat schedule <list|show|create|update|enable|disable|delete|run>。 定时任务是已保存的提示词，Clipcat Agent 会在 --timezone（IANA 时区，例如 Asia/Shanghai）中的 --at（24 小时制 HH:mm）时间自行运行， 每天运行，或在 --days 指定的日期运行（mon,wed,fri / weekdays / weekends）。每次运行都会在网站上创建新的聊天，并发送一封电子邮件 （--notify none 可关闭邮件通知）。

• 费用：管理操作免费。每次运行——无论是按计划运行还是通过 run 运行——都按普通 Agent 聊天轮次计费，并且最多可提交 3 个生成任务，无需任何人确认。仅限付费方案；每个账户最多可创建 100 个定时任务（包括已停用的任务）。
• create 需要 --title、--prompt（或 --prompt-file -）、--at、--timezone。请询问用户所在的时区，切勿猜测。运行时不会记得本次对话：请将提示词写成完整、独立的指令，并原样粘贴任何 clipcat:// 引用。创建前，请与用户确认提示词、时间、日期和时区。
• update --id 只会更改你传入的标志；仅指定 --at 或 --days 时，会保留另一项（--days daily = 每天运行）。此命令不会启用或停用定时任务——请使用 enable / disable。
• 仅适用于 Agent 模式：在网站上创建的单击生成 / 视频生成定时任务不会显示在这里，且会返回 not_found。
• delete 会永久删除任务，run 会立即消耗额度——操作前必须先获得明确同意。run 会立即返回；随后使用 show --id 查看（lastStatus、lastResultUrl）。schedule_running 表示已有任务正在运行：不要循环重试。
• nextRunAt / lastRunAt 使用 UTC。

文本转语音 — clipcat tts

将脚本转换为 mp3 配音，同步处理（约 2-10 秒），可使用预设语音或克隆语音。生成的 mp3 会存入 资源库；返回的 ref（clipcat://…）是供 clipcat generate --ref-audio 使用的参考音频，可直接使用。

• 费用：每 100 个字符约 5 个额度（最低 1 个），所有模型价格相同，仅在成功时收费。克隆免费。--dry-run / tts voices 提供权威信息——请在合成前报出费用并告知用户。
• 模型（--model，通常省略）：seed-tts-2.0 是默认模型，仅支持预设语音，也是唯一支持词级时间戳的模型。克隆语音需要使用 cosyvoice-v3.5-plus（克隆语音的默认模型）或 fish-s2.1-pro。模型不支持的标志会被拒绝，不会收费。
• tts voices [--language en] [--model M] — 查看模型（预设 / 克隆 / 支持的标志 / 可用性）、推荐的语音 ID、--language 的可选值和价格。免费。未列出的语音 ID 会使用 seed-tts-2.0，除非指定了 --model。
• tts --voice <id|clone_<id>> --text "…"（长文本或带引号的文本：--text-file - <<'EOF' … EOF）。每次调用最多 1000 个字符——较长的脚本请按句子或场景拆分。可选参数：--language（文本必须使用该语言；seed-tts-2.0 搭配 en / zh-cn 时还会返回 words 时间戳）、--instruction（语气；其字符也会计费）、--speed / --volume（-50..100，0 = 正常）。
• --out <file> 也会将 mp3 保存到本地（若不带 --force，不会覆盖已有文件）。如果保存失败，音频仍会计费并保存在资源库中：请复用 ref / audioUrl，切勿重新运行。
• tts clone --audio <local file | clipcat://ref> [--start S] [--duration D] [--name N] [--transcript T] [--dry-run] — 免费；返回 voice: clone_<id>。样本要求：10–60 秒、单人说话、语音清晰；支持音频或视频（mp3 wav m4a aac ogg flac mp4 mov webm，≤20MB——会提取音轨）。较大的视频：使用 clipcat asset upload <file>（≤150MB），并传入命令输出的 clipcat:// 引用；如果文件已在资源库中：使用 clipcat asset list --type audio|video。其他 URL：请先下载。只能克隆用户有权使用的语音。
• tts clones [--q NAME] [--page N] [--limit N] [--scope mine|all|<userId>] — 查看用户克隆的语音。免费。

传递提示词（绝不要让 shell 篡改它们）

转义错误的 --prompt \"Create a 5s video\" 到达 CLI 时会变成 "Create——在第一个空格处被截断。现在，CLI 和服务端都会拒绝这类提示词，避免你为无效视频付费；不过，还是应该通过以下方式传递提示词，以防这种情况发生：

• 提示词包含引号、换行符、$ 或反引号 → 使用标准输入，不要使用内联标志：

  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
  

  带引号的分隔符 <<'EOF' 会禁用所有类型的展开，因此无需进行任何转义。 这适用于 bash / zsh / Git Bash。在 Windows PowerShell 中，不要通过管道传递——应写入 UTF-8 文件并传入其路径：

  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
  

  为什么在 Windows 上不能通过管道传递：Windows PowerShell 5.1 会使用 $OutputEncoding 将管道输出编码后传给原生程序，而它默认是 ASCII——所有中文/非 ASCII 字符都会悄无声息地变成 ?，而由 ???????? 组成的提示词看起来完全能通过所有引号检查。 如果必须通过管道传递，请先运行 $OutputEncoding = [System.Text.Encoding]::UTF8。（PowerShell 7 在所有地方默认使用 UTF-8，不受此影响；但上面的基于文件的写法两者都适用，所以直接用它即可。）另外请注意，@' 必须单独占一行，'@ 也必须单独占一行——写成单行的 @' … '@ 会导致语法错误。在 5.1 中，Out-File 不能替代 Set-Content -Encoding utf8：它默认使用 UTF-16，而 CLI 会直接拒绝这种编码。

• 绝不要将文件读入字符串后再以内联方式传递——不要使用 --prompt (Get-Content p.txt)。 在 PowerShell 5.1 中，Get-Content 会将 UTF-8 文件解码为 ANSI，产生乱码，而这些乱码本身是有效的 UTF-8，且不会触发任何引号异常：所有检查都会通过，你却会为无效视频付费。请传入路径（--prompt-file p.txt），让 CLI 读取字节。

• 简短的单行提示词可以继续以内联方式传递，例如 --prompt "…"。绝不要对外层引号使用反斜杠转义，也绝不要把已经加好引号的字符串再套上一层引号。

• --prompt 和 --prompt-file 不能同时使用（- 表示标准输入，否则表示文件路径）。

• 提交后，CLI 会打印 Prompt sent (N chars): …。请核对它是否与你的预期一致；如果 N 不对，说明命令行被篡改了，而不是你写的提示词有误。

• 如果提交因提示词引号错误而被拒绝，不要重试同一条命令——请通过 --prompt-file - 重新发送。拒绝发生在扣费之前。

两步确认

四个命令分两次调用提交，绝不能在同一轮中完成两步： replicate、product_video 和 generate 会消耗额度；tiktok publish 会发布到用户自己的公开账号，且无法撤销。绝不要自行计算额度——让服务端返回额度。

第 1 步 — 正常提交。 像平常一样运行完整命令。服务端会验证所有内容，但不会扣费，也不会创建任务；它会返回 data.confirmationRequired: true，其中包含 confirmId 和 confirmation 快照 （generationType、model、resolution、duration、size、lang、imageCount、完整提示词文本，以及额度明细 credits / downloadSurcharge / enhanceCredits / totalCredits），还有一个 instruction 字符串。退出代码为 0——这不是错误，因此不要重试或更改参数。

第 2 步 — 向用户展示核对清单，然后停止。 展示参数、完整提示词和 totalCredits，原样打印 instruction，并等待用户在对话中明确回复。沉默、“听起来不错”或你自己的判断都不算批准。绝不要在同一轮中接着执行第 3 步。

第 3 步 — 仅在用户明确同意后：

clipcat product_video --confirm cfm_7QK2M8   # or clipcat replicate / clipcat generate --confirm ...

--confirm 不能与任何业务参数组合使用——服务端会提交它在第 1 步中保存的快照，因此传入业务参数会悄无声息地不起作用（CLI 会在本地拒绝这种组合，以免让你误以为参数已生效）。管道选项（--output、--api-key、--base-url、--poll，以及 tiktok publish 的 --wait / --timeout）可以使用。要更改任何参数，请携带新值返回第 1 步，并让用户批准新的核对清单。

完整示例（Seedance 2，默认 480p，8s，TikTok 链接）：

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 — 协议相同，检查清单不同

三个步骤完全相同；变化的是要求用户批准的内容。 data.confirmationType 为 tiktok_publish（两个生成命令中则为 video），而 confirmation 快照包含账号、视频（来源、标题、时长）、发布模式、说明文字、隐私级别、评论 / 合拍 / 拼接、AIGC 和品牌自然内容 / 品牌内容披露标记、排期和封面帧——另外还包含服务端为你计算出的两个列表：

• forcedOff — 用户要求启用、但此账号已在 TikTok 设置中禁用的互动功能。这些功能发布时将处于关闭状态。请明确告知用户；不要重试。
• ignoredInDraft — 已传入但不会在 --mode draft 下发送的设置（TikTok 会从应用中读取这些设置）。这些值不会生效。

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

成功确认后会返回 taskId；没有 taskId 就表示没有发布任何内容——请将其报告为失败，绝不能说成已发布。低于 1.0.43 的 CLI 完全无法发布：服务端会拒绝并明确提示“run clipcat update”，因为这些版本会把确认清单误读为已创建的任务，并打印一个实际并不存在的发布任务。在第 1 步之前，仍值得运行 creator-info：它是唯一能确认账号接受哪些 --privacy 值的权威来源；如果 --video 指向大型本地文件，还能避免上传被拒。

可选附加操作，均独立于确认流程：

• clipcat quote 可在第 1 步之前预览费用（参数相同；添加 --url 以计入下载附加费，添加 --enhance 以使用超分辨率）。可用于与用户比较模型。切勿自行计算点数——让 quote 或第 1 步的检查清单返回点数。对于原始生成，请改用 clipcat generate --dry-run（quote 不涵盖原始生成的定价）。
• 原始生成的 --dry-run 也会上传素材并返回 clipcat:// 引用——将这些引用传入第 1 步即可跳过重复上传。它不是确认步骤，也不会返回 confirmId。
• 第 1 步中的 --expected-credits <n> 可为费用设定上限：只有实际费用更高时，服务端才会拒绝请求（实际费用较低——例如命中缓存或使用促销价——则会直接通过）。拒绝时会返回当前费用；请重新确认并提交。

用户尚未选择模型时（或你需要完整的模型列表时），运行 clipcat models，即可列出所有可用模型及其费用。

高级模型（例如 seedance2、happyhorse10）需要付费套餐；clipcat quote 会标记这些模型（premiumBlocked），服务端也会拒绝免费用户使用。

原始生成（generate）使用 --dry-run 获取报价，而不是 quote

clipcat quote 不涵盖 generate。请改为构建你打算提交的完整命令，并添加 --dry-run：它会验证所有内容、上传 / 解析素材，并返回与提交时收费相同的 totalCredits（报价和扣费使用相同的服务端计算，因此不会出现偏差）。它不会创建任务，也不会扣费。响应还会为上传的每项素材提供 clipcat:// 引用——请在正式提交时重用这些引用，避免重复上传：

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

将提示词指向特定素材

有些模型允许提示词按位置指定单个素材。clipcat models --raw 会在每个模型的 raw.mention 中报告此信息：

"mention": { "dialect": "at_en", "kinds": ["image", "video", "audio"],
             "examples": { "image": "@image1", "video": "@video1", "audio": "@audio1" } }

• 所有模型使用相同的表示法：@image1 / @video1 / @audio1。 只写这些内容，不要添加其他内容。服务会在分发时将其转换为上游模型所需的格式（@图片1、图1、[Image 1]、<IMAGE_REF_0>……），因此，为一个模型编写的提示词可以原样用于任何其他模型。
• kinds 仍因模型而异——它表示该模型可以被指向的素材类型（Grok 的上游只支持图像表示法，Omni 则不支持音频表示法）。提及不在 kinds 中的类型会被视为普通文本。
• 匹配时不区分大小写（@Image1 也有效），但请使用小写形式。
• 编号按类型分别计算，从 1 开始，顺序与传入素材的顺序一致——本地文件和 clipcat:// 引用都按你写下的顺序排列，无论是否混用。角色图像（--character）算作最后一张引用图像。
• 不允许重复传入同一素材（media_duplicate），因为上游会对其去重，之后的所有引用都会因此错位。
• 这只是一种柔性的自然语言提示，不会进行任何验证。提及未附加的素材只会被视为普通文本——但额度仍会照常扣除。
• 没有 mention 字段的模型无法指定其素材——上游从未说明该模型支持何种表示法。不要在提示词中提及素材。
• 提及在翻译后会让提示词变长（@image1 → <IMAGE_REF_0>），长度限制适用于翻译后的文本。--dry-run 会报告实际长度，因此应以它为准，而不是自己统计字符数。
• 参考帧（--first-frame / --last-frame）按角色绑定，而非按编号绑定，因此无法被提及。

引用视频（--ref-video）会被上传，其时长在服务端测量——某些模型会根据此时长调整价格（模型行会显示 repricedByReferenceVideo），因此添加或更改引用视频后，务必重新运行 --dry-run 并再次确认新的总价。

引用音频（--ref-audio）只能使用 clipcat:// 引用：使用 clipcat asset upload <file> 上传本地文件（命令会打印引用），或从 clipcat asset list --type audio 获取引用。其时长也会在服务端测量，某些模型还会据此计价——添加引用音频后请重新运行 --dry-run。音频不能单独使用：必须搭配至少一张引用图像或一段引用视频。

单个片段的时长限制因模型而异，并非全局统一。 clipcat models --raw 中每个模型行都包含 maxClipSec——单个引用片段允许的最长时长（Seedance 2.5 为 30s，其他模型均为 15s）。它与限制所有片段时长总和的 maxVideoTotalSec 相互独立。顶层的 clipRules.maxClipSec 只是所有模型中的最大值（当前为 30）；它仅用于上传步骤，因为此时尚未选择模型——切勿用它进行校验，否则它会放行 20s 的片段，而 Seedance 2.0 模型随后会在提交时拒绝该片段。请读取对应的模型行。

超分辨率（--enhance）

replicate、product_video 和 generate 支持使用 --enhance 720p|1080p|2k 提升成品视频的分辨率。规则如下：

• 档位必须严格高于生成分辨率，适用于 replicate / product_video：480p → 720p / 1080p / 2k，720p → 1080p / 2k，1080p → 2k，2k → 无可选档位。（generate 只要求输出档位有效，不会与生成分辨率进行比较，但提升到较低档位仍会消耗点数，因此请选择更高档位。）CLI 只会检查值是否属于枚举范围；档位规则由服务端强制执行。
• 仅限付费计划。 免费用户提交时会被拒绝；clipcat quote --enhance 会通过 enhanceBlocked: true 标明需要升级。
• 费用 = ceil(duration_sec / 10) × 档位费率（每 10 秒：720p = 10、1080p = 20、2k = 30 点数）。费用会延后收取——仅在基础视频成功后扣除。quote 会通过 enhanceCredits 返回此费用，并将其计入 totalCredits；请通过 --expected-credits 提交该 totalCredits。对于 generate，--dry-run 会返回相同的数值作为 enhanceCredits，并已计入其 totalCredits。
• 状态语义（query_task）：基础视频就绪后，会以 status: enhancing 出现在 videos[] 中，并提供可用的 videoUrl（原始视频）；但任务只有在增强完成后才会进入最终完成状态（标准的 1 分钟视频需要额外约 6–10 分钟）。enhanceStatus: failed → 任务仍会完成并交付原始视频，增强费用会退还。

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>

replicate：参考视频来源

clipcat replicate 需要通过 --url / --video 二选一提供参考视频：

• --url TikTok/Douyin 链接 → 调用 /replicate_from_social（下载额外消耗 10 点数）
• --url 直接视频 URL → 调用 /replicate
• --video 本地文件（最大 100MB）→ 通过预签名 URL 上传，然后调用 /replicate（无下载附加费用）。再次上传同一文件会进行去重（按内容哈希、按用户），因此重复复刻时会跳过上传。

使用社交平台 --url 运行前，务必告知用户额外需要 10 点数。

clipcat:// 资源引用

在之前轮次中看到的 clipcat://... 字符串是稳定的资源引用。将其原样传入任何 --image-url / --first-frame-url / --last-frame-url / --ref-video / --ref-audio / --character-id / replicate --url 标志；切勿在前面添加 https:// 或修改它们，服务端会将其解析为签名 URL。拼写错误的引用会在提交时立即被拒绝（不会扣除点数），因此切勿凭记忆重新输入。详情请参阅子命令的 -h。

没有资源引用？clipcat asset upload <file> 可上传本地图片 / 视频 / 音频文件并打印其引用；clipcat asset list 会打印账号中所有已有资源的引用（音频使用 --type audio），包括用户在网站上上传的资源。

--character-id 在 replicate / product_video 中接受以下三种形式：来自 clipcat character list 的数字 id（切勿猜测 id）、@<sora-username>，或图片 URL / clipcat:// 引用。generate 仅接受数字 id。

异步任务规则

replicate、product_video、generate、image 和 breakdown 均为异步操作。它们都会提交任务并立即返回任务 ID，不会阻塞。

典型耗时：image 约 3 分钟，breakdown 几分钟，product_video / replicate / generate 需 10 分钟以上。切勿尝试在单次工具调用中同步等待——所有现实中的 Agent 运行环境都有工具调用超时（通常为 60 秒），会在任务完成前很久就终止调用。务必按“提交 → 返回 → 轮询”的流程，跨多个轮次完成。

1. 任务 ID 会自动保存在本地的 ~/.clipcat/tasks.json 中。
2. 使用 clipcat query_task --task-id <id> --type <type> 检查状态。每次调用都会立即返回当前状态。省略 --task-id 可继续查询最新任务。在后续轮次中重复执行该命令（建议间隔：image 约 30 秒；breakdown / product_video / replicate 约 1–2 分钟），直到 status 为 completed 或 failed。
3. 使用 clipcat list_tasks --type <replicate|product|raw|breakdown|download> 查看服务器上指定类型的任务（raw = 来自 generate 的任务）。

query_task：自动恢复

不带任何标志调用 clipcat query_task，会自动读取 ~/.clipcat/tasks.json 中的最新任务并继续查询。无需记住任务 ID。

可用模型

所有用户均可使用试用模型；标准模型需要付费套餐。

模型 ID	时长	分辨率	备注
grok_imagine	10s、15s	480p、720p	试用。xAI Grok Imagine 1.5，仅支持 9:16 宽高比
veo3.1fast	8s、16s、24s	720p	试用。Google Veo 3.1 Fast，质量与成本均衡
omini_flash	10s、20s	720p、1080p	试用。Gemini Omni Flash，Google 最新模型
seedance2_mini	4–15s（任意整数）	480p、720p	试用，平台默认模型（省略 --model 时使用）。Seedance 2 Mini，性价比之选。免费套餐仅支持 480p——省略 --resolution 时也会使用该分辨率
mmh3_promo	10s、15s	480p、720p、2K	试用。MiniMax H3 补贴渠道，免费套餐也可使用
seedance2	4–15s（任意整数）	480p、720p、1080p	标准（付费）。ByteDance Seedance 2，顶级画质。默认 480p
seedance2_5	4–30s（任意整数）	480p、720p	标准（付费）。ByteDance Seedance 2.5，最新一代，片段最长 30 秒。默认 480p
seedance2_fast	4–15s（任意整数）	480p、720p	标准（付费）。ByteDance Seedance 2 Fast，快速版本。默认 480p
wan30	5–30s（任意整数）	480p、720p、1080p	标准（付费）。Alibaba Wan 3.0，片段最长 30 秒
minimax_h3	10s、15s	768p、2K	标准（付费）。MiniMax H3
happyhorse10	3–15s（任意整数）	720p、1080p	标准（付费）。Alibaba HappyHorse 1.1

clipcat models 是模型列表和各组合当前积分费用的权威来源——若模型未列于其中，说明该模型已停用，无论 -h 或本表如何显示，提交时都会被拒绝。只要 clipcat models 列出了 mmh3_promo，就优先选择它而非 minimax_h3：两者使用相同模型，但前者是限时补贴渠道，积分费用低得多，免费套餐也可能可以使用。 此表不适用于 clipcat generate（原始生成）——请运行 clipcat models --raw。原始生成仅支持其中一部分模型，时长档位范围更窄（它会直接调用模型，不进行拼接），且每个模型接受的内容——图像模式、图像数量范围、帧槽位、参考视频数量上限、提示词长度上限、角色支持情况——会随当时启用的提供商而变化。每次都要查看该表，不要死记限制；提交表中未列出的内容会被拒绝，拒绝信息会告知模型当前实际接受的内容。

此表中的档位是各模型提供的选项；clipcat models 显示的才是当前可用选项。提供商可能会因维护而停用，因此表中列出的档位可能会暂时消失。如果提交被拒并提示 "no available channel"，说明参数有效，但该档位当前没有可用的提供商——请重新运行 clipcat models，从最新列表中选择其他分辨率／时长／模型，重新报价并与用户确认。不要使用相同组合重试。

除非用户指定了具体档位，否则不要传入 --resolution。 此时服务器会使用该模型自己的默认值——即模型列出的第一个分辨率；对于价值型模型（seedance2、seedance2_5、seedance2_fast、seedance2_mini、mmh3_promo）为 480p，其他模型则为 720p。这与网页端预选的档位相同，quote 也会以相同方式确定档位，因此报价与之后的扣费不会出现偏差。传入高于用户要求的档位会悄悄扣除更多积分。

图像模型（clipcat image --model）

以下价格是发布时的默认值；这些价格由服务端配置，可以不经发布而更改，因此请从 clipcat models（imageModels）获取报价，不要依据此表。

模型 ID	名称	积分／张
gptimage2	GPT Image 2	20（默认）
gptimage25flare	GPT Image 2.5 Flare	22
gptimage25sunburst	GPT Image 2.5 Sunburst	22
nanobana2	Nano Banana Pro	20

图像生成按模型、按张收费。只有用户指定了具体模型时才传入 --model——否则省略该参数，服务器会使用 gptimage2。提交前请告知用户每张图的费用；提交响应中的 costCredits 字段表示实际扣除的积分。与视频一样，clipcat models 的 imageModels 部分是模型列表和价格的实时权威来源。

支持的语言（--lang）

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

replicate 和 product_video 必须传入 --lang——没有默认值。该参数设置成片中的口语／字幕语言，因此请在提交前与用户确认（并同时确认模型／时长／分辨率／积分）。不在此列表中的值会被 CLI 和服务器拒绝。

地区（--region）

ISO 3166-1 alpha-2，使用大写：US GB DE ES FR IT JP MX BR ID MY PH SG TH VN。由服务器强制校验；代码超出允许范围时，会返回当前允许的列表。

优秀的 Agent 行为

• 不确定该使用哪个命令时，先运行 clipcat -h。
• 用户要求提供带货视频的提示词／创意／脚本时：先运行 clipcat prompt search，将最接近且经验证有效的结果改写为适用于用户产品的内容，并注明其 detail_url。凭空编写会舍弃这类提示词能够广泛传播的唯一优势。
• 对于两步命令（replicate、product_video、generate、tiktok publish）：先提交一次以获取检查清单和 confirmId（不收费，也不会创建任何内容），向用户展示返回的内容——生成任务的参数／完整提示词／totalCredits，发布任务的账户／文案／隐私设置／排期——等待用户在对话中明确同意，然后在后续轮次运行 --confirm <confirmId>。绝不要自行确认，也绝不要在同一轮中连续调用这两个命令。不要自行计算积分，让检查清单（或 clipcat quote）返回积分。对于 tiktok publish，要明确说明这会发布到用户自己的公开账户，且无法撤回；如果确认后没有返回 taskId，则应视为失败，绝不能视为已发布。
• 对于 generate：先读取 clipcat models --raw（其限制是唯一权威依据），然后遵循与其他付费视频命令相同的两步流程——提交一次以获取检查清单和 confirmId，等待用户明确同意，再运行 --confirm <confirmId>。--dry-run 是可选的预览，也会返回可重复使用的 clipcat:// 引用；它不代表确认。
• 对于 schedule create／delete／run：先向用户确认——每次执行排期都会消耗积分，不会再次询问。
• 分辨率：除非用户明确指定了档位，否则不要使用 --resolution——服务端会应用该模型自身的默认值（价值型模型为 480p，其余模型为 720p），且 quote 的解析方式相同。绝不要在用户不知情的情况下升级到 720p／1080p——更高分辨率会消耗更多积分。
• 对于任何较复杂的提示词，使用带引号的 here-doc，通过 --prompt-file - 传入（参见“传递提示词”）；提交后核对 Prompt sent (N chars) 回显。
• 记录任务 ID；对于运行时间较长的任务，跨轮次重新调用 query_task 以跟踪进度。
• 完整保留签名视频 URL——其中包含 X-Amz-* 参数，截断后会导致 URL 失效。
• Agent 应优先使用默认的 JSON 输出。