MoneyPrinterTurbo 功能全景解析：从 AI 文案到成片的短视频自动生成能力与实现

本文基于官方文档 功能特性 展开，系统梳理 MoneyPrinterTurbo 已实现的各项核心能力——AI/自定义文案、双画幅高清输出、批量生成、多模型接入、语音合成、字幕、背景音乐与无版权素材——并结合仓库源码逐项印证其实现位置与关键参数，帮助读者快速掌握该项目的功能边界，并了解如何通过 API 参数和 config.example.toml 配置落地使用。

MoneyPrinterTurbo WebUI 界面

MoneyPrinterTurbo WebUI 界面

一、功能总览与 MVC 架构

官方功能文档 sites/docs/guide/features.md 列出了项目当前已交付的能力清单：

• 完整的 MVC 架构，代码结构清晰、易于维护，同时支持 API 与 Web 界面 两种使用方式；
• 支持 AI 自动生成视频文案，也支持 自定义文案；
• 支持多种 高清视频尺寸：竖屏 9:16（1080x1920）、横屏 16:9（1920x1080）；
• 支持 批量视频生成，一次生成多个视频后挑选最满意的一个；
• 支持设置 视频片段时长，方便调节素材切换频率；
• 支持 中文 与 英文 视频文案；
• 支持 多种语音 合成；
• 支持 字幕生成，可调整 字体、位置、颜色、大小，并支持 字幕描边；
• 支持 背景音乐，随机或指定音乐文件，可设置 背景音乐音量；
• 视频素材来源 高清 且 无版权；
• 支持 OpenAI、moonshot、Azure、gpt4free、one-api、通义千问、Google Gemini、Ollama 等多种模型接入。

从源码结构看，这一功能清单与仓库的 MVC 分层一一对应：

• Controller（控制器）：app/router.py 定义根 APIRouter，并挂载 app/controllers/v1 下的 video 与 llm 两个子路由；main.py 通过 uvicorn 启动 app.asgi:app，服务启动后即可在 http://127.0.0.1:<端口>/docs 查看交互式 API 文档；
• Service（业务层）：app/services/ 目录按职责拆分为 llm.py（文案）、voice.py（配音）、material.py（素材搜索与下载）、subtitle.py（字幕）、video.py（剪辑合成）、task.py（任务编排）、state.py（状态管理）；
• Model（模型层）：app/models/schema.py 用 Pydantic 定义了所有请求/响应结构。

也就是说，文档中"API + Web 界面"的双入口，实际上共享同一套服务层：API 入口是 FastAPI 路由，Web 界面则是 webui/Main.py（可通过 webui.sh 或 webui.bat 启动）在浏览器中调用同一组 HTTP 接口。

二、API 与 Web 界面：两种入口的落地方式

API 入口的核心路由定义在 app/controllers/v1/video.py，与功能文档中"支持 API"直接对应：

@router.post("/videos", response_model=TaskResponse, summary="Generate a short video")
def create_video(background_tasks: BackgroundTasks, request: Request, body: TaskVideoRequest):
    return create_task(request, body, stop_at="video")

@router.post("/subtitle", response_model=TaskResponse, summary="Generate subtitle only")
def create_subtitle(...):
    return create_task(request, body, stop_at="subtitle")

@router.post("/audio", response_model=TaskResponse, summary="Generate audio only")
def create_audio(...):
    return create_task(request, body, stop_at="audio")

可以看到项目不止提供"生成完整视频"的 POST /videos，还提供了 POST /subtitle（仅生成带字幕的本地视频）与 POST /audio（仅生成配音音频）两个轻量接口，分别通过 stop_at 参数在任务流水线的不同阶段截停。任务创建后返回 task_id，随后通过 GET /tasks/{task_id} 查询进度与产物地址，DELETE /tasks/{task_id} 可清理任务目录——这套异步任务模型让"批量生成多个视频再挑选"变得简单：客户端只需循环提交多次 POST /videos，各自独立追踪 task_id。

任务管理器由配置决定：enable_redis = false 时使用内存管理器 InMemoryTaskManager，开启 Redis 后切换为 RedisTaskManager，两者都受 max_concurrent_tasks（默认 5，见 config.example.toml）约束，从源码结构看这是"批量生成"场景下的并发上限来源。

三、核心生成参数：一次看懂 VideoParams

功能文档提到的"画幅、批量数量、片段时长、中/英文文案"等能力，最终都收敛为 app/models/schema.py 中的 VideoParams 请求模型。下表整理了各参数的默认值与含义，可直接作为调用 POST /videos 的请求体参考：

参数	默认值	说明
video_subject	必填	视频主题/关键词，AI 据此生成文案与检索素材
video_script	""	自定义文案；填写后跳过 AI 文案生成，直接用它生成视频（对应文档"自定义文案"）
video_terms	None	指定用于检索素材的关键词，可传字符串或列表
video_aspect	9:16	画幅，取值见下表
video_concat_mode	random	素材拼接方式：random 或 sequential
video_transition_mode	None	转场效果（见"后期计划"）
video_clip_duration	5	每个片段时长（秒），即文档所说"素材切换频率"
video_count	1	一次生成的视频数量，即"批量生成"
video_language	""	文案语言，空值自动检测，可显式指定中文/英文
video_source	pexels	素材来源
voice_name / voice_volume / voice_rate	"" / 1.0 / 1.0	配音名称、音量、语速
bgm_type / bgm_file / bgm_volume	random / "" / 0.2	背景音乐模式、指定文件、音量
subtitle_enabled	True	是否生成字幕
subtitle_position / custom_position	bottom / 70.0	字幕位置（top/bottom/center）与自定义百分比
font_name	STHeitiMedium.ttc	字幕字体文件
text_fore_color / text_background_color	#FFFFFF / True	字幕前景色、背景色
font_size	60	字幕字号
stroke_color / stroke_width	#000000 / 1.5	字幕描边颜色与宽度
n_threads	2	并发线程数
paragraph_number	1	文案段落数

其中画幅由 app/models/schema.py 的 VideoAspect 枚举映射为具体分辨率，与功能文档一致：

class VideoAspect(str, Enum):
    landscape = "16:9"
    portrait = "9:16"
    square = "1:1"

    def to_resolution(self):
        if self == VideoAspect.landscape.value:
            return 1920, 1080
        elif self == VideoAspect.portrait.value:
            return 1080, 1920
        elif self == VideoAspect.square.value:
            return 1080, 1080
        return 1080, 1920

值得注意的一点：文档列出的 9:16 / 16:9 两种尺寸在源码中还额外支持 1:1（1080x1080），可用于方形画幅平台，这是阅读源码获得的增量信息。

四、AI 文案生成：多模型接入的实现

功能文档宣称支持 OpenAI、moonshot、Azure、gpt4free、one-api、通义千问、Google Gemini、Ollama 等模型接入。配置侧对应 config.example.toml 中的 [app] 段：

# 支持的提供商: openai / moonshot / oneapi / g4f / azure / qwen / gemini
llm_provider = "openai"

########## Ollama Settings ##########
ollama_base_url = ""
ollama_model_name = ""

########## OpenAI API Key ##########
openai_api_key = ""
openai_base_url = ""
openai_model_name = "gpt-4-turbo"

########## Moonshot API Key ##########
moonshot_api_key = ""
moonshot_base_url = "https://api.moonshot.cn/v1"
moonshot_model_name = "moonshot-v1-8k"

########## OneAPI ##########
oneapi_api_key = ""
oneapi_base_url = ""
oneapi_model_name = ""

########## G4F ##########
g4f_model_name = "gpt-3.5-turbo"

########## Azure ##########
azure_api_key = ""
azure_base_url = ""
azure_model_name = "gpt-35-turbo"
azure_api_version = "2024-02-15-preview"

########## Gemini ##########
gemini_api_key = ""
gemini_model_name = "gemini-1.0-pro"

########## Qwen ##########
qwen_api_key = ""
qwen_model_name = "qwen-max"

########## DeepSeek ##########
deepseek_api_key = ""
deepseek_base_url = "https://api.deepseek.com"
deepseek_model_name = "deepseek-chat"

运行侧的实现集中在 app/services/llm.py 的 _generate_response()：先读取 llm_provider 决定走 g4f（无需 Key 的免费通道）还是各提供商的 OpenAI 兼容接口，然后按 provider 分发到对应的 api_key / model_name / base_url：

• g4f：直接调用 g4f.ChatCompletion.create，默认模型 gpt-3.5-turbo-16k-0613；
• ollama：base_url 留空时回落到 http://localhost:11434/v1，api_key 任意字符串即可；
• openai / oneapi：base_url 留空时回落 https://api.openai.com/v1，因此 oneapi 网关只要指向兼容地址即可接入；
• qwen：走 dashscope 官方 SDK 的 Generation.call；
• gemini：走 google.generativeai，固定 temperature=0.5、max_output_tokens=2048 等生成参数；
• azure：额外携带 azure_api_version（默认 2024-02-15-preview）。

源码中还存在 cloudflare、ernie、deepseek 等分支，说明实际支持的面比文档清单更广；任何 provider 缺 Key 或模型名都会抛出明确的 ValueError 提示到 config.toml 补全，排错成本较低。

"自定义文案"与"AI 生成文案"的边界也很清晰：VideoParams.video_script 非空时流水线直接使用给定文案，不再调用 LLM；app/services/llm.py 还提供独立的 /llm/script 与 /llm/terms 接口（路由挂载于 app/router.py），可单独生成文案或从主题/文案中提取检索关键词，供 video_terms 使用。

五、视频素材：高清、无版权、多 Key 轮询

文档强调素材"高清且无版权"。实现位于 app/services/material.py：

• 来源：默认 Pexels（video_source = "pexels"），可切换 Pixabay，两者均提供免版权素材，对应 config.example.toml 中 video_source 与两组 API Key 配置；
• 高清保证：Pexels 搜索时按 video_aspect 计算目标宽高，只挑选分辨率完全匹配（如竖屏精确 1080x1920）且时长不小于 video_clip_duration 的片段，从源头保证素材清晰度和切换节奏匹配；
• 多 Key 轮询：get_api_key() 支持传入多个 Key 并按请求次数取模轮询（api_keys[requested_count % len(api_keys)]），用于规避单 Key 限流，这与配置文件中"多个 Key 用逗号隔开"的注释相互印证；
• 代理支持：搜索请求统一携带 [proxy] 段配置的代理，解决网络受限环境的素材下载问题。

素材落盘位置由 material_directory 控制：留空使用默认 ./storage/cache_videos 缓存目录（可跨任务复用），设为 "task" 则下载到当前任务目录（不复用），设为绝对路径则自定义目录，见 config.example.toml。

六、语音合成：内置多音色列表

文档"支持多种语音合成"对应 app/services/voice.py。实现基于 edge-tts，get_all_azure_voices() 内嵌了一份按语言/性别组织的 Neural 音色清单（默认过滤 zh-CN、en-US、zh-HK、zh-TW、vi-VN），这解释了功能清单中"中文与英文文案"的语音支撑：voice_name 既可用 WebUI 中的友好名（如"女生-晓晓"），也可用底层音色 ID（如 zh-CN-XiaoxiaoNeural-Female，见 app/models/schema.py 中 SubtitleRequest.voice_name 的默认值）。完整音色列表可参考 docs/voice-list.txt。voice_volume 与 voice_rate 分别控制音量与语速，方便后期统一调节。

七、字幕与背景音乐：可逐项调参的后期能力

字幕方面，文档列出字体、位置、颜色、大小、描边五个可调维度，在 VideoParams 中一一对应：font_name（字体文件）、subtitle_position（top/bottom/center，配合 custom_position 百分比微调）、text_fore_color / text_background_color（前景/背景色）、font_size（字号）、stroke_color / stroke_width（描边颜色/宽度）。字幕生成引擎由 config.example.toml 的 subtitle_provider 决定，取 "edge"（随 TTS 返回的时间轴）或 "whisper"（本地 ASR，[whisper] 段可配模型大小、GPU/CPU 与计算类型）；留空则不生成字幕。

背景音乐方面，bgm_type 取 random 或指定模式，bgm_file 指定具体音乐文件，bgm_volume 默认 0.2，实现"随机或指定 + 音量可调"的完整闭环。API 侧还配套了 BGM 检索/上传接口（BgmRetrieveResponse / BgmUploadResponse，见 app/models/schema.py），WebUI 中即可浏览内置曲库或上传自有音乐。

八、批量生成与任务流：功能如何在代码中闭环

"一次生成多个视频，再挑选最满意的一个"这一能力，落到代码上是三层协作：

1. 入口：POST /videos 将 TaskVideoRequest 序列化为 params 存入任务，video_count 控制单任务内产物数量；
2. 执行：task_manager.add_task(tm.start, ...) 把任务投递给管理器，max_concurrent_tasks 限制并发（默认 5），批量提交多任务时天然被限流保护；
3. 追踪：GET /tasks/{task_id} 返回 state / progress / videos（各独立成片）/ combined_videos（拼接成片），产物 URL 形如 http://127.0.0.1:8080/tasks/<task_id>/final-1.mp4，可配置 endpoint 域名经 nginx 代理对外暴露（见 config.example.toml）。

这样"批量生成 + 状态查询 + 挑选下载"的完整工作流全部有 API 支撑，WebUI 本质上就是在图形界面上执行同样的调用链。

九、后期计划（Roadmap）

官方文档同时给出了未实现能力清单（sites/docs/guide/features.md），使用项目时需注意以下功能当前尚未提供：

• GPT-SoVITS 配音支持；
• 利用大模型优化语音合成，使声音更自然、情绪更丰富；
• 视频转场效果，提升观看流畅度（VideoParams.video_transition_mode 字段已预留枚举，但功能尚在计划中）；
• 优化视频内容与素材的匹配度；
• 视频长度选项：短、中、长；
• 打包 Windows/macOS 一键启动程序；
• 使用自定义素材（源码中 video_materials 字段已预留本地素材入口，从源码结构看该能力正在建设中）；
• 配音与背景音乐的实时试听；
• 接入更多 TTS 服务商，如 OpenAI TTS、Azure TTS；
• 自动上传 YouTube。

十、小结与使用建议

MoneyPrinterTurbo 的功能矩阵可以概括为："一个主题进，若干条成片出"。落地使用时的关键抓手只有两处——请求参数（app/models/schema.py 的 VideoParams）与配置文件（config.example.toml）。建议按如下顺序验证功能：先配置 llm_provider 与素材 Key，用 POST /videos 生成一条 9:16 默认参数视频；再调整 video_count、video_clip_duration 体验批量与节奏控制；最后通过 font_*、bgm_*、voice_* 参数打磨字幕与音轨。每一项文档中的功能承诺，都可在上述文件路径中找到对应的实现依据，便于二次开发与问题定位。