Pixelle-Video 使用指南：从一句话主题到 AI 全自动短视频的完整实战手册-开发者社区

Pixelle-Video 使用指南：从一句话主题到 AI 全自动短视频的完整实战手册

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video

本指南以 Pixelle-Video 官方 README 为主线，系统讲解这款 AI 全自动短视频引擎的核心能力、模块化生成流程、安装部署方式、配置项含义与 Web 界面三栏布局的完整操作步骤。读完本文，你将掌握从「输入一个主题」到「自动产出带 AI 配图、语音解说与背景音乐的成片视频」的全链路实战方法，并理解其背后基于 Streamlit 与流水线架构的实现原理。

项目定位：AI 全自动短视频引擎

Pixelle-Video 的核心设计理念是零门槛、零剪辑经验——用户只需要输入一个主题，引擎即可自动完成以下五步工作：

✍️ 撰写视频文案：由 LLM 根据主题智能创作解说词；
🎨 生成 AI 配图/视频：为每句解说生成对应的 AI 插图，或调用视频模型生成动态画面；
🗣️ 合成语音解说：通过 TTS 将文案转为旁白音频；
🎵 添加背景音乐：支持内置或自定义 BGM；
🎬 一键合成视频：逐帧渲染后拼接输出最终成片。

从仓库源码结构看，这一整套能力被封装在服务层 pixelle_video/service.py 的PixelleVideoCore中，它统一暴露llm（文案）、tts（语音）、media/api_media（图像与视频）、video（合成）、frame_processor（逐帧渲染）等能力，并注册了standard、custom、asset_based三条视频生成流水线（见 pixelle_video/service.py）。Web 界面与核心服务分层解耦，前者负责交互，后者负责生成。

功能亮点一览

全自动生成：输入主题即自动产出完整视频；
AI 智能文案：无需自己写脚本，LLM 根据主题创作解说词；
AI 生成配图：每个分镜都配有精美 AI 插图；
AI 生成视频：支持 WAN 2.1 等 AI 视频生成模型创建动态内容；
直连模型 API：可直接调用 DashScope、OpenAI、Seedream、Seedance、Kling 等图像/视频生成服务；
AI 生成语音：支持 Edge-TTS、Index-TTS 等主流 TTS 方案；
背景音乐：支持添加 BGM 增强氛围；
视觉风格：多种 HTML 模板可选，打造独特视频风格；
灵活尺寸：支持竖屏（1080x1920）、横屏（1920x1080）、方形（1080x1080）等多种画幅；
多种 AI 模型：支持 GPT、通义千问、DeepSeek、Ollama 等 LLM；
原子能力灵活组合：既支持 ComfyUI / RunningHub 工作流，也支持直连 API 模型，可随时替换图像、视频、TTS、VLM 等能力。

视频生成流程：模块化的四段式流水线

README 将 Pixelle-Video 的生成流程概括为四步：

文案生成 → 配图规划 → 逐帧处理 → 视频合成

每个环节都支持灵活定制：文案可选择不同 LLM、配图可选择不同图像工作流与风格、语音可选择不同 TTS 引擎、画面可选择不同模板与尺寸。

源码视角：标准流水线的八个阶段

以默认的standard流水线（pixelle_video/pipelines/standard.py）为例，底层实现远比四段式更细，共拆分为八个阶段，与 README 的宏观描述一一对应：

阶段	对应方法	作用
1. 环境准备	`setup_environment`	创建独立任务目录与任务 ID，确定最终视频输出路径
2. 内容生成	`generate_content`	按`generate`/`fixed`两种模式生成或切分解说词
3. 标题生成	`determine_title`	自动生成或使用用户指定的视频标题
4. 视觉规划	`plan_visuals`	为每句解说生成图像提示词（可叠加风格前缀）
5. 分镜初始化	`initialize_storyboard`	组装 Storyboard 与逐帧分镜数据
6. 素材生产	`produce_assets`	逐帧生成音频、图像并渲染画面（核心耗时环节）
7. 后期合成	`post_production`	拼接所有视频片段、叠加 BGM
8. 结果收尾	`finalize`	生成结果对象并持久化任务元数据

值得注意的两点实现细节：

模板类型感知：在plan_visuals阶段，引擎会根据所选模板的前缀（static_/image_/video_）判断是否需要生成媒体素材。静态模板（static_*）会完全跳过图像提示词与媒体生成，从而节省 LLM 调用次数与生成成本（见 pixelle_video/pipelines/standard.py）。
RunningHub 并行处理：当使用runninghub/前缀的工作流时，produce_assets会基于配置的并发上限（runninghub_concurrent_limit）用asyncio.Semaphore并行处理多个分镜，显著缩短生成时间（见 pixelle_video/pipelines/standard.py）。

快速开始：两种安装方式

方式一：Windows 一键整合包（推荐 Windows 用户）

整合包无需安装 Python、uv 或 ffmpeg，解压即可使用：

从项目 Releases 页面下载最新的 Windows 一键整合包并解压；
双击运行start.bat启动 Web 界面；
浏览器自动打开 http://localhost:8501 ；
在「⚙️ 系统配置」中配置 LLM API 和图像生成服务；
开始生成视频。

整合包已内置全部依赖与启动脚本（参见 packaging/windows/templates/start.bat），首次使用只需配置 API 密钥。

方式二：从源码安装（macOS / Linux / 需要自定义的用户）

前置环境依赖

安装 Python 包管理器uv（用于自动管理依赖）与视频处理工具ffmpeg（用于视频合成）：

uv：参照官方安装指南完成安装后，运行uv --version验证；
ffmpeg：
- macOS：brew install ffmpeg
- Ubuntu / Debian：sudo apt update && sudo apt install ffmpeg
- Windows：下载后解压，将bin目录加入系统 PATH 环境变量

安装完成后运行ffmpeg -version验证。

三步启动

# 第一步：下载项目 git clone https://gitcode.com/GitHub_Trending/pi/Pixelle-Video.git cd Pixelle-Video # 第二步：启动 Web 界面（uv 会自动安装依赖） uv run streamlit run web/app.py

浏览器会自动打开 http://localhost:8501。Web 入口定义在 web/app.py，采用 Streamlit 多页面导航结构，包含「Home」主页与「History」历史记录页。

第三步：在 Web 界面完成首次配置

展开「⚙️ 系统配置」面板，填写：

LLM 配置：选择 AI 模型（通义千问、GPT 等）并填入 API Key；
ComfyUI / RunningHub 配置：如需用工作流生成图片、视频或语音，配置本地 ComfyUI 地址或 RunningHub API Key；
API 媒体模型配置：如需直连图像/视频模型，配置 DashScope、OpenAI、ARK、Kling 等供应商的 API Key、Base URL 与代理选项。

配置完成后点击「保存配置」，即可开始生成视频。

配置文件 config.yaml 深度解析

除 Web 界面外，Pixelle-Video 也支持通过 YAML 文件集中管理配置。仓库提供了一份完整的示例 config.example.yaml，复制为config.yaml即可使用（注意：切勿将含密钥的config.yaml提交到 Git）。

LLM 配置

llm: api_key: "" base_url: "" model: ""

配置项说明：

api_key：模型服务密钥；
base_url：API 地址，兼容任何 OpenAI SDK 协议的服务；
model：模型名称。

Web 界面中的「快速选择预设」正是读取自 pixelle_video/llm_presets.py 中内置的预设表，选择后自动填充base_url与model：

预设名称	base_url	默认 model
Qwen	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-max`
OpenAI	`https://api.openai.com/v1`	`gpt-4o`
Claude	`https://api.anthropic.com/v1/`	`claude-sonnet-4-5`
DeepSeek	`https://api.deepseek.com`	`deepseek-chat`
Ollama（本地）	`http://localhost:11434/v1`	`llama3.2`
Moonshot	`https://api.moonshot.cn/v1`	`moonshot-v1-8k`

Ollama 预设的default_api_key为"ollama"（OpenAI SDK 要求必填但 Ollama 会忽略）。所有预设均遵循 OpenAI SDK 协议，理论上任何兼容该协议的私有部署模型都可手动填入。

直连 API 供应商配置

api_providers: common: print_model_input: false # 调试用：打印发送给模型的 prompt、模型名与输入文件路径 local_proxy: "" # 本地代理，如 http://127.0.0.1:9090 openai: api_key: "" base_url: "https://api.openai.com/v1" use_proxy: false dashscope: api_key: "" base_url: "https://dashscope.aliyuncs.com/api/v1" use_proxy: false ark: api_key: "" base_url: "https://ark.cn-beijing.volces.com/api/v3" use_proxy: false kling: base_url: "https://api-beijing.klingai.com" access_key: "" secret_key: "" use_proxy: false

common段的local_proxy与use_proxy组合决定了各供应商请求是否走本地代理；print_model_input用于在终端打印请求参数便于调试。底层读取逻辑见 pixelle_video/services/api_services/config.py，它优先从配置管理器取值，其次回退到同名环境变量。

ComfyUI / RunningHub 配置

comfyui: comfyui_url: http://127.0.0.1:8188 # 本地 ComfyUI 地址（selfhost 工作流必需） comfyui_api_key: "" # ComfyUI API Key（可选） runninghub_api_key: "" # RunningHub 云端密钥（runninghub 工作流必需） runninghub_concurrent_limit: 1 # RunningHub 并发上限（1-10，普通会员默认 1） tts: default_workflow: selfhost/tts_edge.json image: default_workflow: runninghub/image_flux.json prompt_prefix: "Minimalist black-and-white matchstick figure style illustration, clean lines, simple sketch style" video: default_workflow: runninghub/video_wan2.1_fusionx.json prompt_prefix: "Minimalist black-and-white matchstick figure style illustration, clean lines, simple sketch style"

要点：

Docker 环境下使用 ComfyUI 时，macOS/Windows 填host.docker.internal:8188，Linux 填宿主机 IP；
image.default_workflow与video.default_workflow为必填项且无回退，选项包括runninghub/*（无需本地环境，推荐）与selfhost/*（需本地 ComfyUI）；
prompt_prefix控制整体画面风格，语言需为英文，在 pixelle_video/pipelines/standard.py 中与 LLM 生成的图像提示词拼接；
runninghub_concurrent_limit支持热更新，无需重启即可生效。

模板默认配置

template: default_template: "1080x1920/image_default.html"

该配置决定了未显式指定时的默认画面模板，同时隐含视频画幅比例。模板命名约定与仓库templates/目录结构一致：

static_*.html：静态模板（无需 AI 生成媒体，纯文字样式）；
image_*.html：图片模板（以 AI 生成图片为背景）；
video_*.html：视频模板（以 AI 生成视频为背景）。

可选画幅：1080x1920（竖屏）、1080x1080（方形）、1920x1080（横屏），具体见 templates 目录。

Web 界面使用指南：三栏布局实战

打开 Web 界面后是典型的三栏布局：左侧内容输入、中间语音与视觉设置、右侧生成视频。主页渲染逻辑见 web/pages/1_🎬_Home.py，不同类型的生成流水线（标准生成、自定义素材、数字人、图生视频、动作迁移等）以 Tab 形式切换，每种流水线 UI 通过 web/pipelines/base.py 的注册机制挂载。

⚙️ 系统配置（首次必填）

1. LLM 配置

用于生成视频文案的 AI：

快速选择预设：下拉选择通义千问、GPT-4o、DeepSeek 等预设后自动填充base_url和model，再填入 API Key；
手动配置：直接填写 API Key、Base URL、Model 三项。

2. ComfyUI / RunningHub 配置

用于通过工作流生成配图、视频片段或语音：

本地部署（推荐）：填写 ComfyUI URL（默认http://127.0.0.1:8188），点击「测试连接」验证服务可用；
云端部署：填写 RunningHub API Key。

3. API 媒体模型配置

用于不依赖 ComfyUI/RunningHub 时直连模型供应商的图像、视频或素材分析能力。支持的供应商包括：

OpenAI / GPT Image：GPT 图像生成模型；
DashScope / Wan / HappyHorse：通义万象图像与视频生成；
Volcengine ARK / Seedream / Seedance：字节 Seedream 图像与 Seedance 视频生成；
Kling AI / 可灵：可灵视频生成。

可配置项包括：API Key / Access Key / Secret Key（鉴权信息）、Base URL（WebUI 提供官方默认地址）、本地代理（如http://127.0.0.1:9090）、启用代理（每个供应商独立开关）、打印模型请求参数（调试用）。

💡 若只使用 ComfyUI 或 RunningHub，可不填此项；若选择api/...工作流，则必须配置对应供应商的密钥。

这些供应商与模型在源码中登记于 pixelle_video/services/api_media.py：图像侧包括 dashscope（wan2.7-image 系列）、openai（gpt-image-2）、seedream（doubao-seedream 系列）；视频侧包括 dashscope（wan2.7-t2v、happyhorse 系列等）、kling（kling-v3 等）、seedance（doubao-seedance 系列）。每款视频模型的能力元数据（时长范围、分辨率、画幅比例、原生音频、水印等）登记在VIDEO_MODEL_CAPABILITIES中，WebUI 会据此动态展示可用参数。

📝 内容输入（左侧栏）

生成模式

AI 生成内容：输入主题，AI 自动创作文案。适合想快速出片、让 AI 写稿的场景，例如「为什么要养成阅读习惯」；
固定文案内容：直接输入完整文案，跳过 AI 创作。适合已有现成稿件的场景，支持段落/行/句子多种分割方式。

背景音乐（BGM）

无 BGM：纯人声解说；
内置音乐：选择预置背景音乐（如 default.mp3）；
自定义音乐：将 MP3/WAV 等音乐文件放入仓库根目录的 bgm 文件夹即可在列表中选用；
可点击「试听 BGM」预览效果。

🎤 语音设置（中间栏）

TTS 工作流

从下拉菜单选择 TTS 工作流（支持 Edge-TTS、Index-TTS 等），系统会自动扫描 workflows 文件夹中的 TTS 工作流（仓库内置tts_edge.json、tts_index2.json、tts_spark.json等）；熟悉 ComfyUI 的用户也可自定义 TTS 工作流放入该目录。

参考音频（可选）

上传参考音频文件用于声音克隆（支持 MP3/WAV/FLAC 等格式），适用于支持声音克隆的 TTS 工作流（如 Index-TTS），上传后可直接试听。

预览功能

输入测试文本后点击「预览语音」即可试听效果，同样支持携带参考音频预览。

🎨 视觉设置（中间栏）

图像生成

决定 AI 生成配图的风格：

ComfyUI 工作流：下拉选择图像生成工作流，支持本地（selfhost）与云端（RunningHub）两类，也支持api/...直连图像模型（需先在系统配置中填写对应供应商密钥）；默认使用image_flux.json；自定义工作流可放入 workflows 文件夹；
图像尺寸：设置生成图像的宽高（像素），默认 1024x1024；注意不同模型对尺寸有限制；
提示词前缀（Prompt Prefix）：控制整体风格（需为英文），例如Minimalist black-and-white matchstick figure style illustration, clean lines, simple sketch style，可点击「预览风格」测试效果。

视频模板

决定视频画面的布局与设计：

从下拉菜单按尺寸分组选择模板（竖屏 / 横屏 / 方形）；
命名规范：static_*.html静态、image_*.html图片、video_*.html视频；
点击「预览模板」可自定义参数测试效果；
懂 HTML 的用户可在 templates 文件夹创建自己的模板。

API 视频生成

当选择动态视频模板或扩展工作流时，可直连 API 视频模型生成片段：

支持 DashScope Wan / HappyHorse、Kling、Seedance 等视频模型；
按模型能力动态展示分辨率、画幅比例、时长、水印、原生音频等参数；
支持网络/下载重试，以及内容审核失败后自动用 LLM 将提示词「中性化改写」后重试（实现在 pixelle_video/services/api_media.py，重试机制检测datainspectionfailed、inappropriate content等审核错误标记）；
在「自定义素材」工作流中，API 视频片段会尽量匹配旁白音频时长，并利用相邻片段信息提升画面连贯性。

🎬 生成视频（右侧栏）

配置完成后点击「🎬 生成视频」；
界面实时显示进度（生成文案 → 生成配图 → 合成语音 → 合成视频），例如「分镜 3/5 - 生成插图」；
生成完成后自动播放预览，并显示视频时长、文件大小、分镜数等信息；
视频文件保存在 output 文件夹，任务元数据与分镜信息由 pixelle_video/services/persistence.py 持久化，可在「History」历史记录页回顾与复用。

常见问题 FAQ

Q: 第一次生成一个视频需要多久？

A: 取决于视频分镜数量、网络状况与 AI 推理速度，通常几分钟内即可完成。

Q: 视频效果不满意怎么办？

A: 可以从四个维度迭代：

更换 LLM 模型（不同模型文案风格不同）；
调整图像尺寸与提示词前缀（改变配图风格）；
更换 TTS 工作流或上传参考音频（改变语音效果）；
尝试不同的视频模板与画面尺寸。

Q: 费用大概多少？

A: 项目完全支持免费运行，常见方案组合：

完全免费方案：LLM 使用本地 Ollama + ComfyUI 本地部署 = 0 元（适合本地有显卡的用户）；
推荐方案：LLM 使用通义千问（成本极低、性价比高）+ ComfyUI 本地部署；
云端方案：LLM 使用 OpenAI + 图像使用 RunningHub（费用较高但无需本地环境）。