gyoridavid/short-video-maker · 上手攻略

仓库：gyoridavid/short-video-maker
链接：https://github.com/gyoridavid/short-video-maker
分类：AI · 视频生成 · MCP
作者：Tom
更新：2026-08-23

是什么

short-video-maker 是一个开源自动化短视频创作工具，通过文本脚本自动生成 TikTok / Instagram Reels / YouTube Shorts 风格的短视频。它同时暴露 REST API 和 MCP（Model Context Protocol） 接口，既可以配合 n8n 等工作流工具使用，也可以直接 API 调用。

它的定位是不需要 GPU 视频生成模型的免费替代方案——不从头生成视频（no video generation model），而是用 TTS 配音 + Whisper 字幕 + Pexels 素材 + Remotion 合成，出品是"有人配音、有字幕、有背景视频"的半专业短视频，硬件门槛远低于本地跑 Sora/Gen-3。

底层技术栈：Kokoro TTS（文本转语音） + Whisper.cpp（字幕生成） + Pexels API（背景视频搜索） + Remotion（视频合成）。

解决什么问题

内容创作者批量做短视频时遇到： - 配音难：自己配音耗时、声音不稳定、外语更困难； - 字幕烦：手动加字幕繁琐，自动字幕工具质量参差； - 素材贵： Shutterstock / Getty 视频素材订阅成本高； - GPU 门槛高：Stable Video Diffusion 等本地视频生成需要高端显卡； - 流程散：配音、字幕、素材、剪辑分散在多个工具里，难以自动化。

short-video-maker 把这四步串成一个 Docker 容器，一条 Prompt 提交后等视频出炉，不需要 GPU。

快速安装

推荐方式：Docker（一行启动）

docker run -it --rm \
  --name short-video-maker \
  -p 3123:3123 \
  -e LOG_LEVEL=debug \
  -e PEXELS_API_KEY=你的Pexels免费API密钥 \
  gyoridavid/short-video-maker:latest-tiny

服务启动后访问 http://localhost:3123 使用 Web UI。

三种 Docker 镜像规格

镜像	Whisper 模型	Kokoro 模型	适用场景
`latest-tiny`	tiny.en	q4 量化版	低内存（≥3 GB RAM）
`latest`（默认）	base.en	fp32 全精度	中等配置（≥4 GB RAM）
`latest-cuda`	medium.en + GPU	fp32	有 NVIDIA GPU

启动 CUDA 版（需显卡）：

docker run -it --rm \
  --name short-video-maker \
  -p 3123:3123 \
  -e LOG_LEVEL=debug \
  -e PEXELS_API_KEY=你的密钥 \
  --gpus=all \
  gyoridavid/short-video-maker:latest-cuda

内存优化参数（必设）

Remotion 在低显存环境容易 OOM，官方建议设置：

-e CONCURRENCY=1 \
-e VIDEO_CACHE_SIZE_IN_BYTES=2097152000   # 2 GB

与 n8n 联动（Docker Compose）

version: "3"
services:
  short-video-maker:
    image: gyoridavid/short-video-maker:latest-tiny
    environment:
      - PEXELS_API_KEY=你的密钥
    ports:
      - "3123:3123"
    volumes:
      - ./videos:/app/data/videos
    networks:
      - demo

在 n8n workflow 中用 HTTP Request 节点调用 http://short-video-maker:3123。

npm / npx 方式（需手动装依赖）

前提：Ubuntu ≥ 22.04 或 macOS + ffmpeg + Node.js 22+

# Ubuntu 安装系统依赖
sudo apt install git wget cmake ffmpeg curl make \
  libsdl2-dev libnss3 libdbus-1-3 libatk1.0-0 libgbm-dev \
  libasound2 libxrandr2 libxkbcommon-dev libxfixes3 \
  libxcomposite1 libxdamage1 libatk-bridge2.0-0 \
  libpango-1.0-0 libcairo2 libcups2

# macOS
brew install ffmpeg

# 然后
npx short-video-maker

⚠️ Windows 暂不支持：whisper.cpp 安装在 Windows 环境会偶发失败。

核心用法

场景与搜索词机制

每个视频由多个场景组成，每个场景包含： - Text（文案）：TTS 朗读的旁白脚本，同时生成对应字幕； - Search terms（搜索词）：Pexels 视频搜索关键词；若未找到，回退到 joker 词（nature / globe / space / ocean）。

Web UI（无 API 经验友好）

服务启动后打开 http://localhost:3123，在浏览器里填写文案、搜索词，选择音乐风格，直接生成。适合一次性创作，不写代码。

REST API 方式

生成视频（POST）：

curl -X POST http://localhost:3123/generate \
  -H "Content-Type: application/json" \
  -d '{
    "scenes": [
      {"text": "Welcome to my channel!", "search_terms": "technology"},
      {"text": "Today we explore AI tools.", "search_terms": "artificial intelligence"}
    ],
    "title": "AI Tools Overview"
  }'

查询状态：

curl http://localhost:3123/status/<job_id>

下载视频：

curl -O http://localhost:3123/video/<job_id>.mp4

MCP 方式（配合 AI Agent）

当 MCP 服务器启动后，支持 MCP 的 AI Agent（如 n8n）可以直接"调用"视频生成工具，将短剧创作编入更复杂的工作流。示例 n8n workflow 在配套仓库。

关键配置参数

环境变量（必需）

变量	说明	默认值
`PEXELS_API_KEY`	Pexels 免费 API Key	必须提供
`PORT`	服务监听端口	3123
`LOG_LEVEL`	日志级别（info / debug）	info

可选调优变量

变量	说明	默认值（tiny 镜像）
`WHISPER_MODEL`	Whisper.cpp 模型：`tiny` / `base` / `small` / `medium` / `large-v3` 等	`tiny.en`
`KOKORO_MODEL_PRECISION`	Kokoro TTS 精度：`fp32` / `fp16` / `q8` / `q4` / `q4f16`	`q4`
`CONCURRENCY`	Remotion 并发渲染 tab 数（建议 1）	1
`VIDEO_CACHE_SIZE_IN_BYTES`	Remotion 帧缓存大小	2097152000（2 GB）

⚠️ WHISPER_VERBOSE=true 会把 whisper.cpp 输出打到 stdout，生产环境建议 false。

典型适用场景

批量内容工厂：一次写多条脚本，API 调用批量生成系列视频；
AI 频道自动化：AutoGPT / n8n + short-video-maker = 无人值守内容流水线；
教程/解说类短视频：TTS 配音 + 字幕 + 素材全自动，不需要真人出镜；
多语言内容：⚠️ 当前 Kokoro 仅支持英文 TTS，其他语言需等待官方支持；
n8n 工作流集成：配合 AI Agent 做选题 → 脚本 → 视频全链路自动化。

坑与注意

TTS 仅英文（⚠️ 最重要限制）：Kokoro.js 目前不支持英文以外语言，若要做中文配音视频当前不可行；这是官方已知限制，非 bug。
Pexels API Key 必须：免费 Key 有每日限额（约 200 请求/天），高频率调用需注意配额；视频搜索回退词有限，热门时段 Pexels 可能限流。
whisper.cpp 对内存敏感：medium.en 模型需要较大 RAM，内存不足时视频生成会 OOM；latest-tiny 镜像是内存受限环境的安全选择。
Remotion 并发问题：CONCURRENCY=1 是官方推荐值，提高并发在低配置机器上会 OOM；渲染速度与并发数不可兼得。
Windows 不支持：whisper.cpp 依赖的系统库在 Windows 安装不稳定，开发文档明确标注 Windows 暂不支持。
不生成视频素材本身：背景视频来自 Pexels 有版权素材（可商用），但视频内容是被动展示非 AI 生成，若需要完全 AI 生成的视频内容需要配合其他工具。
Node.js 版本：官方在 Node.js 22+ 测试，低于 22 可能有兼容问题。

与同类对比

	short-video-maker	Runway / Sora 等	HeyGen	本地 SD Video
硬件要求	CPU + 4 GB RAM	云端 GPU	云端	高端本地 GPU
视频来源	Pexels 实拍素材	AI 生成	AI 数字人	AI 生成
配音	Kokoro TTS	TTS/原生配音	TTS/录音	不含
TTS 语言	仅英文	多种	多种	不含
字幕	Whisper 自动生成	部分	部分	不含
价格	免费 + Pexels 免费 Key	按次付费	订阅制	免费（需 GPU）
定制化	高（Prompt 控制）	高	中	高

一句话结论

short-video-maker 是目前最低硬件门槛的"AI 短视频工厂"——一条 Docker 命令起服务，一个 API 调用等视频出来，全程不需要显卡，适合想做内容自动化流水线但没有 GPU 预算的团队；唯一的硬性限制是英文 TTS，不支持中文是当前最大的坑。

⚠️ 本攻略依赖 GitHub README + 官方文档，未实际运行代码；Docker 镜像标签、Kokoro 模型列表等以仓库最新文档为准。建议启动前读一次仓库 Requirements 和 Environment variables 章节确认最新参数。