企业官网建设流程全解析

Pixelle-Video API 使用指南：Python SDK 与 HTTP REST API 双通道视频生成实战

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

本文围绕 Pixelle-Video 的 API 使用方式展开，系统讲解其 Python SDK（PixelleVideoCore）与 HTTP REST API（FastAPI 服务）两条视频生成通道的调用方法、核心参数与底层实现原理。读完本文，你将能够独立完成 SDK 初始化、同步/异步视频生成、任务状态轮询、结果文件获取，以及基于 Swagger UI 的接口调试，并理解请求参数在源码层面的校验规则与执行流程。

一、API 双入口：先建立整体认知

Pixelle-Video 是一个 AI 全自动短视频引擎，将 LLM 文案生成、TTS 配音、图像/视频生成、帧模板渲染与 BGM 合成封装为一条完整流水线。对外暴露的两类编程接口分工明确：

• Python SDK：面向 Python 项目内嵌集成的首选。核心类是 PixelleVideoCore，提供initialize()、generate_video()、cleanup()等异步方法，并统一托管 LLM、TTS、Media、Video 等全部底层服务。
• HTTP REST API：面向跨语言调用、服务化部署与 Web 前端。基于 FastAPI 实现，入口为 api/app.py，提供视频生成（同步/异步）、任务管理、文件访问、健康检查等一系列端点。

两条通道最终都汇聚到同一个视频生成管线（standard / custom / asset_based），因此请求参数语义完全一致，可以按场景自由切换。从 api/app.py 可以看到，所有业务路由统一挂在/api前缀之下，涵盖llm、tts、image、content、video、tasks、files、resources、frame共 9 个模块。

二、Python SDK：从初始化到生成视频

2.1 快速开始

SDK 的使用非常直接，官方文档给出了最小可用示例：

from pixelle_video.service import PixelleVideoCore import asyncio async def main(): # Initialize pixelle = PixelleVideoCore() await pixelle.initialize() # Generate video result = await pixelle.generate_video( text="Why develop a reading habit", mode="generate", n_scenes=5 ) print(f"Video generated: {result.video_path") # Run asyncio.run(main())

这段代码完成了三件事：创建核心服务实例、初始化全部能力、生成 5 个场景的短视频。注意generate_video是异步方法，因此外层需要asyncio.run()驱动。

2.2 初始化背后发生了什么

initialize()并非简单的空操作，从 pixelle_video/service.py 的实现看，它会依次完成：

1. 初始化核心服务：LLMService、TTSService、APIProviderMediaService、MediaService、ImageAnalysisService、VideoAnalysisService、VideoService、FrameProcessor、PersistenceService与HistoryManager；
2. 注册三条视频生成管线：standard（标准流程）、custom（自定义工作流模板）、asset_based（素材库驱动流程）；
3. 将默认的generate_video包装为支持pipeline参数的分发函数，保持向后兼容。

值得说明的是，ComfyKit（与 ComfyUI/RunningHub 交互的客户端）采用懒加载策略，并不会在initialize()时创建，而是在首次使用时按当前配置生成，并通过 MD5 配置哈希检测配置变更后自动重建实例（见 service.py）。这意味着修改 ComfyUI 地址、API Key 等配置后无需重启进程即可热生效。

2.3 资源释放与上下文管理器

PixelleVideoCore实现了异步上下文管理器协议（__aenter__/__aexit__），推荐写法：

from pixelle_video.service import PixelleVideoCore async def main(): async with PixelleVideoCore() as pixelle: result = await pixelle.generate_video(text="Hello", mode="generate") print(result.video_path)

进入上下文时自动initialize()，退出时自动调用cleanup()关闭 ComfyKit 会话，避免资源泄漏（见 service.py）。

三、generate_video() 核心方法全参数解析

generate_video()是 SDK 的主方法，参数语义与 HTTP API 的请求体一一对应。综合 API 参考文档 与 api/schemas/video.py 中的 Pydantic 字段约束，完整参数表如下：

两点关键说明：

• mode语义：generate模式会先让 LLM 根据text主题生成分镜脚本与旁白；fixed模式则把传入文本直接当作成稿使用，此时n_scenes等生成参数被忽略（见 video.py）。
• frame_template是分辨率来源：服务端不会单独接收宽高参数，而是通过HTMLFrameGenerator读取模板 HTML 的 meta 标签自动推导media_width/media_height（见 api/routers/video.py）。仓库内置了1080x1920、1920x1080、1080x1080三档尺寸的模板目录，可参考 templates。

generate_video()返回VideoResult对象，至少包含video_path（成品视频绝对/相对路径）与duration（时长，秒）。

四、HTTP REST API：启动与端点详解

4.1 启动 API 服务器

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

也可以直接运行入口脚本，并支持--host、--port、--reload参数：

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

服务启动后默认监听8000端口，同时提供三份交互式接口文档：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc
• OpenAPI JSON：http://localhost:8000/openapi.json

所有文档地址、/api前缀、CORS 策略与任务清理周期均可在 api/config.py 中调整（默认 CORS 全开、任务结果保留 24 小时）。

4.2 健康检查

curl http://localhost:8000/health

返回服务状态与版本信息：

{ "status": "healthy", "version": "0.1.0", "service": "Pixelle-Video API" }

/version端点返回相同结构（见 api/routers/health.py）。

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

该端点会阻塞等待视频生成完成，适合小于 30 秒的短视频；大视频建议改用异步接口以免请求超时。

请求体示例（来自 API 参考文档）：

{ "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" }

响应体：

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

其中video_url由服务端根据请求的base_url动态拼接（支持域名访问），file_size为字节数，duration为秒数。源码实现在 api/routers/video.py：先校验frame_template并从模板推导分辨率，然后组装参数调用generate_video()，最后将输出目录下的绝对路径转换为/api/files/{相对路径}形式的可访问 URL（path_to_url函数同时兼容 Windows 与 Linux 路径分隔符）。

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

异步接口立即返回task_id，生成过程在后台执行，适合大型视频：

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

异步调用的请求体与同步接口完全一致。后台执行由 api/tasks/manager.py 中的TaskManager驱动：create_task()生成 UUID 任务并登记为pending，execute_task()以asyncio协程方式运行生成逻辑，完成后将结果写入任务对象并标记completed，失败则记录error并标记failed。

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

任务状态机共五态：pending（排队中）→running（执行中）→completed（完成）/failed（失败）/cancelled（取消），定义见 api/tasks/models.py。任务对象还携带progress（进度百分比）、request_params（原始请求参数）与各类时间戳。

此外 api/routers/tasks.py 还提供两个配套端点：

• GET /api/tasks?status=running&limit=100：按状态过滤任务列表（默认按创建时间倒序，limit 上限 1000）；
• DELETE /api/tasks/{task_id}：取消进行中的任务。

需要注意：任务数据默认保存在进程内存中（源码注释说明后续可替换为 Redis 方案），且已完成/失败/取消的任务会在 24 小时后被后台清理循环自动回收（见 api/config.py），因此长期依赖任务结果的场景应尽快下载视频文件。

4.6 文件访问：GET /api/files/{file_path}

生成结果与素材统一通过 api/routers/files.py 暴露，仅允许访问以下白名单目录：

访问时不带前缀会默认回退到output/目录查找；接口按扩展名自动识别媒体类型（mp4/mp3/png/jpg/html/json 等），并以inline方式支持浏览器直接预览。

五、完整调用实战：异步生成 + 轮询 + 下载

把前面各端点串起来，一次典型的 HTTP 调用链路如下：

# 1. 提交异步生成任务 curl -X POST http://localhost:8000/api/video/generate/async \ -H "Content-Type: application/json" \ -d '{ "text": "Atomic Habits teaches us that small changes compound over time.", "mode": "generate", "n_scenes": 5, "frame_template": "1080x1920/image_default.html", "template_params": {"accent_color": "#3498db"}, "bgm_volume": 0.3 }' # 2. 轮询任务状态（直到 status == "completed"） curl http://localhost:8000/api/tasks/abc123 # 3. 下载成品视频（video_url 即文件访问地址） curl -o final.mp4 "http://localhost:8000/api/files/xxx/final.mp4"

若任务量不大且视频较短，直接使用同步端点POST /api/video/generate/sync一次请求即可拿回结果。两种方式生成的视频文件都落在output/目录下，按任务时间戳组织子目录。

六、进阶实践与注意事项

6.1 自定义模板参数

template_params的内容由所选 HTML 模板决定（如强调色、背景图等），不同模板支持的参数不同。仓库内置模板集中在 templates 目录，例如1080x1920/image_default.html、1080x1920/image_book.html、1920x1080/image_full.html等，可先阅读模板源码确认可用占位符。

6.2 声音克隆与风格控制

• 传入ref_audio即可基于参考音频做声音克隆（需对应 TTS 工作流支持）；
• 传入prompt_prefix可统一约束生成图像的风格，例如指定“电影感”“插画风”等前缀；
• tts_workflow支持切换不同 TTS 引擎，内置工作流见 workflows/runninghub（如tts_edge.json、tts_spark.json）与 workflows/selfhost。

6.3 旧参数兼容

voice_id参数已被标记为deprecated，源码中会输出弃用警告并建议改用tts_workflow（见 api/routers/video.py），新项目应避免使用。

6.4 适用前提

• 视频生成依赖外部 AI 服务（LLM、TTS、图像/视频生成），需在config.yaml中正确配置相应 API Key 与 ComfyUI/RunningHub 地址（参考 config.example.yaml）；
• 异步任务为内存态，进程重启后任务记录丢失；
• 同步接口对超长视频存在请求超时风险，官方建议大视频一律走异步链路。

七、延伸阅读

• API 概览（含完整参数表与响应结构）
• Web UI 使用指南
• 工作流使用指南
• 配置详解
• 架构说明（服务层与管线设计）

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