MoneyPrinterTurbo：从一句话主题到成片短视频的 AI 自动化工作流、部署与 API 实战

MoneyPrinterTurbo 是一个基于 AI 大模型与自动化工作流的短视频生成项目：只需提供一个视频主题或关键词，它就能自动生成视频文案、配音、字幕、匹配无版权素材并合成高清短视频。本文基于仓库 README 主体内容展开，结合 app/ 目录下的实际源码（任务流水线、配置加载、API 路由、请求模型），系统讲解其功能特性、config.toml 配置项、三种部署方式、API 接口的参数细节，以及字幕、语音、背景音乐等配套机制和常见故障排查，帮助你在本机或服务器上真正跑通并调用这套生成链路。

一句话主题驱动的短视频生成流水线

README 中对项目定位的核心描述是：只需提供一个视频主题或关键词，就可以全自动生成视频文案、视频素材、视频字幕、视频背景音乐，然后合成一个高清的短视频。

这条“自动化工作流”在源码中对应 app/services/task.py 里的 start() 主函数（task.py#L210-L329），它按固定顺序执行 6 个阶段，并在每个阶段更新任务状态与进度：

1. 生成文案（script）：调用 llm.generate_script()，根据主题、语言、段落数让大模型产出口播稿；若请求中已自带 video_script，则跳过 LLM 直接使用自定义文案（task.py#L16-L33）。
2. 生成搜索词（terms）：当素材来源不是 local 时，调用 llm.generate_terms() 从主题和文案中提炼 5 个英文搜索词，用于后续在素材网站上检索视频片段（task.py#L36-L58）。
3. 生成音频（audio）：通过 voice.tts() 用 Edge TTS 等引擎合成配音 audio.mp3，并计算音频时长，该时长决定了后续需要下载多少素材。
4. 生成字幕（subtitle）：按 subtitle_provider 配置选择 edge 或 whisper 方案生成 subtitle.srt，whisper 路径还会用 LLM 对字幕做一轮 correct 纠偏。
5. 获取视频素材（materials）：本地模式直接预处理上传素材；在线模式按搜索词从 Pexels/Pixabay 下载片段并缓存。
6. 合成最终视频：先用 video.combine_videos() 把素材片段拼接成 combined-N.mp4，再用 video.generate_video() 叠加配音、字幕、背景音乐输出 final-N.mp4（task.py#L159-L207）。

stop_at 参数（script / terms / audio / subtitle / materials / video）允许流水线在任一阶段提前终止，这也正是 API 层 /subtitle、/audio 等独立接口的底层实现方式——同一个流水线，不同的终止点。

功能特性：README 承诺的功能及其代码落点

README 列出的功能清单与源码结构可以一一对照：

• 完整的 MVC 架构，支持 API 和 Web 界面：FastAPI 后端入口为 main.py，它通过 uvicorn 加载 app/asgi.py 中的应用实例，路由统一在 app/router.py 中挂载 video 与 llm 两个控制器；Web 界面基于 Streamlit，入口为 webui/Main.py。
• 文案 AI 自动生成 / 自定义文案：video_script 字段非空即跳过 LLM（见上文流水线第 1 步）。
• 多种高清视频尺寸：README 标注竖屏 9:16（1080x1920）、横屏 16:9（1920x1080）；从源码结构看，app/models/schema.py 中的 VideoAspect 枚举还定义了 1:1 方形（1080x1080）。
• 批量视频生成：video_count 参数控制一次生成 N 个成片，源码中当 video_count > 1 时强制使用 random 拼接模式，使每条成片素材顺序不同，便于挑选最满意的（task.py#L164-L166）。
• 视频片段时长设置：video_clip_duration（默认 5 秒）控制单个素材片段最长时长，调节素材切换频率。
• 中英文文案：video_language 为空时由大模型按主题语言自动响应；配音引擎对中英文音色均有覆盖。
• 多种语音合成、实时试听：Web 界面提供试听；完整声音列表见 docs/voice-list.txt。
• 字幕样式：font_name、text_fore_color、text_background_color、font_size、stroke_color、stroke_width、subtitle_position（top/bottom/center）及 custom_position 均可在请求中调整（schema.py#L94-L105）。
• 背景音乐：bgm_type（random 或指定文件）、bgm_file、bgm_volume（默认 0.2）。
• 素材来源：Pexels、Pixabay（高清、无版权）或 local 本地素材；对应请求字段 video_source 与 video_materials。
• 多模型接入：OpenAI、Moonshot（月之暗面）、Azure、g4f（gpt4free）、one-api、通义千问（qwen）、Google Gemini、Ollama、DeepSeek、文心一言（ernie）。从源码结构看，app/services/llm.py 的 _generate_response() 分支中还包括 cloudflare 一条接入路径。README 同时建议国内用户优先使用 DeepSeek 或 Moonshot，注册即有可用额度、无需翻墙。

README 还给出了“后期计划”：GPT-SoVITS 配音、更自然的语音合成、视频转场效果、更多素材来源、短/中/长视频长度选项、更多 TTS 服务商（如 OpenAI TTS）、自动上传 YouTube。这些在源码中尚未实现（VideoTransitionMode 已有 none/Shuffle/FadeIn/FadeOut/SlideIn/SlideOut 等枚举定义，转场能力仍在演进中）。

安装部署

配置要求

• 建议最低 CPU 4 核或以上、内存 8G 或以上，显卡非必须；
• Windows 10 或 MacOS 11.0 以上系统；
• 路径尽量不要使用中文、特殊字符或空格，避免不可预料的兼容问题；
• 需要正常网络环境（访问大模型与素材站点时按各自要求配置网络）。

方式一：Windows 一键启动包

README 提供了一键启动包（百度网盘下载），解压后建议先双击执行 update.bat 更新到最新代码，再双击 start.bat 启动；启动后自动打开浏览器（若为空白页建议换 Chrome 或 Edge）。其他系统则推荐 Docker 部署。

方式二：Docker 部署（推荐）

仓库根目录的 docker-compose.yml 定义了 webui 与 api 两个服务，二者共用同一 Dockerfile 构建，并将项目目录挂载到容器内 /MoneyPrinterTurbo：

cd MoneyPrinterTurbo
docker-compose up

注意：新版 Docker 安装时会以插件形式自带 docker compose，启动命令应调整为 docker compose up。

容器端口映射（见 docker-compose.yml）：

服务	端口	启动命令	用途
webui	8501:8501	streamlit run ./webui/Main.py ...	Web 图形界面
api	8080:8080	python3 main.py	FastAPI 后端服务

启动后：

• 访问 Web 界面：http://0.0.0.0:8501；
• 访问 API 文档：http://0.0.0.0:8080/docs（Swagger）或 http://0.0.0.0:8080/redoc。

方式三：手动部署

git clone https://gitcode.com/GitHub_Trending/mo/MoneyPrinterTurbo
cd MoneyPrinterTurbo
conda create -n MoneyPrinterTurbo python=3.11
conda activate MoneyPrinterTurbo
pip install -r requirements.txt

关键依赖可参考 requirements.txt：moviepy（视频合成）、streamlit（Web 界面）、edge_tts（语音合成）、fastapi/uvicorn（API 服务）、faster-whisper（whisper 字幕）、openai、google.generativeai、dashscope、g4f、azure-cognitiveservices-speech、redis 等。

启动前需安装 ImageMagick（用于字幕文字渲染）：

• Windows：下载**静态库（static）**版本安装包，安装时不要修改路径，然后在 config.toml 中把 imagemagick_path 指向实际的 magick.exe；
• MacOS：brew install imagemagick；
• Ubuntu：sudo apt-get install imagemagick；
• CentOS：sudo yum install ImageMagick。

随后在项目根目录下分别启动：

:: Windows
conda activate MoneyPrinterTurbo
webui.bat

# MacOS / Linux
conda activate MoneyPrinterTurbo
sh webui.sh

# 启动 API 服务
python main.py

API 启动后同样在 http://127.0.0.1:8080/docs 或 /redoc 在线调试。

配置文件 config.toml：核心参数逐项说明

配置是理解本项目行为的枢纽。app/config/config.py 中的 load_config() 有一个值得注意的行为：若项目根目录下不存在 config.toml，会自动把 config.example.toml 复制为 config.toml，因此首次启动后直接编辑 config.toml 即可。配置分为 [app]、[whisper]、[proxy]、[azure] 四个段，核心参数如下（完整注释见 config.example.toml）：

素材来源（[app]）

参数	说明
video_source	"pexels" 或 "pixabay"，素材网站二选一
pexels_api_keys	Pexels API Key 列表，支持多个 Key 规避频率限制；注意 Key 用英文双引号、多个 Key 逗号隔开
pixabay_api_keys	Pixabay API Key，格式同上
material_directory	视频素材缓存位置：留空为默认 ./storage/cache_videos；填绝对路径为自定义目录；填 "task" 则素材下载到各任务目录下（不共享缓存）

大模型接入（[app]）

llm_provider 决定调用哪一家模型，支持的取值在 app/services/llm.py 中有完整分支：

取值	需配套配置	默认模型
openai	openai_api_key，可加 openai_base_url（代理/兼容端点）、openai_model_name	gpt-4-turbo
moonshot	moonshot_api_key，moonshot_model_name	moonshot-v1-8k
deepseek	deepseek_api_key，deepseek_model_name	deepseek-chat
qwen	qwen_api_key（走 dashscope SDK）	qwen-max
gemini	gemini_api_key（走 google.generativeai）	gemini-1.0-pro
azure	azure_api_key、azure_base_url、azure_api_version	部署名
oneapi	oneapi_api_key、oneapi_base_url、oneapi_model_name	-
ollama	ollama_base_url（默认 http://localhost:11434/v1）、ollama_model_name	-
g4f	g4f_model_name（免 Key，稳定性较差）	gpt-3.5-turbo
ernie	ernie_api_key + ernie_secret_key（百炼 OAuth 流程）	ernie 4.0

调用链路上，generate_script() 与 generate_terms() 内置了最多 5 次重试（_max_retries = 5），对响应做 Markdown 清洗、段落切分与 JSON 数组校验，这是文案偶发失败时日志中出现多次 “trying again...” 的原因。

字幕、二进制工具与运行时（[app]）

参数	说明
subtitle_provider	"edge"（快、无配置要求）/ "whisper"（慢、质量稳）/ 留空表示不生成字幕
imagemagick_path	Windows 下 ImageMagick 无法自动探测，需指向 magick.exe；config.py#L63-L65 会在启动时将其写入 IMAGEMAGICK_BINARY 环境变量
ffmpeg_path	通常 ffmpeg 会自动下载探测；失败时手动指定，config.py#L67-L69 会将其写入 IMAGEIO_FFMPEG_EXE
endpoint	视频生成成功后 API 返回的下载链接前缀，默认取服务自身地址（如 http://127.0.0.1:8080/tasks/{task_id}/final-1.mp4）；用 nginx 反代对外提供时设为你的域名
enable_redis / redis_host / redis_port / redis_db / redis_password	任务状态管理后端；开启后使用 RedisTaskManager，否则用内存版 InMemoryTaskManager（app/controllers/v1/video.py#L37-L51）
max_concurrent_tasks	文生视频最大并发任务数，默认 5
hide_config	Web 界面是否隐藏基础配置面板

whisper 段（[whisper]）

仅当 subtitle_provider = "whisper" 时生效，底层使用 faster-whisper：

[whisper]
    model_size="large-v3"      # 官方推荐 large-v3
    device="CPU"               # 使用 GPU 时改为 "cuda"
    compute_type="int8"        # GPU 可选 float16 / int8_float16

代理与 Azure 语音（[proxy] / [azure]）

• [proxy]：http / https 两行，用于访问 Pexels 等海外站点时走代理，格式为 http://user:pass@proxy:port；
• [azure]：speech_key + speech_region，配置后可使用 9 种 Azure 神经网络音色，合成声音更接近真人。

API 使用：接口清单与请求参数

API 路由全部注册在 app/controllers/v1/video.py 与 app/controllers/v1/llm.py 中，由 app/router.py 汇总挂载。核心任务接口：

方法	路径	说明	对应 stop_at
POST	/videos	生成完整短视频（默认行为）	video
POST	/subtitle	只生成字幕	subtitle
POST	/audio	只生成配音音频	audio
GET	/tasks/{task_id}	查询任务状态、进度与产物下载链接	-

提交任务后接口立即返回 task_id，任务在后台线程池中执行（受 max_concurrent_tasks 约束），通过 GET /tasks/{task_id} 轮询状态，成功后返回 final-N.mp4 等产物的下载 URL（前缀由 endpoint 配置决定，见 video.py#L98-L120）。

TaskVideoRequest 关键字段（源自 VideoParams）

请求体定义在 app/models/schema.py 的 VideoParams，常用字段与默认值：

{
  "video_subject": "金钱的作用",
  "video_script": "",
  "video_language": "",
  "video_aspect": "9:16",
  "video_concat_mode": "random",
  "video_transition_mode": null,
  "video_clip_duration": 5,
  "video_count": 1,
  "video_source": "pexels",
  "voice_name": "zh-CN-XiaoxiaoNeural-Female",
  "voice_rate": 1.0,
  "voice_volume": 1.0,
  "bgm_type": "random",
  "bgm_volume": 0.2,
  "subtitle_enabled": true,
  "subtitle_position": "bottom",
  "font_name": "STHeitiMedium.ttc",
  "text_fore_color": "#FFFFFF",
  "font_size": 60,
  "stroke_color": "#000000",
  "stroke_width": 1.5,
  "n_threads": 2,
  "paragraph_number": 1
}

几个字段的行为细节：

• video_aspect："16:9" / "9:16" / "1:1"，分别映射到 1920x1080、1080x1920、1080x1080（schema.py#L30-L42）；
• video_source = "local" 时需提供 video_materials（素材 URL 列表），此时跳过搜索词生成与在线下载，直接走本地素材预处理（task.py#L126-L138）；
• voice_name 支持 Web 界面里的中文昵称（如“女生-晓晓”），源码中通过 voice.parse_voice_name() 将其归一化为 TTS 引擎可识别的音色 ID；
• 配音语言必须与文案语言匹配，否则音频生成会失败，源码日志会给出对应排查提示（task.py#L82-L90）。

GET /tasks/{task_id} 的状态查询支持按 stop_at 语义返回对应阶段产物（script / terms / audio_file / subtitle_path / materials / videos）。

语音合成与字幕生成

语音合成

所有支持的声音列表见 docs/voice-list.txt。基础配音基于 Edge TTS（edge_tts 依赖），无需 API Key；2024-04-16 版本起新增 9 种 Azure 语音合成声音，需要在 [azure] 段配置 speech_key 与 speech_region，合成效果更真实。

字幕生成：edge 与 whisper 两种模式

README 对两种 subtitle_provider 的取舍很明确：

• edge：生成速度快、对机器配置无要求，但质量可能不稳定；
• whisper：速度慢、对配置有一定要求，但质量更可靠；
• 建议先用 edge，字幕质量不满意再切 whisper；留空则不生成字幕。

源码层面，app/services/task.py#L96-L116 中还有一层自动降级：即使配置为 edge，若未生成出字幕文件，会自动 fallback 到 whisper 流程，并且 whisper 路径会额外调用 subtitle.correct() 用原文案校正识别错词。

whisper 模式需要模型文件 whisper-large-v3（约 3GB，默认从 HuggingFace 拉取）。国内网络不通时，可从网盘手动下载，解压后放到项目下的 models 目录，最终路径形如：

MoneyPrinterTurbo
  ├─models
  │   └─whisper-large-v3
  │          config.json
  │          model.bin
  │          preprocessor_config.json
  │          tokenizer.json
  │          vocabulary.json

背景音乐与字幕字体

• 背景音乐位于项目的 resource/songs 目录下，请求里 bgm_type = "random" 随机选取，或通过 bgm_file 指定具体文件，bgm_volume 控制音量（默认 0.2）；README 说明仓库内置的默认音乐来自 YouTube 视频，如涉及版权可自行删除替换。
• 字幕字体位于 resource/fonts 目录下，font_name 即该目录下的字体文件名；你也可以把自己的字体放进去供字幕渲染使用。

常见问题排查

以下问题均收录于 README，且大多有源码层面的解释：

如何用免费的 GPT-3.5 模型？

可用 Docker 拉起一个 GPT-3.5 兼容代理（如 docker run -p 3040:3040 missuo/freegpt35），然后在 config.toml 中：

• llm_provider = "openai"
• openai_api_key 随意填写（如 '123456'）
• openai_base_url = "http://localhost:3040/v1/"
• openai_model_name = "gpt-3.5-turbo"

注意该方式稳定性较差。

AttributeError: 'str' object has no attribute 'choices'

该错误源于大模型没有返回结构化响应（网络异常时常见）：app/services/llm.py#L244-L255 中，当 client.chat.completions.create() 返回的不是 ChatCompletion 对象时会抛出异常。解决办法：开启 VPN 全局模式，或将 openai_base_url 指向你的代理；README 同时建议国内优先使用 Moonshot 或 DeepSeek，访问更快更稳。

RuntimeError: No ffmpeg exe could be found

ffmpeg 正常情况下会被自动下载并自动检测；若环境无法联网下载，从官方构建包站点手动下载 ffmpeg，解压后在 config.toml 中设置：

[app]
# Windows 路径分隔符为 \\
ffmpeg_path = "C:\\Users\\harry\\Downloads\\ffmpeg.exe"

ImageMagick 安全策略阻止操作临时文件

在 ImageMagick 安装目录（或 /etc/ImageMagick-X/）下的 policy.xml 中，找到 pattern="@" 的条目，将 rights="none" 改为 rights="read|write"。

OSError: [Errno 24] Too many open files

系统打开文件数限制过低。用 ulimit -n 查看当前值，过低时执行 ulimit -n 10240 调高。

Whisper 模型下载失败（LocalEntryNotFoundError / 同步 Hugging Face Hub 报错）

按上文“字幕生成”一节手动下载 whisper-large-v3 并放置到 models/whisper-large-v3 目录即可绕过在线拉取。

项目背景与参考

• 该项目基于开源项目 MoneyPrinter 重构而来，做了大量优化并扩展了功能（README“参考项目”一节）；
• 文档站提供了更细化的使用指南，可参考 docs 目录 下的字幕生成、语音合成、背景乐、FAQ 等文章；
• 版本与变更历史见 CHANGELOG.md，changelog.py 用于生成更新日志；
• 许可证见 LICENSE。

小结

MoneyPrinterTurbo 的价值在于把“文案生成 → 搜索词提炼 → TTS 配音 → 字幕对齐 → 素材检索 → moviepy 合成”整条链路封装为一个可配置、可轮询的异步任务系统：config.toml 决定模型、素材与工具链，/api 层的 VideoParams 决定每一条视频的个性化风格，task.py 的六阶段流水线负责可靠执行。理解了 config.example.toml 的参数语义与 app/services/task.py 的阶段划分，就能覆盖从 Docker 一键部署到纯 API 集成的全部使用场景。