Kaloclip AI 影片創作（clip）
Kaloclip 將商品資訊與圖片轉換為短影片腳本，並將腳本製作成完成的影片。帳號為擁有 API 金鑰的帳號：其額度、 Kaloclip 會員資格（影片佇列大小，免費版有浮水印）、圖片素材與任務。大部分指令免費。[credits] 指令會提交付費任務 — 使用前請參閱「花費額度」。
執行
命令列工具包含在此技能內（scripts/clip.py，僅需 Python 3.11+ 標準函式庫 — 無需安裝）：
python3 <此技能目錄>/scripts/clip.py 選項
以下所有範例將 clip 視為 python3 <此技能目錄>/scripts/clip.py 的簡寫。
輸出為 TOON（以 token 為導向）至標準輸出；對任何指令加上 --json 可獲得原始 JSON。
錯誤訊息會以結構化方式輸出至標準輸出，並附帶可行的 help: 行。結束碼：0 成功，1 錯誤，2 用法錯誤。
設定 — 在首次呼叫前檢查
每個指令都需要一個 KaloData OpenAPI 金鑰（以 secret-key 標頭傳送）。此金鑰與 kalo 技能（kalodata）的 kalo 命令列工具所使用的金鑰相同，儲存在同一位置。在會話的首次呼叫前，執行 clip config 並查看 api_key。如果顯示 missing，請停止 — 不要猜測金鑰或重試。引導使用者完成以下步驟並等待：
-
取得金鑰 — 登入 https://www.kalodata.com/open-center/account 並點擊「產生金鑰」。還沒有帳號？請先於 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 create2 video createvideo preview根據模型/時長/解析度顯示的額度（例如 sd2 · 15秒 · 720P = 28）analysis createKaloclip 對腳本分析的價格
指令
| 指令 | 說明 |
|---|---|
clip options | 目前可用的模型、時長、解析度；哪些模型支援哪些時長 |
clip credit | 剩餘額度 |
clip product resolve <連結> | 商品連結 → 標題、類別、賣點、圖片素材 |
clip image upload <檔案...> | 1–6 張本地圖片（JPEG/PNG/GIF/WebP，≤5MB）→ 素材 ID |
clip image import <網址...> | 1–6 個公開的 HTTPS 圖片網址 → 素材 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 共用）與端點（--base-url staging） |
影片流程
clip options— 從其輸出中選擇--model和--duration。模型及其時長會變更；切勿憑記憶使用模型。- 商品素材，任選其一：
clip product resolve <連結>檢查連結產生的內容，然後將相同的--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 <連結> --model <M> --duration <S> --description "..."→ 預演。顯示結果，取得同意後，重新執行並加上--yes --idempotency-key <提示中的金鑰> --wait（草稿約需 30–60 秒；額度在提交時扣除）。- 顯示腳本。若要更改，將編輯後的文字寫入檔案並使用
--script-file。 clip video create --script-job <job_id> [--script-file edited.txt] [--resolution 1080P]→ 包含額度成本的預演。取得同意後，重新執行並加上--yes --idempotency-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 <金鑰>。切勿自行添加 --yes，也切勿迴圈提交。
- 重試：如果提交以「結果未知」結束（逾時 / 5xx / SUBMISSION_IN_PROGRESS），請在 5 分鐘內使用相同的
--idempotency-key重新執行完全相同的指令 — Kaloclip 將返回原始任務，不會再次收費。新的金鑰代表一個新的付費任務。SUBMISSION_OUTCOME_UNKNOWN：停止並告知使用者；不要重新提交。 - 任務為非同步：保留任務 ID；使用
--wait輪詢（每 5 秒）。切勿重新提交狀態為queued或processing的任務。 TASK_QUEUE_FULL：會員資格的影片佇列已滿（免費版：一次只能處理一個影片）。尚未收費；等待正在執行的影片完成，然後再次提交。RATE_LIMIT_EXCEEDED：每個使用者的限制（上傳/匯入 10 次/分鐘，商品解析 10 次/分鐘，預覽 20 次/分鐘，影片 5 次/分鐘）— 請至少等待 60 秒。
腳本分析
clip analysis create <tiktok|kalodata|youtube-shorts 網址> 將影片分解為場景（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 仍在分析商品時可能為空 — 一分鐘後重新執行，或在不使用的情況下繼續。- 圖片素材屬於該帳號；一個金鑰的素材 ID 不適用於另一個金鑰。