Kaloclip AI 视频创作工具（命令行 clip）
Kaloclip 能把产品信息与图片转成短视频脚本，再把脚本转成成片视频。账户即拥有 API 密钥的账户：其积分、Kaloclip 会员等级（视频队列大小、免费版水印）、图片素材与任务都归属该账户。多数命令免费；[credits] 类命令会提交付费任务，使用前请先阅读“积分消耗”部分。
运行方式
该 CLI 内置在本技能中（scripts/clip.py，仅依赖 Python 3.11+ 标准库，无需安装）：
python3 <本技能目录>/scripts/clip.py options
下文所有示例中的 clip 均指代 python3 <本技能目录>/scripts/clip.py。
输出默认是 TOON（面向 token）格式，写到 stdout；任意命令加 --json 可输出原始 JSON。错误以结构化形式写到 stdout，并附带可操作的 help: 行。退出码：0 成功，1 错误，2 用法错误。
初始化——首次调用前务必检查
每条命令都需要 KaloData OpenAPI 密钥（通过 secret-key 请求头发送）。它与 kalodata 技能的 kalo CLI 使用同一密钥，存放位置相同。会话首次调用前先运行 clip config 查看 api_key；若显示 missing，请停止，不要猜测密钥，也不要重试。引导用户完成以下步骤并等待：
获取密钥——登录 https://www.kalodata.com/open-center/account 并点击 generate key。还没有账户？先到 https://www.kalodata.com/open-center/home 注册。
保存密钥——clip config set --key <API_KEY>（存储在 ~/.config/kalodata/config.toml，权限 0600，与 kalo 共享），或设置环境变量 KALODATA_API_KEY。
积分——与 KaloData 同一积分余额；适用 Kaloclip 的价格与会员规则。clip credit 显示余额。
调用 积分
options、credit、product resolve、image upload/import、video preview、任意 get / job 免费
script create 2
video create 以 video preview 显示的模型/时长/分辨率为准（例如 sd2 · 15s · 720P = 28）
analysis create 按 Kaloclip 的脚本分析定价
命令
command 作用
clip options 当前可用的模型、时长、分辨率；哪个模型允许哪些时长
clip credit 剩余积分
clip product resolve <link> 商品链接 → 标题、类目、卖点、图片素材
clip image upload <file...> 1–6 张本地图片（JPEG/PNG/GIF/WebP，≤5MB）→ 素材 id
clip image import <url...> 1–6 个公开 https 图片 URL → 素材 id
clip script create [credits] 起草脚本；--product-link，或 --image --title --category
clip script get <job_id> 草稿状态与脚本文本；--wait
clip script candidates <job_id> 在 Kaloclip 网站发起的改写任务的两个候选版本
clip video preview 预估一个视频将消耗的积分；--model --duration --resolution --ratio
clip video create [credits] 最终脚本 → 视频；--script-job / --script-file / --script
clip video get <job_id> 视频状态；完成时给出 videoUrl；--wait
clip analysis create <video_url> [credits] 对现有视频做逐镜头拆解；--commerce --country
clip analysis get <job_id> 分析状态与结果（保留 30 天）；--wait
clip job <job_id> 任意任务的状态与输出；--wait
clip config 显示/设置密钥（与 kalo 共享）与 endpoint（--base-url staging）
视频流程
clip options —— 从输出中同时选定 --model 与 --duration。模型及其支持的时长会变化，切勿凭记忆使用模型。
商品素材，二选一：
clip product resolve <link> 查看链接产出，然后把同一个 --product-link 传给 script create；或
使用用户自己的图片：clip image upload a.png b.jpg → --image ASSET_ID=IMAGE_URL（可重复，1–6 个），再加上 --title 与 --category。
询问视频想要的调性（语气、场景、钩子），作为 --description 传入。
clip script create --product-link <link> --model <M> --duration <S> --description "..." → 这是一次试运行。展示给用户，获得同意后，用 --yes --idempotency-key <提示中的 key> --wait 重新运行（草稿约需 30–60 秒；积分在提交时扣除）。
展示脚本。若要修改，把编辑后的文本写入文件并用 --script-file。
clip video create --script-job <job_id> [--script-file edited.txt] [--resolution 1080P] → 一次试运行，包含积分成本。获得同意后，用 --yes --idempotency-key <key> 重新运行。
clip video get <job_id> --wait —— 15 秒视频约需 15 分钟（--wait 最多轮询 20 次）。告知用户任务正在运行；若 --wait 超时，再次轮询——切勿重新提交。把 videoUrl（mp4）与 coverImageUrl 交给用户。
若草稿是在本机创建的，--script-job 会复用该草稿提交时的图片、标题、模型与时长；否则需再次传入（--product-link 可覆盖大部分）。
积分消耗
[credits] 类命令首次运行不会真正执行：不带 --yes 时，它会打印确切的请求（dry_run:）、积分成本与幂等键，不发送任何内容。展示给用户，获得明确同意后，再用 --yes --idempotency-key <key> 重新运行。切勿自行添加 --yes，也切勿循环提交。
重试：若某次提交以“outcome is unknown”（超时 / 5xx / SUBMISSION_IN_PROGRESS）结束，请在 5 分钟内用相同的 --idempotency-key 重新运行完全相同的命令——Kaloclip 会返回原任务而不会再次计费。新 key 意味着新的付费任务。SUBMISSION_OUTCOME_UNKNOWN：停止并告知用户；不要重新提交。
任务为异步：保留 job id；用 --wait 轮询（每 5 秒一次）。切勿重新提交处于 queued 或 processing 的任务。
TASK_QUEUE_FULL：该会员的视频队列已满（免费版一次只能一个视频）。未扣费；等正在运行的视频结束后再提交。
RATE_LIMIT_EXCEEDED：按用户限速（上传/导入 10 次/分，product resolve 10 次/分，preview 20 次/分，视频 5 次/分）——至少等待 60 秒。
脚本分析
clip analysis create <tiktok|kalodata|youtube-shorts url> 把视频拆成场景（video_scripts[]：时间、景别、画面描述、配音，各附翻译），外加出镜者性别、口语语言、运镜以及它为何有效。可购物的 TikTok 视频：加 --commerce --country US。结果可读 30 天（clip analysis get <job_id>）；加 --json 可看到所有字段。可用它在起草自己的脚本前学习爆款视频。
正确解读数据
已完成草稿的脚本是长篇指导（出镜者、风格、场景、逐场景的 VISUAL / AUDIO / TALENT ACTION）。请完整展示，不要在用户批准前用摘要替代它。
video preview 是估算；提交仍可能被拒（队列、会员、输入）。
videoUrl 是成品文件；免费会员的视频带水印。
product resolve 返回的 selling_points 可能为空，因为 Kaloclip 仍在分析商品——过一分钟重试，或直接不带卖点继续。
图片素材归属账户；一个密钥下的 asset id 不能用于另一个密钥。