Pixelle-Video API 接入指南：Python SDK 与 REST 接口的短视频生成实战

Pixelle-Video API 接入指南：Python SDK 与 REST 接口的短视频生成实战

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

Pixelle-Video 是一套 AI 全自动短视频生成引擎，它对外提供两种能力接入方式：面向 Python 程序的 SDK（PixelleVideoCore）和面向任意客户端的 HTTP REST API。本篇指南以 docs/zh/reference/api-overview.md 为骨架，结合仓库源码（api/routers/video.py、api/schemas/video.py、pixelle_video/service.py 等）逐层拆解同步/异步视频生成、任务轮询、参数语义与文件访问机制，读完你可以直接用 SDK 或 curl 完成从文案到成片的全流程调用。

两种接入方式总览

Pixelle-Video 的 API 层设计为双通道：

• Python SDK：在进程内直接调用PixelleVideoCore，适合编写批处理脚本、集成到自己的后端服务或基于 Streamlit 的自有应用；
• HTTP REST API：FastAPI 实现，暴露/api/video/*、/api/tasks/*、/api/files/*等端点，任何语言/工具（curl、Postman、前端）都能调用，且自带 Swagger UI 交互文档。

二者底层共享同一套核心：REST 端点在 api/routers/video.py 中通过PixelleVideoDep依赖注入拿到全局的PixelleVideoCore实例（见 api/dependencies.py），最终都汇入pixelle_video.generate_video(...)这一条调用链。也就是说，SDK 里能配的参数，REST 请求体里基本都有对应字段。

Python SDK：PixelleVideoCore 与 generate_video()

初始化核心服务

SDK 的入口类是PixelleVideoCore（定义于 pixelle_video/service.py），文档给出的最小初始化方式：

from pixelle_video.service import PixelleVideoCore pixelle = PixelleVideoCore() await pixelle.initialize()

从源码看，PixelleVideoCore.__init__会通过全局config_manager读取配置（默认config.yaml），而initialize()负责组装所有核心能力（pixelle_video/service.py）：

• llm：LLMService，负责文案生成、分镜脚本、图像提示词等文本能力；
• tts：TTSService，语音合成；
• media/api_media：MediaService与APIProviderMediaService，图像/视频媒体生成；
• frame_processor：FrameProcessor，HTML 模板帧渲染；
• persistence/history：输出落盘与历史记录；
• pipelines：注册三套视频生成流水线standard、custom、asset_based。

值得注意的底层细节：ComfyKit 实例（负责与 ComfyUI/RunningHub 交互）不在initialize()中创建，而是首次使用时惰性创建，并且会通过配置 MD5 哈希检测 ComfyUI 地址、API Key 等配置变化后自动重建（pixelle_video/service.py），这让你在长驻进程中修改配置也能热生效。

初始化后即可直接使用各项能力，官方 docstring 中给出的示范（pixelle_video/service.py）：

from pixelle_video.service import pixelle_video # 全局单例 await pixelle_video.initialize() answer = await pixelle_video.llm("Explain atomic habits") audio = await pixelle_video.tts("Hello world") media = await pixelle_video.media(prompt="a cat") print(f"Using LLM: {pixelle_video.llm.active}") print(f"Available TTS: {pixelle_video.tts.available}")

PixelleVideoCore同时实现了异步上下文管理器（__aenter__/__aexit__），可用async with PixelleVideoCore() as pixelle:自动完成初始化和资源清理。

generate_video() 参数与返回值

文档列出的generate_video()核心参数：

参数	类型	说明
text	str	主题或完整文案
mode	str	生成模式："generate"（AI 生成）或"fixed"（固定文案）
n_scenes	int	分镜数量
title	str, optional	视频标题
tts_workflow	str	TTS 工作流
media_workflow	str	媒体生成工作流（图像或视频）
frame_template	str	视频模板
template_params	dict, optional	模板自定义参数
bgm_path	str, optional	BGM 文件路径
bgm_volume	float	BGM 音量（0.0-1.0）

返回值：VideoGenerationResult对象。其字段定义在 pixelle_video/models/storyboard.py：

@dataclass class VideoGenerationResult: video_path: str # 最终视频文件路径 storyboard: Storyboard # 完整分镜数据 duration: float # 视频总时长（秒） file_size: int # 文件大小（字节） created_at: datetime

storyboard里还包含每个分镜的叙述文案、图像提示词、视频片段路径等中间产物，方便做二次加工或调试（pixelle_video/models/storyboard.py）。

管道选择（pipeline）

generate_video实际是由_create_generate_video_wrapper()生成的包装函数，额外支持pipeline参数（pixelle_video/service.py）：

# 默认 standard 管道 result = await pixelle_video.generate_video(text="如何提高学习效率", n_scenes=5) # 指定 custom 管道 result = await pixelle_video.generate_video( text=your_content, pipeline="custom", custom_param_example="custom_value" )

可用的管道名称即initialize()中注册的standard、custom、asset_based；传入未知管道名会抛出ValueError并列出可用项。三套管道的实现分别位于 pixelle_video/pipelines/standard.py、pixelle_video/pipelines/custom.py、pixelle_video/pipelines/asset_based.py。

HTTP REST API：启动与端点速览

启动 API 服务器

文档给出的标准启动命令：

uv run uvicorn api.app:app --host 0.0.0.0 --port 8000

也可以直接运行应用入口文件并携带命令行参数（api/app.py）：

uv run python api/app.py --host 0.0.0.0 --port 8080 --reload

FastAPI 应用在启动时（lifespan生命周期，见 api/app.py）会自动启动任务管理器，并在关闭时统一清理任务与PixelleVideoCore资源。服务启动后可访问：

• http://localhost:8000/docs—— Swagger UI 交互文档
• http://localhost:8000/redoc—— ReDoc 文档
• http://localhost:8000/openapi.json—— OpenAPI 规范

根路径GET /会返回所有 API 分组索引（LLM、TTS、Image、Content、Video、Tasks、Files、Resources、Frame），全部挂载在/api前缀之下（api/app.py、api/routers/init.py）。

同步生成：POST /api/video/generate/sync

同步接口会阻塞等待视频生成完毕再返回结果，适合时长较短（约 < 30 秒）的视频。请求体示例（来自文档）：

{ "text": "为什么要养成阅读习惯", "mode": "generate", "n_scenes": 5, "frame_template": "1080x1920/image_default.html", "template_params": { "accent_color": "#3498db", "background": "https://example.com/custom-bg.jpg" }, "title": "阅读的力量" }

响应示例：

{ "success": true, "message": "Success", "video_url": "http://localhost:8000/api/files/xxx/final.mp4", "duration": 45.5, "file_size": 12345678 }

从实现看（api/routers/video.py），同步端点在真正调用生成前会做一件关键事：根据frame_template的 HTML meta 标签自动推导media_width与media_height（通过HTMLFrameGenerator.get_media_size()），因此frame_template是必填项——没有模板就无法确定视频分辨率，会直接报错。响应中的video_url由path_to_url()从结果文件路径换算而来。

异步生成：POST /api/video/generate/async

异步接口适合大视频，提交后立即返回任务 ID（api/routers/video.py）：

{ "success": true, "message": "Task created successfully", "task_id": "abc123" }

文档明确给出了异步模式的四步工作流：

1. 提交视频生成请求；
2. 从响应中拿到task_id；
3. 轮询GET /api/tasks/{task_id}查看状态；
4. 当状态为completed时，从result中取视频。

查询任务状态：GET /api/tasks/{task_id}

{ "task_id": "abc123", "status": "completed", "result": { "video_url": "http://localhost:8000/api/files/xxx/final.mp4", "duration": 45.5, "file_size": 12345678 } }

Task模型（api/tasks/models.py）还包含更丰富的字段：task_type、progress（current/total/percentage/message）、error、created_at、started_at、completed_at、request_params（提交时的原始参数）。

任务状态枚举（api/tasks/models.py）：

状态	含义
pending	等待执行
running	执行中
completed	已完成，result可用
failed	失败，error携带错误信息
cancelled	已取消

任务管理由内存版TaskManager承担（api/tasks/manager.py），除了查询还支持：

• GET /api/tasks?status=running&limit=100—— 按状态过滤、按创建时间倒序列出任务；
• DELETE /api/tasks/{task_id}—— 取消 pending/running 任务（终态任务不可取消）；
• 自动清理：默认每 3600 秒清理一次、保留 24 小时的已完成任务（见 api/config.py）。

请求参数完整说明

文档给出了 REST 请求参数总表，结合 api/schemas/video.py 的 Pydantic 校验规则，补充默认值与取值范围后如下：

参数	类型	必填	默认值/范围	说明
text	string	是	—	主题或完整文案
mode	string	否	"generate"	"generate"（AI 生成）或"fixed"（固定文案）
n_scenes	int	否	5，范围 1-20	分镜数量，仅 generate 模式有效
title	string	否	自动生成	视频标题
frame_template	string	否	—	HTML 模板路径，如1080x1920/image_default.html，同时决定视频分辨率
template_params	object	否	—	模板自定义参数（颜色、背景等）
media_workflow	string	否	—	媒体工作流（图像或视频生成）
tts_workflow	string	否	使用配置默认	TTS 工作流，如runninghub/tts_edge.json
ref_audio	string	否	—	声音克隆参考音频路径
voice_id	string	否	—	（已弃用）旧版声音 ID，建议改用tts_workflow
min_narration_words	int	否	5，范围 1-100	分镜叙述最少字数
max_narration_words	int	否	20，范围 1-200	分镜叙述最多字数
min_image_prompt_words	int	否	30，范围 10-100	图像提示词最少字数
max_image_prompt_words	int	否	60，范围 10-200	图像提示词最多字数
video_fps	int	否	30，范围 15-60	视频帧率
prompt_prefix	string	否	—	图像风格前缀
bgm_path	string	否	—	BGM 文件路径
bgm_volume	float	否	0.3，范围 0.0-1.0	BGM 音量

参数语义要点（从源码确认）：

• text在mode="generate"时是主题，AI 会据此生成标题、分镜与叙述文案；在mode="fixed"时是完整文案，直接进入后续处理，n_scenes被忽略；
• frame_template同时承担“确定视频尺寸”的职责，尺寸读取自模板 HTML 的 meta 标签；
• 字数类参数（min/max_narration_words、min/max_image_prompt_words）控制 AI 生成内容的篇幅粒度，从而间接影响视频节奏；
• ref_audio用于声音克隆，配合tts_workflow使用；旧参数voice_id在源码中会打印弃用警告并兼容透传（api/routers/video.py）。

模板与 template_params：自定义画面风格

frame_template指向仓库 templates 目录下的 HTML 模板，按分辨率分目录组织：

• 1080x1920/（竖屏）：image_default.html、image_book.html、image_neon.html、image_healing.html、video_default.html等二十余款；
• 1920x1080/（横屏）：image_book.html、image_film.html、image_full.html、image_ultrawide_minimal.html、image_wide_darktech.html；
• 1080x1080/（方形）：image_minimal_framed.html。

template_params用于向模板注入自定义变量，比如请求示例里的accent_color（强调色）与background（背景图）。可用参数随模板而异，schema 注释提示可通过GET /api/templates/{template_path}/params发现某个模板支持哪些参数（api/schemas/video.py）。模板还支持中文/英文双语静态图与动态视频两种形态，对应 docs/zh/user-guide/templates.md 中的模板体系说明。

视频文件访问机制

响应中的video_url形如http://localhost:8000/api/files/xxx/final.mp4，它由 api/routers/video.py 的path_to_url()生成：把生成结果的绝对/相对路径中output/之后的部分提取出来，拼接到请求的base_url上。因此：

• 开发环境返回http://localhost:8000/api/files/...；
• 如果通过域名访问，则自动返回https://your-domain.com/api/files/...，无需手工改 URL。

文件服务端点GET /api/files/{file_path:path}（api/routers/files.py）按优先级在白名单目录内定位文件：output/（生成结果）、workflows/（ComfyUI 工作流）、templates/（HTML 模板）、bgm/与data/bgm/（背景音乐）、data/templates/（自定义模板）以及resources/（图片、字体等资源）。

Swagger UI 与后续探索

API 的交互式文档位于http://localhost:8000/docs，支持直接在页面上填写参数、发送请求并查看响应，是调试参数最快捷的入口。同一 OpenAPI 定义还渲染为/redoc与/openapi.json。

进一步可参考：

• api/app.py —— FastAPI 应用装配、生命周期与全部路由注册；
• api/schemas/video.py —— 视频生成请求/响应的完整 Pydantic 模型（含校验范围）；
• api/routers/video.py —— 同步/异步端点的完整实现；
• api/tasks/manager.py —— 任务生命周期、并发与清理策略；
• api/config.py —— API 级配置（CORS、任务并发数、上传大小上限、文档 URL 等）；
• pixelle_video/service.py —— SDK 核心类与能力清单；
• config.example.yaml —— LLM、TTS、媒体等工作流的全局配置模板；
• docs/zh/user-guide/api.md 与 docs/zh/user-guide/web-ui.md —— 更完整的使用场景说明。

小结

Pixelle-Video 的 API 设计遵循“同核双通道”原则：SDK 适合进程内深度集成与批处理，REST 适合跨语言调用与 Web 服务化。实战时建议按视频体量选择接口——短小视频走同步端点拿结果最简单，长视频务必走异步端点并用task_id轮询，避免请求超时；frame_template与template_params的组合是控制成片规格与风格的关键，先用 Swagger UI 验证参数、再固化到脚本或服务中，是最稳妥的接入路径。

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