尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

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

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-VideoPixelle-Video 是一套 AI 全自动短视频生成引擎它对外提供两种能力接入方式面向 Python 程序的 SDKPixelleVideoCore和面向任意客户端的 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 APIFastAPI 实现暴露/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 SDKPixelleVideoCore 与 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.pyllmLLMService负责文案生成、分镜脚本、图像提示词等文本能力ttsTTSService语音合成media/api_mediaMediaService与APIProviderMediaService图像/视频媒体生成frame_processorFrameProcessorHTML 模板帧渲染persistence/history输出落盘与历史记录pipelines注册三套视频生成流水线standard、custom、asset_based。值得注意的底层细节ComfyKit 实例负责与 ComfyUI/RunningHub 交互不在initialize()中创建而是首次使用时惰性创建并且会通过配置 MD5 哈希检测 ComfyUI 地址、API Key 等配置变化后自动重建pixelle_video/service.py这让你在长驻进程中修改配置也能热生效。初始化后即可直接使用各项能力官方 docstring 中给出的示范pixelle_video/service.pyfrom 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(prompta cat) print(fUsing LLM: {pixelle_video.llm.active}) print(fAvailable TTS: {pixelle_video.tts.available})PixelleVideoCore同时实现了异步上下文管理器__aenter__/__aexit__可用async with PixelleVideoCore() as pixelle:自动完成初始化和资源清理。generate_video() 参数与返回值文档列出的generate_video()核心参数参数类型说明textstr主题或完整文案modestr生成模式generateAI 生成或fixed固定文案n_scenesint分镜数量titlestr, optional视频标题tts_workflowstrTTS 工作流media_workflowstr媒体生成工作流图像或视频frame_templatestr视频模板template_paramsdict, optional模板自定义参数bgm_pathstr, optionalBGM 文件路径bgm_volumefloatBGM 音量0.0-1.0返回值VideoGenerationResult对象。其字段定义在 pixelle_video/models/storyboard.pydataclass class VideoGenerationResult: video_path: str # 最终视频文件路径 storyboard: Storyboard # 完整分镜数据 duration: float # 视频总时长秒 file_size: int # 文件大小字节 created_at: datetimestoryboard里还包含每个分镜的叙述文案、图像提示词、视频片段路径等中间产物方便做二次加工或调试pixelle_video/models/storyboard.py。管道选择pipelinegenerate_video实际是由_create_generate_video_wrapper()生成的包装函数额外支持pipeline参数pixelle_video/service.py# 默认 standard 管道 result await pixelle_video.generate_video(text如何提高学习效率, n_scenes5) # 指定 custom 管道 result await pixelle_video.generate_video( textyour_content, pipelinecustom, custom_param_examplecustom_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.pyuv run python api/app.py --host 0.0.0.0 --port 8080 --reloadFastAPI 应用在启动时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异步接口适合大视频提交后立即返回任务 IDapi/routers/video.py{ success: true, message: Task created successfully, task_id: abc123 }文档明确给出了异步模式的四步工作流提交视频生成请求从响应中拿到task_id轮询GET /api/tasks/{task_id}查看状态当状态为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、progresscurrent/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?statusrunninglimit100—— 按状态过滤、按创建时间倒序列出任务DELETE /api/tasks/{task_id}—— 取消 pending/running 任务终态任务不可取消自动清理默认每 3600 秒清理一次、保留 24 小时的已完成任务见 api/config.py。请求参数完整说明文档给出了 REST 请求参数总表结合 api/schemas/video.py 的 Pydantic 校验规则补充默认值与取值范围后如下参数类型必填默认值/范围说明textstring是—主题或完整文案modestring否generategenerateAI 生成或fixed固定文案n_scenesint否5范围 1-20分镜数量仅 generate 模式有效titlestring否自动生成视频标题frame_templatestring否—HTML 模板路径如1080x1920/image_default.html同时决定视频分辨率template_paramsobject否—模板自定义参数颜色、背景等media_workflowstring否—媒体工作流图像或视频生成tts_workflowstring否使用配置默认TTS 工作流如runninghub/tts_edge.jsonref_audiostring否—声音克隆参考音频路径voice_idstring否—已弃用旧版声音 ID建议改用tts_workflowmin_narration_wordsint否5范围 1-100分镜叙述最少字数max_narration_wordsint否20范围 1-200分镜叙述最多字数min_image_prompt_wordsint否30范围 10-100图像提示词最少字数max_image_prompt_wordsint否60范围 10-200图像提示词最多字数video_fpsint否30范围 15-60视频帧率prompt_prefixstring否—图像风格前缀bgm_pathstring否—BGM 文件路径bgm_volumefloat否0.3范围 0.0-1.0BGM 音量参数语义要点从源码确认text在modegenerate时是主题AI 会据此生成标题、分镜与叙述文案在modefixed时是完整文案直接进入后续处理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.html1080x1080/方形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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表