企业官网建设流程全解析

Pixelle-Video API 完全指南：Python SDK 与 HTTP REST 双接口实战

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

导读

Pixelle-Video 是一套 AI 全自动短视频生成引擎，对外同时暴露 Python SDK 与 HTTP REST API 两种调用方式，开发者既可以在 Python 代码中直接驱动端到端视频生成，也可以通过 HTTP 接口将生成能力集成进任意语言的服务端。本文以官方 API 参考文档为主线，结合仓库内pixelle_video/service.py、api/routers/video.py、api/tasks/manager.py等源码实现，系统讲解 SDK 初始化、generate_video()全参数、同步/异步生成端点、任务状态查询与完整请求参数语义，读完后你可以直接在自己的项目中接入并跑通第一条 AI 视频生成链路。

一、双入口架构概览

从仓库结构看，Pixelle-Video 的对外能力分为两层（对应 docs/en/reference/api-overview.md 的主线）：

• Python SDK：以PixelleVideoCore为核心门面类，统一封装 LLM、TTS、图片/视频生成、模板渲染、流水线调度等全部能力，适合在 Python 脚本、服务进程或 Web 后端中直接调用；
• HTTP REST API：基于 FastAPI 构建，位于api/目录，将 SDK 能力封装为一组 REST 端点（视频生成、任务管理、文件访问、资源查询等），适合跨语言集成与远程调用。

两类入口共享同一套底层实现，SDK 负责"进程内调用"，REST API 负责"跨进程调用"，二者参数模型高度一致——HTTP 请求体中的字段与 SDKgenerate_video()的关键字参数一一对应，掌握一套即可触类旁通。

二、Python SDK 使用详解

2.1 初始化 PixelleVideoCore

PixelleVideoCore是 SDK 的主服务类，定义于 pixelle_video/service.py。文档给出的最小用法如下：

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

结合源码可以补充以下几点关键行为：

• 配置来源：PixelleVideoCore(config_path="config.yaml")构造时读取全局配置管理器config_manager的单例（即仓库根目录的config.yaml，可参照 config.example.yaml 编写），LLM、TTS、ComfyUI、模板等能力均由此驱动。
• 初始化内容：initialize()会依次装配LLMService、TTSService、APIProviderMediaService、MediaService、FrameProcessor、PersistenceService、HistoryManager等组件，并注册三条视频生成流水线standard/custom/asset_based（见 pixelle_video/service.py）。
• ComfyUI 懒加载：ComfyKit 实例并不在initialize()中创建，而是在首次使用时按需创建，并通过配置哈希检测配置变更、自动重建实例（_get_or_create_comfykit/_compute_comfykit_config_hash），支持热更新 ComfyUI 地址与 API Key。
• 资源释放：使用完毕可调用await pixelle.cleanup()关闭 ComfyKit 会话；类本身也实现了异步上下文管理器（__aenter__/__aexit__），推荐写法：

from pixelle_video.service import PixelleVideoCore async with PixelleVideoCore() as pixelle: result = await pixelle.generate_video(text="如何养成阅读习惯", n_scenes=5)

另外，模块底部还导出了一个全局实例pixelle_video = PixelleVideoCore()（pixelle_video/service.py），可直接from pixelle_video import pixelle_video复用。

2.2 generate_video()：视频生成主方法

generate_video()是 SDK 的核心入口。它实际上是一个支持流水线选择的包装函数（见 pixelle_video/service.py），签名为generate_video(text, pipeline="standard", **kwargs)，最终把参数转发给对应流水线实例执行。

原文档列出的参数如下：

结合 api/schemas/video.py 与 pixelle_video/models/storyboard.py 的字段定义，实际可用的参数比文档更丰富，其中几个高频参数值得展开：

• ref_audio（str, optional）：参考音频路径，用于 TTS 音色克隆（voice cloning），仅在指定了对应 TTS 工作流时生效。
• prompt_prefix（str, optional）：图片风格前缀，会拼接到每张生成图片的提示词之前，用于统一全片视觉风格（如"极简黑白火柴人风格插画"）。
• min_narration_words/max_narration_words（int）：每条旁白的最小/最大字数，默认 5 / 20，约束 LLM 生成脚本的粒度。
• min_image_prompt_words/max_image_prompt_words（int）：每条图片提示词的最小/最大字数，默认 30 / 60。
• video_fps（int）：成片帧率，默认 30，取值范围 15–60。
• voice_id（str, optional）：旧版 TTS 音色 ID，源码中已标记为废弃（deprecated），建议改用tts_workflow。

返回值：VideoResult对象，包含video_path（视频文件绝对路径）、duration（时长，秒）等字段；REST 层正是据此构造下载 URL 与文件大小（见 api/routers/video.py）。

2.3 底层执行流程（StandardPipeline）

默认流水线standard定义于 pixelle_video/pipelines/standard.py，从类注释与源码可以还原其六步执行链：

1. setup_environment：创建隔离的任务目录（create_task_output_dir）并确定最终成片路径；
2. generate_content：mode="generate"时由 LLM 依据主题生成n_scenes条旁白；mode="fixed"时按行切分脚本（split_narration_script）；
3. 为每条旁白生成图片提示词（generate_image_prompts）；
4. 逐帧处理：TTS 生成音频 → 生成图片/视频素材 → 套用 HTML 模板合成带字幕的帧 → 生成该帧的视频片段；
5. 拼接全部片段（concat）；
6. 后期处理：可选叠加 BGM（bgm_path+bgm_volume），得到最终 mp4。

这解释了为什么frame_template是必填项：媒体宽高（media_width/media_height）需要从模板文件的 meta 标签中解析，模板路径中的尺寸目录（如1080x1920）直接决定输出视频分辨率。REST 端点在生成前会通过HTMLFrameGenerator.get_media_size()自动完成这一推断（见 api/routers/video.py）。

三、HTTP REST API 实战

3.1 启动 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 8000 --reload

启动后服务会输出横幅与地址信息。需要注意的几点：

• 应用默认挂载在/api前缀下（api_config.api_prefix = "/api"），健康检查端点GET /health无前缀；
• CORS 默认开启且允许所有来源（cors_origins = ["*"]），便于前端直接调用；
• 服务生命周期由 FastAPIlifespan管理：启动时初始化任务管理器，关闭时取消所有进行中的任务并释放 Pixelle-Video 资源（api/app.py）；
• 服务端默认任务并发上限为 5、已完成任务保留 24 小时后自动清理（每小时清理一次），这些参数定义于 api/config.py。

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

同步接口适用于成片小于 30 秒的短视频，请求会阻塞至视频生成完成。原文档示例：

{ "text": "Why you should develop a reading habit", "mode": "generate", "n_scenes": 5, "frame_template": "1080x1920/image_default.html", "template_params": { "accent_color": "#3498db", "background": "https://example.com/custom-bg.jpg" }, "title": "The Power of Reading" }

curl 调用示例：

curl -X POST http://localhost:8000/api/video/generate/sync \ -H "Content-Type: application/json" \ -d '{ "text": "Why you should develop a reading habit", "mode": "generate", "n_scenes": 5, "frame_template": "1080x1920/image_default.html", "template_params": {"accent_color": "#3498db"}, "title": "The Power of Reading" }'

响应示例（VideoGenerateResponse结构）：

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

字段语义（来自 api/schemas/video.py）：

• success/message：调用状态与提示；
• video_url：成片访问地址，由path_to_url()将输出目录下的文件路径转换为基于当前请求 host 的 URL（api/routers/video.py），因此换域名部署时该 URL 会自动跟随请求域名；
• duration：视频时长（秒）；
• file_size：文件大小（字节）。

注意：源码提示大视频在同步模式下可能超时，建议改用异步接口。

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

异步接口适用于大视频：请求立即返回任务 ID，后台协程继续执行生成。请求体与同步接口完全一致，响应结构（VideoGenerateAsyncResponse）：

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

其执行机制（api/routers/video.py）为：先通过task_manager.create_task()以 UUID 创建video_generation类型任务，再把生成协程交给task_manager.execute_task()在后台执行；执行成功后将video_url、duration、file_size写入任务结果。

3.4 查询任务状态：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 } }

任务状态机定义于 api/tasks/models.py：

任务对象还包含created_at/started_at/completed_at时间戳、request_params（原始请求参数）以及可选的progress（进度对象，含current/total/percentage/message），便于构建进度条（api/tasks/models.py）。

完整异步调用链（官方推荐的 4 步流程，见 api/app.py 的 Getting Started 描述）：

# 1. 健康检查 curl http://localhost:8000/health # 2. 提交异步任务 curl -X POST http://localhost:8000/api/video/generate/async \ -H "Content-Type: application/json" \ -d '{"text": "Why you should develop a reading habit", "mode": "generate", "n_scenes": 5, "frame_template": "1080x1920/image_default.html"}' # => {"success": true, "message": "Task created successfully", "task_id": "abc123"} # 3. 轮询任务状态 curl http://localhost:8000/api/tasks/abc123 # => {"task_id": "abc123", "status": "running", ...} # 4. status 变为 "completed" 后，从 result.video_url 下载成片

3.5 任务管理的扩展端点

除单任务查询外，任务路由还提供了两个配套端点（api/routers/tasks.py）：

• GET /api/tasks：任务列表，支持按status过滤、limit限制条数（默认 100，最大 1000），按创建时间倒序返回；
• DELETE /api/tasks/{task_id}：取消 pending/running 状态的任务，对已终态任务无效，成功返回{"success": true, "message": "Task {task_id} cancelled successfully"}。

任务数据当前保存在内存中（TaskManager的_tasks字典，源码注释说明未来可替换为 Redis 等持久化存储），因此服务重启后任务记录会清空。

四、请求参数总表与取值约束

综合原文档参数表与 api/schemas/video.py 的 Pydantic 校验规则，完整请求参数如下（REST 请求体与 SDK 关键字参数通用）：

说明：frame_template在 Schema 中标记为可选，但两个生成端点的源码都会在缺失时抛出ValueError("frame_template is required to determine media size")，因为媒体宽高必须从模板 meta 中解析；media_width/media_height不开放给调用方，由服务端自动推导。

模板可选用例可直接参考 templates/1080x1920（竖屏，如image_default.html、image_modern.html、video_default.html）、templates/1080x1080（方形，image_minimal_framed.html）与 templates/1920x1080（横屏，image_film.html、image_full.html）。

五、更多资源与交互式文档

• Swagger UI：http://localhost:8000/docs，可直接在线调试全部端点（POST /api/video/generate/sync、POST /api/video/generate/async、GET /api/tasks/{task_id}等）；
• ReDoc：http://localhost:8000/redoc，面向阅读的 API 文档；
• OpenAPI JSON：http://localhost:8000/openapi.json，可导入 Postman / Apifox 等工具生成客户端；
• 根路径GET /返回服务信息与全部 API 分组入口（llm / tts / image / content / video / tasks / files / resources / frame，见 api/app.py），其中frame路由提供模板参数发现能力（GET /api/templates/{template_path}/params），可用于查询某模板支持的自定义参数；
• 能力配置：LLM、ComfyUI、直接 API 提供商（OpenAI / DashScope / Ark / Kling）、默认模板与默认工作流的完整配置示例见 config.example.yaml；
• 中文文档：中文版 API 参考见 docs/zh/reference/api-overview.md。

六、小结

Pixelle-Video 的 API 设计强调"一套参数、双入口复用"：Python SDK 通过PixelleVideoCore.generate_video()提供进程内编程接口，REST API 则将其包装为同步/异步两套 HTTP 端点，配合任务状态轮询与内存任务管理，覆盖从几十秒短视频到长视频批量的全场景。接入时只需记住三个核心动作——初始化（SDK）或启动服务（REST）、提交生成请求、查询/获取结果，其余细节（场景拆分、旁白与图片提示词生成、逐帧合成、BGM 混音）均由底层StandardPipeline自动完成。

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