弹幕决定下一幕，AI 让直播继续生长。
API-first · MiniMax H3 · FastAPI · React · FFmpeg
Important
你的电脑跑不动 H3，也能运行 OpenH3Live。 v0.3 已接入 MiniMax H3 官方云 API，本机只负责导演、队列、预览和推流，不需要下载模型或配备高端 GPU。没有 API Key 时会自动启用免费的 Mock Provider，完整体验媒体循环。
普通文生视频 Demo 只生成一个文件；OpenH3Live 维护一场可以持续运行的互动直播：吸收弹幕、延续世界观、规划下一幕、保持片段库存，并在网络或生成故障时用安全片保证画面不断。
flowchart LR
A[观众弹幕] --> B[审核与优先级]
B --> C[AI 导演 / 故事记忆]
C --> D[SceneSpec]
D --> E{Video Provider}
E -->|MiniMax H3 API| F[云端生成]
E -->|Mock| G[本地演示]
F --> H[预缓冲队列]
G --> H
H --> I[连续播放]
J[安全 Filler] --> I
I --> K[Web 预览 / FFmpeg RTMP]
I -.尾帧连续性.-> D
- MiniMax H3 官方异步 API Provider，支持文本生成和上一片段首帧条件
auto自动选择：有MINIMAX_API_KEY就用云 API，否则使用 Mock- 无 GPU 的真实 H.264/AAC Mock 媒体，用于免费体验、开发和 CI
IDLE → PREBUFFER → LIVE → STOPPING状态机和目标缓冲水位- 弹幕去重、基础反垃圾、优先级评分和连续故事记忆
- 生成失败自动补片、尾帧提取、FFmpeg 进程监督和 RTMP 输出
- SQLite clip ledger、故事检查点和异常退出恢复
- FastAPI REST/WebSocket、React Studio 和 Python SDK
- 云端单场默认最多生成 20 个片段，避免无人值守时无限计费
需要 Python 3.11+。Node.js 只在修改前端时需要；FFmpeg 由 Python wheel 提供，无需单独安装。
git clone https://github.com/SUWJTech/OpenH3Live.git
cd OpenH3Live
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
openh3live start打开 http://localhost:7860，点击「开始无限直播」，再从右侧发送弹幕。默认无需密钥，会使用 Mock Provider。
Copy-Item .env.example .env在 .env 中填写：
OPENH3LIVE_PROVIDER=minimax-h3
MINIMAX_API_KEY=your_api_key重新启动 openh3live start 即可。启动前可以运行 openh3live doctor 检查 Provider 和 FFmpeg；详细选型、安全和费用控制见 API Provider 方案。
docker compose up --buildDocker 会读取本地 .env。如果不提供 Key，同样以 Mock 模式运行。
| Provider | 使用场景 | 本地 GPU | 状态 |
|---|---|---|---|
minimax-h3 |
真实 H3 内容、低本地门槛 | 不需要 | 已实现 |
mock |
免费体验、开发、测试 | 不需要 | 已实现 |
| fal H3 Max Director | 实时 WebRTC 连续生成 | 不需要 | 规划中 / 实验性 |
| 本地 H3 | 隐私与可控成本优先 | 需要 | 规划中 |
云 API 依然可能生成得比播放慢，因此 OpenH3Live 保留预缓冲和 filler；“无限”描述的是直播调度能力，不代表无限免费调用。默认预算可在 configs/default.yaml 的 model.max_clips_per_session 调整。
默认配置位于 configs/default.yaml：
model:
provider: auto
model: MiniMax-H3
resolution: 768P
max_clips_per_session: 20
live:
clip_duration: 5
min_ready_clips: 2
target_ready_clips: 3
max_ready_clips: 5
stream:
provider: preview
rtmp_url: null不要把 .env、API Key 或包含直播密钥的 RTMP URL 提交到仓库。
| Method | Path | 用途 |
|---|---|---|
GET |
/api/health |
Provider、FFmpeg、GPU 能力检测 |
GET |
/api/providers |
可用 Provider 和当前选择 |
GET |
/api/session |
完整直播快照与生成预算 |
POST |
/api/session/start |
预缓冲并开始播放 |
POST |
/api/session/stop |
安全停止当前会话 |
POST |
/api/chat/messages |
注入统一弹幕事件 |
WS |
/ws |
实时状态、队列和弹幕事件 |
交互式 OpenAPI 文档位于 http://localhost:7860/docs。
import asyncio
from openh3live import Live
async def main():
live = Live()
await live.start()
await live.danmaku("让橘猫驾驶飞船", username="viewer-01")
await asyncio.sleep(30)
await live.stop()
asyncio.run(main())pip install -e ".[dev]"
pnpm install
pytest
ruff check .
pnpm build
pnpm lint核心模块在 openh3live/，服务端在 apps/server/，Studio 在 apps/web/。设计细节见 架构文档，产品边界见 PRD，贡献流程见 CONTRIBUTING。
- OpenH3Live 是社区项目，不是 MiniMax 官方产品。
- 平台弹幕协议通过独立 Adapter 接入，核心运行时不依赖平台私有协议。
- 上线前应准备内容审核、鉴权、速率限制、安全片和平台条款检查。
- API 可用性、价格和模型许可由对应服务提供方决定。
Apache-2.0。欢迎在遵守模型许可证、素材版权和直播平台条款的前提下使用与贡献。