數字人影片生成

這個技能做什麼

輸入三樣東西——一份文案、一張形象照、一段聲音樣本——產出一條本人出鏡的直式口播影片：克隆本人的聲音唸文案，用 Seedance 2.0-mini 讓照片中的人物按音訊對嘴型，配 Suno 產生的 BGM，燒錄含關鍵字高亮與卡拉OK 推進的豐富樣式字幕，最後 ffmpeg 合成。全程只呼叫文件化的公開 API，任何能跑 Python 和 ffmpeg 的智慧體都能按本技能執行，不依賴特定客戶端。

整條管線的每個參數、每個陷阱都在真實專案中驗證過（見 references/），不是紙上方案。

開始前必須向使用者要齊的輸入

文案：存為專案根目錄 script.md，每句一行，格式為「1. 台詞」「2. 台詞」。句子是分段產生的單位，一句太長（超過 15 秒）就拆成兩句。
形象照：assets/ 下的照片，直式 9:16 最佳（例如 1152×2048）。照片品質直接決定成品品質：正臉、光線勻、不戴墨鏡口罩。使用者沒有合適照片時，用 GPT Image 2 產生（見 references/api-reference.md），並要求使用者確認形象後再進入影片階段。
聲音樣本：assets/ 下 15–30 秒乾淨人聲（無背景音樂、無殘響），用於 Fish Audio 克隆。
兩個 API Key：Fish Audio 和 APIMART 各一個。用環境變數傳入，禁止寫入任何檔案、禁止出現在命令回顯裡。腳本從環境變數讀取，缺 key 時給出提示並退出，不會落盤。

成本與帳號

組成部分	模式	成本（元）	模型來源	備註	邀請連結
人物	GPT image 2	0.1	APIMART API	僅無照片時產生	https://apimart.ai/register?aff=QVui
影片	Seedance 2.0-mini	10	APIMART API	720x1280，按秒計費	https://apimart.ai/register?aff=QVui
BGM	Suno	0.35	APIMART API	純音樂模式，一次兩首
聲音克隆	s2.1-pro-free	0	Fish Audio API	免費層，voice_id 永久復用	https://fish.audio/?aff=X7QT3YAX3N4Q4
字幕	whisperx small	0	本地執行	一次性裝好環境

實測口徑：Seedance 2.0-mini 720p 約 0.039 美元/秒，一條 30 秒影片約 12 元；Fish Audio 克隆需帳號有餘額（0/0 額度會回傳 403），TTS 走免費層不收費；Suno 每首 0.05 美元。一條完整影片的現實成本約 10–13 元。

五階段流程

每個階段有門禁：不滿足就不進入下一階段。狀態存 output/state.json，腳本可斷點續跑。

Stage A 聲音（Fish Audio）

python scripts/avatar_voice.py clone：上傳聲音樣本建私有克隆模型，拿回 voice_id。
python scripts/avatar_voice.py tts：按 script.md 逐句合成 WAV。
python scripts/avatar_voice.py fixwav：修復串流 WAV 檔案頭（Fish 回傳的頭宣告長度大於實際，不修復部分解碼器會截斷音訊）。
python scripts/avatar_voice.py qc：逐句檢查時長、平均音量、削頂。

門禁：全部句子音量不低於 -30dBFS、無削頂。預估時長只是參考，不拿它當硬目標—— 為湊時長做變速是明確禁止的（見鐵律）。使用者試聽確認音色像不像本人，才算過。

Stage B 影片（Seedance 2.0-mini）

python scripts/avatar_video.py upload-image：形象圖傳到 APIMART 拿公開網址。
python scripts/avatar_video.py host-audio：每句 WAV 經 tmpfiles.org 托管，解析出 /dl/ 真實直連（APIMART 沒有音訊上傳端點；直連 60 分鐘過期，傳完立即提交）。
python scripts/avatar_video.py submit：逐句提交，核心參數 generate_audio=False （影片靜音，嘴型由外掛音訊驅動——這是數字人路線的開關）。duration 按音訊時長向上取整，單段費用估算超過 1 美元自動熔斷。
python scripts/avatar_video.py poll + download：輪詢下載。

門禁：抽偵檢查人物不崩、不換臉；嘴部有張合。換了音訊必須重跑本階段——舊影片的嘴型是對著舊音訊驅動的，直接換音軌不等於同步。

Stage C BGM（Suno）

讀文案寫音樂 brief（風格/情緒/BPM/能量曲線/避免項），範式見 references/prompts.md。
python scripts/avatar_bgm.py generate：instrumental 純音樂模式出兩首候選。
python scripts/avatar_bgm.py mix：裁剪、淡入淡出、壓到人聲下約 -16dB、 sidechaincompress 側鏈閃避，混進成片。
使用者試聽選一首。音樂審美是主觀的，自動化到「出合格候選」為止，選曲留給人。

Stage D 字幕（ASS 豐富樣式，本地零成本）

不依賴任何線上服務，用 ASS/libass 實現一套接近專業剪輯軟體的字幕效果。avatar_caption.py 的六種能力（每一項都逐偵抽像素驗證過，不是紙上說明）：

能力	怎麼配	說明
Cue 分組	script.md 台詞裡寫 `
關鍵字高亮	`spec.keywords`	例如 `AI`→青色、`5000人`→金色，跨中西文的詞整體命中
卡拉OK 逐字推進	`spec.karaoke.enabled`	讀到哪個字亮到哪個字，讀過的不回退
Dual Text	`spec.dual_text`	說「十塊」畫面顯示「10塊」，口語與書面分離
時間窗換樣式	`spec.emphasis`	指定 3–6 秒用更大字型/別的顏色，做重點句
中英雙軌 + 排版動效	`spec.points`	中文主軌 + 英文要點軌，帶 `\fad` 淡入、`\t` 縮放彈出

python scripts/avatar_caption.py spec    # 寫出 output/caption-spec.json 模板
python scripts/avatar_caption.py all     # 產生 ASS + 燒錄成 digital-human-captioned.mp4

字幕文案來源優先級：--srt 指定 > whisperx 的 output/digital-human.srt > voice/qc.json 時長 + script.md 原文。有台詞原文時優先使用原文（加 --prefer-script），它比 ASR 轉寫準，且不需要安裝 whisperx。

兩個必須知道的 libass 約定（都踩過坑，見 references/pitfalls.md）：卡拉OK 的未讀色是 SecondaryColour、讀過切 PrimaryColour 並保持；\k 的單位是釐秒且總和必須等於該條 Cue 的時長，寫成百分比會讓卡拉OK 在一秒內跑完。

使用者用剪映等工具配字幕時，本階段可跳過，但要在交付說明裡講清楚。

Stage E 合成與品檢

四段影片按音訊時長 trim 對齊，縮放 1080×1920，30fps，音軌用 Stage A 的 TTS （影片自帶音軌丟棄），ffmpeg 合成。合成命令模板在 references/prompts.md。品檢：總時長與各段之和一致、波形與人聲零偏移、無削頂、完整解碼。

鐵律（每條都用真實教訓換來的）

禁止用 atempo 等後處理拉伸音訊湊時長。拉伸會讓語速驟降、聽感拖沓。要調整語速，用 Fish TTS 原生的 prosody.speed 參數重錄（例如 s3=0.85、s4=0.9），或接受自然時長。
API Key 只進行程記憶體。環境變數傳入，腳本 atexit 清除，輸出裡出現 key 形態的字串一律替換為佔位符。專案檔案、報告、日誌裡不得出現 key。
同一操作標籤連續失敗兩次即停止，寫報告說明原因，不無限重試。HTTP 401 立即停止（key 問題）。單段影片費用估算超過 1 美元熔斷。
預估時長是參考不是指標。給執行者的 QC 標準不能是「湊數型」的。
使用者聽感優先於自動統計。時長、音量、削頂全過，不代表聽感沒問題；使用者說第 10 秒起不對勁，那就是有問題，從那個時間點倒查。
未通過人工驗收的不能叫成品。交付時明確列出哪些項已驗、哪些沒驗。

環境陷阱速查

Windows 上跑本管線有四個已證實的坑，動手前讀 references/pitfalls.md： Python 請求必須 trust_env=False 否則連錯代理、沙箱與真實檔案系統是兩套檢視、tmpfiles 直連要解析檢視頁、Fish 串流 WAV 頭要修。每個坑裡有根因和修法。

腳本使用

export APIMART_API_KEY=... FISH_API_KEY=...   # 或讓腳本提示時輸入
python scripts/avatar_voice.py all     # Stage A 全流程
python scripts/avatar_video.py all     # Stage B 全流程
python scripts/avatar_bgm.py all       # Stage C
python scripts/avatar_caption.py all   # Stage D（不需要 key）

腳本	階段	是否需要 key	作用
avatar_voice.py	A	Fish Audio	聲音克隆、逐句 TTS、修 WAV 頭、品檢
avatar_video.py	B	APIMART	傳圖、托管音訊、提交嘴型影片、輪詢下載
avatar_bgm.py	C	APIMART（generate 要，mix 不要）	Suno 出 BGM 候選、側鏈閃避混音
avatar_caption.py	D	否	豐富樣式字幕產生與燒錄
avatar_compose.py	E	否	拼接、縮放、轉寫、終檢

腳本從目前目錄讀 script.md 和 assets/，產出到 output/，狀態存 output/state.json，中斷後重跑同一命令即續跑。每個腳本支援 --help 查看子命令。

安全邊界（分發給他人的承諾）

腳本只連接四個文件化端點：api.fish.audio、api.apimart.ai、tmpfiles.org，以及本地 ffmpeg/whisperx。沒有任何遙測、自動更新、匿名統計。
不讀寫專案目錄之外的任何路徑。
API Key 只在行程記憶體，退出即清除；所有落盤文字經過 key 形態過濾。
整包可全文審計：SKILL.md 加 references/ 加 scripts/，無二進位、無可執行安裝步驟。

数字人视频生成