MoneyPrinterTurbo 教學手冊

對應版本：v1.2.8（2026-05-28） 適用場景：團隊要評估「能不能用它替代自家短視頻 pipeline」/「能不能 fork 拆出 LLM + TTS + 自動剪輯三個 module 重用」

1. 專案定位

MoneyPrinterTurbo 是純 Python 寫的 AI 短視頻自動化生成平台。輸入一句主題詞，輸出一支 9:16 或 16:9 的高清成片（含 LLM 腳本、AI 配音、AI 字幕、線上素材、背景音樂）。

1.1 為什麼這個專案值得看

• 66K stars / 9.5K forks：是 GitHub 上短視頻 AI 自動化最受歡迎的開源實作之一
• 完整 MVC 架構：FastAPI 後端 + Streamlit Web UI + 清楚的 services / controllers / models / utils 分層
• 多 LLM provider 支援：OpenAI / Azure / Moonshot / Qwen / Gemini / DeepSeek / Ollama / Pollinations / ModelScope / Grok（v1.2.8 新增）
• 多 TTS provider 支援：Edge-TTS（免費）、Azure、Gemini、SiliconFlow、本地 TTS
• v1.2.8 起的工程升級：套件管理改用 uv + uv.lock，鎖住跨機器版本漂移問題；Colab 也改用 uv 隔離依賴

1.2 不適合的場景

• 要做長視頻（>5 min）：moviepy 2.x 在長片段轉場效率不高
• 要做嚴格版權內容：素材源是 Pexels / Pixabay 雖然免版稅，但 LLM 生成腳本本身仍有風險
• 要做完全離線：除非全部換成 Ollama + 本地 whisper + 本地素材，預設仍依賴雲端 API

2. 安裝指南

2.1 三條路徑

2.2 推薦流程（macOS / Linux + uv）

 1# 1. 安裝 uv（若未裝）
 2curl -LsSf https://astral.sh/uv/install.sh | sh
 3
 4# 2. clone
 5git clone https://github.com/harry0703/MoneyPrinterTurbo.git
 6cd MoneyPrinterTurbo
 7
 8# 3. 安裝依賴（從 uv.lock 鎖定版本）
 9uv sync --frozen
10
11# 4. 設定 config.toml（從 example 複製）
12cp config.example.toml config.toml
13# 編輯 config.toml，填入 LLM provider + API key
14
15# 5. 啟動 webui（會自動開瀏覽器）
16bash webui.sh
17# 或啟動 API
18uv run python main.py

2.3 Docker 流程

1git clone https://github.com/harry0703/MoneyPrinterTurbo.git
2cd MoneyPrinterTurbo
3cp config.example.toml config.toml
4# 編輯 config.toml
5docker-compose up -d
6# 開啟 http://localhost:8501

GPU 版本：docker-compose -f docker-compose.gpu.yml up -d

2.4 系統需求

GPU 只有在用 faster-whisper 本地轉錄 / 批次大量生成時才會顯著加速。

3. 核心架構解析

3.1 整體架構圖

flowchart TD
    UI[Streamlit WebUI
webui/Main.py]
    API[FastAPI
main.py + app/asgi.py]
    Router[app/router.py
v1 routes]
    CtrlV[controllers/v1/video.py]
    CtrlL[controllers/v1/llm.py]
    Task[services/task.py
orchestrator]
    LLM[services/llm.py
13+ providers]
    Voice[services/voice.py
Edge/Azure/Gemini TTS]
    Mat[services/material.py
Pexels/Pixabay]
    Sub[services/subtitle.py
faster-whisper]
    Vid[services/video.py
moviepy 合成]
    State[services/state.py
Redis or memory]
    FS[utils/file_security.py
path validation]

    UI -->|HTTP| API
    API --> Router
    Router --> CtrlV
    Router --> CtrlL
    CtrlV --> Task
    CtrlL --> LLM
    Task --> LLM
    Task --> Mat
    Task --> Voice
    Task --> Sub
    Task --> Vid
    Task --> State
    CtrlV --> FS

3.2 資料流（一支影片從輸入到輸出）

flowchart LR
    A[主題詞
topic] --> B[LLM 生成腳本
llm.generate_script]
    B --> C[LLM 抓關鍵字
llm.generate_terms]
    C --> D[Pexels/Pixabay
material.search_videos]
    B --> E[TTS 合成配音
voice.tts]
    E --> F[whisper 對齊字幕
subtitle.create]
    D --> G[moviepy 合成
video.generate_video]
    E --> G
    F --> G
    G --> H[MP4 成片
storage/tasks/]

3.3 關鍵模組

3.4 設定檔（config.toml）

從 config.example.toml（305 行）複製，主要區段：

• [app] — provider 選擇、API key 路由、enable_g4f（預設 false）
• [whisper] — 模型大小、device、language
• [azure] / [siliconflow] — TTS 進階設定
• [ui] — Streamlit 主題、語言

API key 走 config.toml，也支援 list 形式 round-robin（如 pexels_api_keys = ["k1", "k2"]）。

4. Helper Scripts 詳細用法

4.1 啟動腳本

4.2 Docker 編排

4.3 Colab notebook

docs/MoneyPrinterTurbo.ipynb — 直接在 Google Colab 跑（v1.2.8 起 Colab 也用 uv 隔離）。

5. 應用場景

5.1 內容創作工作流整合

• 批次生產：腳本生成 + 素材抓取 + 配音 + 字幕 + 合成是分離的 services，可以拆出來嵌入自家 pipeline
• 新聞短播：把熱門新聞做成 30 秒短視頻每日推送
• 電商短廣告：主題詞 = 商品 description，自動生成導流短片

5.2 教學 / 內訓

• 上課內容轉成 9:16 短片，配 AI 配音 + 自動字幕
• 將內部 SOP 文件轉成短視頻訓練教材

5.3 二次開發切入點

6. 資安掃描報告

6.1 總體評級：🟡 中等風險（已大幅改善）

維護者在 v1.2.8 對 #881 / #882 / #883 三個資安 issue 都已回應修補，目前剩餘風險屬可控等級。

6.2 紅黃綠燈分級

🟢 低風險（已正確處理）

• ✅ 路徑越界：app/utils/file_security.py 用 os.path.realpath + os.path.commonpath 守 base_dir，符合最佳實踐
• ✅ API auth 機制：app/controllers/base.py 有完整 verify_token（讀 x-api-key header，與 config.app.api_key 對比）
• ✅ g4f supply chain：v1.2.8 起改為 optional dep（uv sync --extra g4f）+ 預設 enable_g4f = false + runtime 警告
• ✅ eval 使用範圍：只在 state.py 用 ast.literal_eval 解析 Redis byte string，非危險的 eval()
• ✅ SSL verify：grep 全 codebase 未發現 verify=False，#881 已修

🟡 中等風險（建議二次審查）

• ⚠️ API auth 預設未掛：controllers/v1/video.py:37 和 llm.py:14 的 verify_token dependency 仍是註解狀態

  1# router = new_router(dependencies=[Depends(base.verify_token)])
  

  → 若要對外暴露 API（非 localhost），務必取消註解
• ⚠️ CORS allow_origins=["*"]：app/asgi.py 預設 wildcard origin，雖然有 CORS_ALLOWED_ORIGINS env 可覆蓋，內網部署也應收緊
• ⚠️ voice.py 巨型檔案（2066 行）+ silent exception swallow（#884）：難以審計，建議拆模組
• ⚠️ API key 存 config.toml：明文存放，需確保 config.toml 不被 git commit（.gitignore 已有）；正式部署建議改 env var 或 vault
• ⚠️ Docker 用 chmod 777：Dockerfile 第 8 行 chmod 777 /MoneyPrinterTurbo 過寬，雖然容器內隔離影響有限，但與最小權限原則不符

🔴 高風險（無）

本次掃描未發現高風險 — 沒有 os.system / shell=True / pickle.loads / yaml.unsafe_load / hardcoded secret 等高危用法。

6.3 部署建議

1. 公網暴露前：取消註解 verify_token dependency；收緊 CORS
2. 生產環境：API key 改用環境變數（os.environ.get）而非 config.toml
3. g4f：除非有強烈理由，不要打開 enable_g4f
4. 依賴掃描：v1.2.8 用 uv.lock 鎖版本，定期 uv pip audit 檢查 CVE
5. 網路出口控管：本服務會打 OpenAI / Pexels / Edge-TTS 等多個外網 API；生產環境建議白名單

7. FAQ

Q1：免費跑得起來嗎？ A：可以。LLM 用 Ollama 本地、TTS 用 Edge-TTS（免費）、素材用 Pexels（免費 API key），全部 0 元成本。

Q2：生成一支 60 秒影片要多久？ A：CPU only：3–8 分鐘；GPU：1–3 分鐘。瓶頸通常在 moviepy 合成階段。

Q3：可以商業使用嗎？ A：本程式 MIT 授權可商用。但生成的影片內容（LLM 腳本 / Pexels 素材）需各自確認版權條件，特別是 Pexels 對直接商業二次散布有限制。

Q4：v1.2.8 跟舊版差在哪？ A：（1）加 Grok provider；（2）套件管理收斂到 uv；（3）Colab 用 uv 隔離；（4）TTS / video 測試補洞；（5）字幕處理保留千分位逗號。

Q5：要怎麼擴 LLM provider？ A：在 app/services/llm.py 的 _generate_response() 加一個 elif llm_provider == "xxx" 分支，模仿 Grok 即可。

8. 進階技巧

8.1 多 API key round-robin

1[app]
2pexels_api_keys = ["key1", "key2", "key3"]

material.get_api_key() 會自動循環使用，繞過單 key 速率限制。

8.2 自定背景音樂

把 mp3 放進 resource/songs/，UI 即可選擇。也支援指定路徑或留空隨機選。

8.3 改字幕字型

resource/fonts/ 預設有多套 CJK 字型，自加 ttf 即可選用。

8.4 用 LiteLLM 統一代理

requirements.txt 已含 litellm==1.60.0，可在 config 走 llm_provider = "openai" + 自架 LiteLLM proxy，統一 13+ LLM 後端。

8.5 Redis 多 worker 部署

services/state.py 支援 Redis backend，正式部署時改用 Redis 可橫向擴 worker。

9. 整合進其他工作流

9.1 與本 AI-Knowledge Template 結合

9.2 作為 micro-service 嵌入自家系統

把 app/services/ 全部抽出來當函式庫呼叫；前端走自家 React / Next.js → 直接 POST /v1/video/scripts + /v1/video/terms API，不用 Streamlit UI。

9.3 用 docker-compose 編排到 K8s

docker-compose.yml 可轉成 kompose convert -f docker-compose.yml 變成 K8s manifest，加 Redis sidecar 即可橫向擴展。

10. 重點摘要 Checklist

• v1.2.8 是寫作日（2026-05-29）最新版本，工程品質明顯比早期高
• 推薦 uv sync --frozen 安裝路徑（最一致）
• 公網部署前必開 verify_token + 收緊 CORS
• g4f 預設關閉，不要主動打開
• config.toml 不要 commit；正式部署改用環境變數
• 二次開發切入點：services/llm.py 加 provider 最簡單
• 整體資安評級 🟡 中等（無 🔴），已修補早期主要漏洞
• 適合做短視頻自動化 POC、教材生產、批次內容創作

11. 進一步閱讀

• README（en）：https://github.com/harry0703/MoneyPrinterTurbo/blob/main/README-en.md
• v1.2.8 release：https://github.com/harry0703/MoneyPrinterTurbo/releases/tag/v1.2.8
• Refactor 議題 #884：https://github.com/harry0703/MoneyPrinterTurbo/issues/884
• Colab notebook：docs/MoneyPrinterTurbo.ipynb
• 三個資安 issue：#881 / #882 / #883（均 closed，修補記錄可佐參）
• LiteLLM（統一 LLM 代理）：https://github.com/BerriAI/litellm
• moviepy（剪輯核心）：https://github.com/Zulko/moviepy
• faster-whisper（字幕引擎）：https://github.com/SYSTRAN/faster-whisper