AI 產品影片
核心分工：
- 3D 或產品照片：決定東西在哪、多大、怎麼動、什麼時候變。
- 圖像模型：負責讓畫面看起來像真的。
- 影片模型：負責讓畫面動起來。
- 程式碼：拿產品事實和 3D 當尺子，量 AI 的每一張圖和每一段影片，量不過就不花錢。
剪輯、字幕、引線標註和聲音都是數據驅動的疊加層，改一個字不用重新生成畫面。
這套方法來自一個真實專案：一支智能硬體產品的投資人演示片，路線改了四次才跑通，匿名復盤見 examples/case-study.md。下面寫的是跑通之後的通用版本，適用於講解片，也適用於廣告。
為什麼不能照搬 AI 漫劇流水線
AI 漫劇的流程是：設定 → 分鏡 → 資產庫 → 鎖定靜幀 → 影片模型讓畫面動起來 → 配音剪輯。它沒有 3D 模型，觀眾也能容忍細節走樣，所以 AI 畫出的圖就是標準答案。
產品影片賣的是"這個東西長這樣、能這樣用"。接口方向、字樣、燈光位置畫錯，片子就在說假話。所以：
- 照搬骨架：資產先行、先靜後動、按鏡頭選模式、提示詞只寫變化、低清試錯、逐鏡質檢。
- 只改一處：標準答案不是 AI 圖，而是產品事實 + 3D（或產品實拍/CAD 圖）。
還有一條經驗：3D 渲染的像素不要直接進成片，無論多精細都會有 CG 味。讓圖像模型在 3D 底圖上重畫一遍，再用這張圖當影片的首幀和尾幀，真實感才出得來。
第一步：立項，先問清這 8 件事
細節和給用戶的問法見 references/01-intake.md。
- 時間預估：第一條回覆就說清大約多少分鐘或幾天、幾點完成，按階段列出，包括用戶要親自做的步驟；延誤時立刻更新。
- 片型與投放位置：講解片、品牌廣告、豎版短影片、電商影片還是發佈會短片，在哪裡播放，時長和畫幅各是多少。按
references/02-formats.md選打法；一次製作可以出多個交付版本。 - 觀眾是內部還是公開：內部與投資人可以看爆炸圖、透視圖、內部結構；公開發布的版本不放任何內部結構，也不寫元件名稱。這決定了能拍哪些鏡頭。
- 產品事實確認單（
templates/product_facts.md）：每個功能靠什麼部件、從哪裡出來、鏡頭裡長什麼樣、不能長什麼樣，是設計目標還是已經實現，能不能公開。你推斷的條目一律標"待確認"，等負責人確認。 - 質量標杆：請用戶給一部參考片，測量它的運動量和製作方式，只學畫質，不學結構。
- 用戶手上的工具：
- 圖像模型：只有訂閱、需要用戶手動畫，還是有 API 可以由腳本調用？
- 影片模型：API 帳號（腳本能調），還是網頁或 App 會員（只能手動生成：用手動影片包，先查商用條款，不假設能草稿升級）？
- 有沒有產品 3D 模型或 CAD；沒有時，有沒有實物樣品或任何渲染圖。沒有 3D 就走"無 3D 路線"（
references/03-previs.md第 10 節）。
- 預算與計費：計價公式、套餐和代金券實際能抵多少、帳戶餘額、總上限。大批量生成和高清升級之前，必須先請用戶看一眼餘額。
- 小測再定路線：同一個鏡頭出兩條低清草稿，一條用 3D 或產品圖當首幀，一條用圖像模型畫的寫實關鍵幀當首幀，幾塊錢、幾分鐘就能看出差別。
專案資料夾約定
所有腳本都以 --project 指定的資料夾為根（預設是目前目錄），新專案請按這個結構建：
<project>/
.env 金鑰（ARK_API_KEY 等），不進版本庫，不在聊天裡出現
brief/ creative_brief.md、product_facts.md、benchmark.md、budget.md、decisions.md、feedback_brief.md、claims.md、licenses.md
shots/shot_list.json 鏡頭表，時間軸的唯一來源
shots/prompts/<id>.txt 每個鏡頭的影片提示詞（改動時加版本號，舊版保留）
plates/<id>/ 3D 底圖、遮罩、相機座標（無 3D 時放產品參考圖）
packs/ look_bible.txt（統一設定，唯一來源）、手動出圖包、手動影片包
keyframes/keyframes.json 關鍵幀清單（母版、首尾幀、上傳順序）
keyframes/raw/ 圖像模型的原圖
keyframes/norm/ 統一到輸出尺寸後的關鍵幀
footage/ 實拍、錄屏、真實介面截圖等不是生成的素材（可選）
gen/ 影片模型的輸出，以及 video_log.jsonl（呼叫和花費帳本）
qc/ 逐幀拼圖、Gate K / Gate V 報告
edit/ edl.json、captions.json、callouts.json、approved_drafts.json、approved_bridges.json
renders/ 剪輯器輸出的無聲畫面和 .timeline.json（edit.py 的預設輸出位置）
sound/ 音樂和音效分軌、cue sheet、混音視窗
deliver/ 成片（公開版和內部版分開放）
work/ 專案自己的腳本和工作流（生成 EDL、出圖包、檢查），每步結果寫盤
templates/ 裡的模板複製進對應資料夾：creative_brief.md、product_facts.md、benchmark.md、budget.md、feedback_brief.md、claims.md、licenses.md 進 brief/，decision_list.md 存成 brief/decisions.md；shot_list.json 進 shots/；keyframes.example.json 存成 keyframes/keyframes.json；填好的 prompts/look_bible.md 程式碼區塊存成 packs/look_bible.txt；sfx_cue_sheet.md 進 sound/；edl、captions、callouts、approved_drafts、approved_bridges 五個 *.example.json 去掉 .example 進 edit/。
畫幅寫在數據裡，不靠記命令：
- 影片生成：首尾幀任務的畫幅跟隨首幀（關鍵幀先用
scripts/qc/normalise_keyframes.py --size 1080x1920統一）；參考模式豎版要加--aspect 9:16。 - 剪輯：
edit/edl.json寫"size": [1080, 1920]，之後uv run scripts/edl_editor/edit.py --project <project> --edl edit/edl.json --dry就按豎版排；--res 480出同畫幅的小預覽，--size WxH另出別的畫幅。 - 豎版資訊流：
edit/captions.json的style寫"preset": "feed_safe"，字幕、片尾小字進保守安全框，--dry逐條檢查。
第一天就 git init，並把 .env、gen/、renders/、.cache/ 寫進 .gitignore。每類數據只認一個檔案作為來源：
- 產品外觀：規格檔案或 3D 母版；統一設定：
packs/look_bible.txt； - 時間軸：
shots/shot_list.json； - 字幕：
edit/captions.json； - 剪輯：
edit/edl.json； - 批准的鏡頭：
edit/approved_drafts.json、edit/approved_bridges.json； - 宣稱與授權：
brief/claims.md、brief/licenses.md； - 用戶意見：
brief/feedback_brief.md。
流水線
兩條軌道並行：畫面軌和聲音軌。聲音不要等畫面升完高清才開始，剪輯結構一定下來就動手。
| # | 階段 | 產出 | 用戶把關 | 自動檢查/記錄 | 詳見 |
|---|---|---|---|---|---|
| 1 | 立項與事實 | 創意簡報、產品事實確認單、交付清單 | 確認事實、片型、預算 | — | 01、02 |
| 2 | 創意與鏡頭表 | 結構、節拍、鏡頭表（每鏡：機位、動作、效果、產品狀態、模式、轉場、字幕、音效） | 定結構和措辭方向 | 時長和閱讀時間是否裝得下 | 02、rulebook §1 |
| 3 | 預演與底圖 | 3D 母版、每張關鍵幀的底圖契約、需要時的灰模影片；無 3D 時用產品參考圖 | 看底圖總覽 | 從每個真實機位檢查朝向、線纜、穿模 | 03 |
| 4 | 設定母版 | 產品母版、場景母版、人物設定（資產先行，先於所有鏡頭關鍵幀） | 逐張過檢查點 | — | 04 §2、§3 |
| 5 | 關鍵幀 | 每張一個出圖包，或由腳本調 API；統一尺寸 | 手動畫或審圖 | Gate K（專案腳本）：輪廓、比例、效果狀態、縮放一致、重複檔案 | 04 |
| 6 | 影片草稿 | 480p 草稿 | 開通、付款由用戶自己點；批量前看餘額；看草稿 | 演練與拒發條件（含提示詞檢查）；逐 0.25 秒拼圖；Gate V（專案腳本） | 05 |
| 7 | 審片與帳本 | edit/approved_drafts.json、edit/approved_bridges.json、粗剪 | 給意見，編號寫進 brief | 人工放行綁定檔案指紋 | 05 §13 |
| 8 | 剪輯與字幕 | EDL 預覽：轉場、AI 過渡鏡頭、字幕、引線標註、片頭片尾卡 | 改措辭和順序 | --dry 檢查間隔和閱讀時間；字幕靜幀審閱 | 06 |
| 9 | 高清升級 | 批准鏡頭原樣升 1080p | 順序和字幕定稿後放行；先看餘額 | 時長和中間幀一致性 | 05 §6 |
| S1 | 聲音設計（與 8、9 並行） | 選曲與授權、音效 cue sheet、產品自帶聲音、需要時配旁白 | 選曲（發可播放的檔案）、試聽過渡 | 授權記錄 | 07 |
| S2 | 混音 | 平衡後的成片音軌 | 聽成片 | 按時間窗實測"音效減音樂"的 dB；響度目標 | 07 |
| 10 | 交付 | 母版、30 MB 以內的分享版、各平台畫幅、15/6 秒剪短版 | 定片頭文字、要成片 | 時長、音影片流、響度、關鍵幀畫面 | 08 |
| 11 | 多語言 | 一份文案檔案生成平行的字幕和 EDL | 定文案 | 原版逐像素不變；殘留原語言字元為 0 | 08 |
| 12 | 合規終檢 | brief/claims.md、brief/licenses.md、AI 標識 | 簽字 | 詞表檢查 + 逐句對照產品事實 | 09 |
最重要的 12 條
完整的 139 條見 references/rulebook.md。
- 先寫立項單：片型、觀眾（內部還是公開）、平台、時長、畫幅，再談創意。
- 產品事實先成文、先確認；一處更正就一次改完所有下游（3D、底圖、出圖提示詞、影片提示詞、字幕、標註、brief），再全域搜殘留詞。
- 3D 只定位置，最終像素交給 AI 畫；每個鏡頭都問一句"最終像素從哪來"。
- AI 關鍵幀要當首幀、尾幀來驅動鏡頭，不能只做一堆參考圖裡的一張。
- 餵給影片模型的每個像素都會被照抄：灰模統一灰色並降噪，參考包裡不放機位不同的圖，參考圖本身必須正確。
- 影片提示詞寫成逐秒劇本，數字從 3D 或鏡頭表導出，不手寫；只寫變化，不重複描述外觀。
- 效果按攝影機拍到的樣子寫，並寫清"不是什麼"；常亮的燈寫"亮度恆定"；用量用肉眼可查的標準卡住。
- 花錢分兩級：先過免費檢查、出 480p 草稿；批准後才原樣升高清，升之前先看餘額。
- 逐幀看原片：首尾幀模式會在中間偷偷疊化；獨立審查必須看生成的原片。
- 字幕、標註、聲音都放在剪輯層，由時間線數據生成；改字、調序、升級高清都不用重新生成畫面。
- 合規兩道關：先過詞表（極限詞、功效、醫療、數字），再逐句對照產品事實查"暗示的功能"。AI 標識的預設做法是開頭畫面標一次（至少約 2 秒）、片尾小字說明一次，再加上平台的 AI 聲明；不掛常駐角標，除非平台要求。
- 用戶的每條意見按原話編號寫進 brief，所有 agent 和終審都對照它。長對話會被壓縮，檔案不會。
和用戶協作
- 時間：先給預估；長任務沒有可見輸出時，主動報告當前階段、最後一次活動的時間和新的預計時間。
- 輪到用戶動手時一次交齊：完整的說明檔案、能直接打開或播放的素材，發到手機上（單個檔案 30 MB 以內）。母版告訴用戶放在哪個資料夾。
- 聽清工作方式："先只分析"就只分析；"中間不要停"就一路做到交付；"最後一輪"就跳過中間的試聽。
- 結論先行：用戶問"要推翻重來嗎"，第一句給結論，再講理由，最後列出需要用戶拍板的點。
- 安全：
- 不讀、不顯示、不索要金鑰（只放
.env）； - 不註冊帳號、不輸入密碼或支付資訊；
- 同意協議、付款、開通、充值都停在按鈕前，說清代價，由用戶自己點；
- 下載檔案前先問。
- 不讀、不顯示、不索要金鑰（只放
- 長任務：
- 開跑前請用戶接上電源、把系統睡眠設為"從不"，再申請保持喚醒；
- workflow 和批次處理要能從磁碟續跑；
- 提交和查詢結果分兩步；
- 3D 渲染一次只開一個進程。
細節見 references/10-working-with-user.md。
對外發佈
凡是公開的內容，包括廣告投放、社交平台、公開演講配圖：
- 不放爆炸圖、透視圖、能看到內部結構的鏡頭，不寫內部元件名稱和工作原理；
- 社交平台的圖文裡不點名具體的 AI 產品（寫"圖像大模型""影片模型""3D 軟體"）；
- 不曬花費；
- 踩坑寫成通用的流程問題，不寫個人經歷；
- 加上平台要求的 AI 生成聲明。
詳見 references/09-compliance.md。
工具
所有腳本都用 uv run 執行，依賴寫在各腳本開頭的 PEP 723 區塊裡，ffmpeg 來自 imageio-ffmpeg。
| 腳本 | 用途 |
|---|---|
scripts/edl_editor/edit.py | 按 EDL 出片：卡片、疊化、黑場、光暈、甩鏡、AI 過渡鏡頭、字幕、引線標註、角標；支援 16:9、9:16、1:1；--dry 演練，輸出 timeline.json。用 make_demo.py 可以一鍵生成演示專案 |
scripts/edl_editor/typeset.py | 字幕和卡片排版引擎：中英文層級、標點擠壓、安全區、跨平台字型回退；--specimen 可以檢查本機字型 |
scripts/video_api/seedance.py | 火山方舟 Seedance 客戶端：首尾幀、參考圖等模式，草稿與高清升級，可續跑的查詢，費用估算和帳本，--dry 不聯網、只做檢查（含提示詞檢查）；也可以照著它給別的影片模型寫適配 |
scripts/audio/mix.py | 音樂和音效分軌按時間窗平衡，實測 dB 差，限幅和兩遍響度標準化，再合成進畫面 |
scripts/qc/strip.py | 每 0.25 秒抽一幀拼成長圖，畫運動和亮度曲線，標出硬切、跳變和定格 |
scripts/qc/contact_sheet.py | 帶標籤的圖片網格，用來審閱底圖、關鍵幀和草稿 |
scripts/qc/normalise_keyframes.py | 關鍵幀 raw → norm：鏡頭幀裁成輸出畫幅，母版和參考圖只縮不裁，放大和硬裁切會警告 |
scripts/qc/lint_prompts.py | 影片提示詞的禁用詞族掃描（含本產品的機理禁用詞），沒掃到檔案時報錯 |
不附帶、要專案自己寫進 work/ 的腳本：Gate K 和 Gate V 的判定（seedance.py 不讀 Gate K 報告，"沒有報告不提交"由專案自己的提交步驟保證）、出圖包生成（keyframes.json → packs/）、shot_list.json → EDL 和字幕草稿。要求寫在 04、05、06 和 templates/prompts/keyframe_pack.md。
使用說明見各目錄的 README。模型的能力、價格和限制變化很快，用之前先核對官方文件，各參考檔案末尾的"模型備註"都標了核對日期。
什麼時候讀哪個檔案
| 檔案 | 什麼時候讀 |
|---|---|
references/01-intake.md | 新專案第一天 |
references/02-formats.md | 定片型、時長、畫幅、結構，或者做廣告和豎版短影片時 |
references/03-previs.md | 搭 3D 預演或底圖之前；沒有 3D 模型時 |
references/04-keyframes.md | 寫出圖包、定統一設定、檢查關鍵幀時 |
references/05-video-gen.md | 寫影片提示詞、選生成模式、提交、審草稿、高清升級時 |
references/06-edit-type.md | 剪輯、轉場、字幕、標註、片頭片尾卡 |
references/07-sound.md | 選曲、音效、旁白、混音 |
references/08-delivery.md | 交付、各平台版本、剪短版、多語言 |
references/09-compliance.md | 寫任何上屏文字或旁白之前；公開發佈之前 |
references/10-working-with-user.md | 和不寫代碼的用戶協作、長任務、安全邊界、環境問題 |
references/rulebook.md | 某個階段拿不準時，查對應的那一組 |
references/pitfalls.md | 出問題時，先按現象查 |
templates/ | 開工時複製到專案裡，填寫後使用 |
examples/case-study.md | 想看一個完整專案是怎麼走下來的 |