VoxFlow Video Skill
使用 AI 產生短影音：LLM 撰寫腳本，AI 繪製卡片或場景，TTS 朗讀，FFmpeg / Remotion 渲染最終 MP4。
若要將文章轉為卡片影片（Slice — 13 種主題：paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric），請切換至 voxflow:slice。若要產生可分享的 HTML/CSS 卡片圖片集或有旁白的卡片 MP4 匯出，請切換至 voxflow:card。
五個入口點 — 依使用者需求選擇：
| 指令 | 輸出 | 使用時機 |
|---|---|---|
picstory | 垂直/橫向 MP4，含手繪卡片或電影場景 | "知識卡片影片", 小紅書 / Twitter 教育內容、草圖教學 |
present | 1080×1920 旁白卡片影片，5 種視覺方案 | 提案簡報、解說短片、品牌短影音 |
explain | MP4 解說影片，包含標題 / 要點 / 總結場景 | "什麼是 X?" 教學、課程介紹 |
slides | 自含式 HTML 簡報，內嵌 TTS 音訊 | 產品發表、演講、以連結分享 |
image | 單張 PNG | 一次性插圖 / 縮圖（Hunyuan TextToImage） |
前置需求
npm install -g voxflow並執行voxflow login- 安裝
ffmpeg（brew install ffmpeg/sudo apt install ffmpeg）— 用於 MP4 渲染 - 對於
present/explain（基於 Remotion）：本機外掛安裝會包含remotion-cards/。若present顯示「Remotion not ready」，請在 bundled 的remotion-cards/目錄內執行npm install。對於explain，可使用--cloud跳過本機 Remotion。
🎴 picstory — 知識卡片影片
LLM 撰寫結構化腳本，AI 為每個場景繪製一張卡片，TTS 朗讀，FFmpeg 組合。最適合 小紅書 / Twitter 教育內容 / TikTok。
快速開始
# 預設：中文、草圖風格、直向、5 個場景
voxflow picstory --topic "AI Agent 入門指南"
# 2 場景快速測試（不渲染完整影片）
voxflow picstory --topic "AI 入門" --scenes 2 --image-only
# 英文橫向影片
voxflow picstory --topic "How React Hooks Work" --language en --ratio landscape --style photo
輸出：picstory-<時間戳>.mp4 + .json（腳本）。
卡片類型風格（結構化標題 + 關鍵要點）
--style | 外觀 | 最佳適用 |
|---|---|---|
sketchnote (預設) | 多彩手繪子彈筆記 | 知識分享、教學 |
neon_noir | 賽博龐克暗色霓虹 | 科技、新創 |
minimal_3d | 柔和 3D 黏土風漸層 | 小紅書生活風格 |
chalkboard | 深綠底白粉筆 | 科學、學術 |
場景類型風格（自由形式插圖）
--style | 外觀 | 最佳適用 |
|---|---|---|
photo | 電影感 / 寫實 | 故事敘述、旅遊 |
manga_panel | 日式漫畫墨線 | 戲劇、步驟式指南 |
vintage_newspaper | 1940 年代報紙 | 歷史、事實故事 |
比例
--ratio | 像素 | 平台 |
|---|---|---|
portrait (預設) | 1080×1920 | 小紅書, TikTok, Reels, 抖音 |
landscape | 1920×1080 | YouTube, B站 |
square | 1080×1080 | Instagram, Twitter |
腳本模型預設（--script-model）
| 預設值 | 提供者 | 優勢 |
|---|---|---|
| 省略 | 伺服器設定 | 平衡預設（gpt-4o-mini） |
gemini-flash | OpenRouter | 多語言、中文優異 |
deepseek | DeepSeek | 最便宜、中文極佳 |
hunyuan | 騰訊混元 | 原生中文 |
moonshot | Moonshot | 中文長上下文 |
伺服器強制實施允許清單 — 僅上述預設名稱有效；任意模型 ID 將被拒絕。
圖片品質（--quality）
圖片生成是唯一有意義的成本（每張約 $0.005-0.08）。LLM 腳本（約 2K token）可忽略不計。
--quality | 提供者 | 優勢 | 5 張圖片成本 |
|---|---|---|---|
fast (預設) | OpenRouter Gemini Flash | 最便宜、平衡 | ~$0.025 |
hd | OpenRouter Gemini Pro | 更高細節 | 中 |
ultra | OpenRouter gpt-5.4-image-2 | 整體最佳、約 16 倍成本 | ~$0.40 |
fast-aiberm | Aiberm Gemini Flash | 便宜的 Aiberm 等級 | 低 |
hd-aiberm | Aiberm Gemini Pro | 最強中文文字渲染 — 最適合包含中文標題的小紅書卡片 | 中 |
迭代時使用 fast；卡片需包含準確中文字元時使用 hd-aiberm；正式輸出使用 ultra。
完整選項
| 旗標 | 預設值 | 說明 |
|---|---|---|
--topic <text> | 必填（或 --text） | 故事主題 |
--text <content> | — | 直接貼入完整文章（而非主題） |
--style <name> | sketchnote | 請參閱上方風格 |
--ratio <name> | portrait | portrait | landscape | square |
--language <code> | zh | zh | en | ja | ko | ... |
--scenes <n> | 5 | 2–10。快速測試請用 2。 |
--script-model <preset> | 伺服器預設 | 請參閱上方預設值 |
--quality <tier> | fast | 請參閱上方表格 |
--voice <id> | 預設 | TTS 語音（來自 voxflow voices） |
--speed <n> | 1.0 | TTS 速度 0.5–2.0 |
--bgm <file> | — | 背景音樂（mp3/wav）混入旁白下方 |
--bgm-volume <n> | 0.1 | BGM 音量 0–1 |
--fade <n> | 0.4 | 每個場景淡入/淡出秒數（設為 0 可停用） |
--image-only | false | 僅儲存圖片+音訊，不進行最終影片渲染 |
--output-dir <dir> | — | 所有輸出的目錄 |
--output <path> | 自動 | 最終 MP4 路徑 |
配額成本
| 操作 | 配額 |
|---|---|
| LLM 腳本 | 100 |
| TTS / 場景 | 50 |
| 圖片 / 場景 | 500 |
| 2 場景測試 | 約 1,200 |
| 5 場景完整 | 約 2,850 |
免費方案（每月 10K）≈ 3 部完整 picstory 影片。
管線
主題 / 文字
├─[1] LLM 腳本 → { title, scenes: [{ heading, keyPoints, narration }] }
├─[2] 每個場景 TTS → PCM 音訊
├─[3] 每個場景圖片（並行）→ JPEG（透過 /api/image/generate）
└─[4] FFmpeg：圖片 + WAV → Ken Burns zoompan MP4 → 合併 → +BGM → final.mp4
疑難排解
| 問題 | 解決方法 |
|---|---|
ffmpeg not found | brew install ffmpeg（Mac）/ sudo apt install ffmpeg |
Image generation failed | 重試；若卡在 hd，降級為 --quality fast |
| 渲染太慢 | Ken Burns 為 CPU 密集型。先使用 --scenes 2 --image-only 驗證內容。 |
model_not_allowed | 使用 --script-model 預設名稱，而非原始模型 ID |
| 卡片中中文文字亂碼 | 切換至 --quality hd-aiberm |
📑 present — 旁白卡片影片（本機 Remotion）
文字或 URL → LLM 卡片 → TTS → Remotion 渲染。1080×1920，5 種視覺方案。
voxflow present --text "Claude Code 是一個 AI 程式設計工具" --style aurora
voxflow present --url https://example.com/article --style noir
voxflow present --text "2025 AI 晶片格局" --web-search --style neon
voxflow present --cards pre-generated.json --no-audio
| 旗標 | 預設值 | 備註 |
|---|---|---|
--text / --url / --cards | 三選一必填 | 輸入來源 |
--style | aurora | noir | neon | editorial | aurora | brutalist |
--voice <id> | v-female-R2s4N9qJ | TTS 語音 |
--speed <n> | 1.0 | 0.5–2.0 |
--no-audio | false | 僅無聲影片 |
--web-search | false | 以最新網路事實增強 LLM |
--output <path> | ./present-<ts>.mp4 | .mp4 或 .wav |
若
present回報「Remotion not ready」，請在 bundled 的remotion-cards/目錄內執行npm install以設定本機渲染器。
🧠 explain — AI 解說影片
標題 / 要點 / 總結場景流程。最適合「什麼是 X？」教學。
voxflow explain --topic "What is React?"
voxflow explain --topic demo --output demo.mp4 # 內建示範（無需 API 呼叫）
voxflow explain --topic "區塊鏈入門" --style chalkboard --voice v-male-Bk7vD3xP
voxflow explain --topic "Machine Learning" --audio-only
voxflow explain --topic "AI Agent 入門" --cloud # 在伺服器上渲染
| 旗標 | 預設值 | 備註 |
|---|---|---|
--topic <text> | 必填 | 使用 demo 取得內建設定腳本 |
--style | modern | modern | playful | corporate | chalkboard |
--language | en | en | zh | ja | ko | ... |
--voice <id> | v-female-R2s4N9qJ | |
--scenes <n> | 5 | 3–12 |
--audio-only | false | 跳過渲染，僅輸出 WAV |
--cloud | false | 使用雲端 Remotion 而非本機 |
--output <path> | ./explain-<ts>.mp4 |
📊 slides — 含 TTS 的 HTML 簡報
產生自含式 HTML 簡報，每張投影片內嵌 base64 音訊。可在任何瀏覽器中開啟，無需伺服器。
voxflow slides "AI in Healthcare"
voxflow slides "Q4 Revenue Report" --template report --theme paper
voxflow slides "React Tutorial" --template tutorial --model balanced
voxflow slides "Startup Pitch" --template pitch --theme ocean --no-audio
| 旗標 | 預設值 | 備註 |
|---|---|---|
--text <text>（或位置參數） | 必填 | 主題 |
--template | free | product | report | tutorial | pitch | free |
--theme | midnight | midnight | paper | ember | forest | ocean |
--model | swift | swift | balanced | pro | creative |
--voice <id> | v-female-R2s4N9qJ | |
--no-audio | false | 跳過 TTS，僅產生投影片 |
--output <path> | ./slides-<ts>.html |
10 種佈局：hero、title-bullets、two-column、three-cards、image-left、image-right、quote、timeline、stats、section。範本會自動選取佈局序列。
🖼 image — 單張 Hunyuan 插圖
同步文字 → 圖片（PNG）。適用於縮圖或一次性插圖。
voxflow image "a sleeping cat in a sunlit window" --resolution 1024:1024 -o cat.png
解析度：768:768、768:1024、1024:768、1024:1024、720:1280、1280:720、768:1280、1280:768、1080:1920、1920:1080。
提示最多 1000 字元。輸出：本機 PNG + COS URL。
選擇正確工具檢查清單
"小紅書風格知識卡片" → picstory
"AI 短影片 + 字幕" → picstory --style sketchnote
"解說 / What is X?" → explain
"品牌短影音（自訂文字）" → present
"已有卡片/腳本" → present --cards
"可分享 HTML 簡報（含音訊）" → slides
"單張插圖" → image
規則
- 搜尋語音：在傳遞
--voice前使用voxflow voices。切勿猜測 ID。 - 檢查配額：在影片呼叫前執行
voxflow status：picstory ≈ 3K，present/explain ≈ 500–2K。 - 優先低成本測試：
picstory --scenes 2 --image-only可在支付完整渲染費用前驗證腳本。 - 渲染完成後，自動播放：
open output.mp4（macOS）。