HiAPI 產品代言人影片 是做什麼的？
使用本地 CLI 建立 3-15 秒的單鏡頭產品影片。付費請求前務必以 --dry-run 進行估算。只有當使用者明確同意生成且指令包含 --spend 時，才建立付費任務。
路由情境
精確選擇一個情境：
| 情境 | 模型 | 必要輸入 | P0 預設值 |
|---|---|---|---|
synthetic-spokesperson | kling-3.0-omni/text-to-video | 提示詞與選用對話 | 3秒，720p，9:16，音訊 |
talking-head | kling-3.0-omni/image-to-video | 一張授權人物圖片、提示詞、對話、同意聲明 | 3秒，720p，音訊 |
product-intro | seedance-2.0-fast | 提示詞與1-9張產品圖片 | 4秒，480p，9:16，音訊 |
brand-promo | seedance-2.0-fast | 提示詞與1-9張品牌或產品圖片 | 4秒，480p，9:16，音訊 |
在建立請求之前，確認目標時長。如果使用者未指定，請詢問影片應為幾秒，並告知支援範圍：Kling 3-15 秒；Seedance 4-15 秒。提供表格中的 P0 預設值，但在使用者選擇時長或明確接受預設值之前，不要進行 --dry-run。
拒絕產生 talking-head，除非使用者確認授權且指令包含 --consent-confirmed。不得虛構產品聲明、背書、價格、認證或品牌事實。
保護費用與機密
先執行零成本檢查：
node scripts/hiapi-product-spokesperson-video.mjs --check --env-file "D:\path\to\.env.local"
然後以 --dry-run 執行意向請求。確認公開定價估算在使用者限制範圍內後，再將 --dry-run 取代為 --spend。預設用戶端估算限制為 $0.50；僅在使用者明確核准的預算範圍內覆寫此值。每次調用最多建立一個付費任務。
將此視為估算保護，而非伺服器強制的最終收費上限。HiAPI 可能在任務預付時套用帳戶特定群組比例。在任務 API 支援伺服器端最大成本欄位之前，請在付費生成前揭露此限制，並在使用者總預算內保留充足的餘裕空間。
從處理程序環境或 --env-file 讀取 HIAPI_API_KEY。切勿在預覽、成品、清單、錯誤或日誌中列印、回傳、持久儲存或包含金鑰。P0 中使用暫存儲存。
安裝後，將 .env.example 複製為被忽略的 .env，或將 --env-file 指向現有被忽略的環境檔案。切勿提交已填入內容的檔案。從預覽和儲存的請求成品中遮蓋嵌入的圖片資料和遠端圖片 URL。
在本機執行
估算授權頭像請求而不花費：
node scripts/hiapi-product-spokesperson-video.mjs `
--scenario talking-head `
--image-file "D:\media\authorized-person.jpg" `
--prompt "固定攝影機，自然的眼神接觸，剋制的動作" `
--dialogue "新產品，現已上市。" `
--consent-confirmed `
--env-file "D:\path\to\.env.local" `
--max-cost-usd 0.50 `
--dry-run
對於 synthetic-spokesperson，省略圖片和同意選項。對於產品和品牌情境，重複 --reference-image-file 或 --reference-image-url。本地 JPEG、PNG 和 WebP 檔案會轉換為 data URI，且每個不得超過 20 MiB。
無需再次花費即可恢復
CLI 在提交前會列印冪等鍵，並在建立後立即列印任務 ID。如果在返回任務 ID 前提交被中斷，請使用相同的 --idempotency-key 重試。如果在建立後輪詢被中斷，僅執行 --task-id ID、--env-file 和所需的 --output-dir。這會恢復輪詢並下載現有結果，而無需重建或重新提交原始請求。
保留輸出套件
除非提供了 --output-dir，否則每次成功執行都會寫入 outputs/ 目錄。保留：
final.mp4；script.md和captions.srt；prompt.json（已遮蓋嵌入媒體和遠端圖片 URL）；manifest.json（包含情境、模型、任務 ID、狀態、估算、請求雜湊、儲存、時間戳記和到期日）；qc.json（標記為人工審查語音、唇形同步、一致性、連續性和聲明準確性）。
如果沒有最終成功的任務和可用的本地影片，切勿聲稱成功。
處理失敗
- 不要重試 HTTP
400、401、402或403。 - 最多使用原始冪等鍵重試提交 HTTP
409、429或503三次。 - 使用
--task-id恢復輪詢中斷；切勿自動提交替代請求。 - 未經明確核准另一次付費執行，請勿在品質失敗後重新生成。
- 回報任務 ID、最終狀態、估算、本地輸出路徑和待處理的人工 QC 檢查。