Pixelle-Video API 教程从第一个视频请求到异步任务追踪的完整调用指南【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-VideoPixelle-Video 是一款 AI 短视频引擎给它一段文本它还你一条成片。它后端FastAPI暴露的 HTTP 接口能把旁白 → 插画 → 配音 → 合成整条流水线拆开来独立编排不依赖 Web 界面也能跑通全部能力。下面从启动服务讲起串完一次完整的视频生成请求、异步任务追踪再补充各环节的独立能力和常见坑。一、先把 API 服务跑起来克隆仓库、装依赖、启动服务三步完成git clone https://gitcode.com/gh_mirrors/pi/Pixelle-Video cd Pixelle-Video uv sync uv run python api/app.py --host 0.0.0.0 --port 8000服务默认监听 8000 端口api/app.py 自带 Swagger 页面/docs所有业务接口都能在里面试。先用GET /health确认服务存活返回状态和版本号。业务接口统一挂在/api前缀下视频相关的实现在 api/routers/video.py。二、跑通第一个视频生成请求视频生成走POST /api/video/generate/sync请求体最少 4 个字段{ text: 为什么要养成阅读习惯, mode: generate, n_scenes: 5, frame_template: 1080x1920/image_default.html }几个关键点frame_template是硬要求视频分辨率由模板决定不传会直接报错。用GET /api/resources/templates可以先看看有哪些可选模板按 1080x1920、1920x1080、1080x1080 分组。mode二选一generate让 LLM 把文本拆成旁白并配插画fixed原样使用你的文本。n_scenes1–20默认 5只在generate模式生效。常用可选项title不传自动生成、tts_workflow指定配音工作流、bgm_path/bgm_volume默认 0.3、video_fps15–60默认 30、template_params模板自定义样式参数。字段说明默认值text源文本必填—modegenerate / fixedgeneraten_scenes场景数仅 generate 模式5frame_templateHTML 模板决定分辨率必填—template_params模板样式参数强调色、背景等无tts_workflow配音工作流 key配置文件默认bgm_path / bgm_volume背景音乐路径与音量— / 0.3video_fps帧率30请求成功后返回video_url、duration、file_size。video_url形如/api/files/xxx/final.mp4浏览器可直接播放下载。注意 api/routers/files.py 只开放output/、workflows/、templates/、bgm/等白名单目录路径要直接用接口返回值别自己拼。三、异步生成与任务状态的三种查法同步接口会阻塞到生成结束只适合 30 秒以内的短视频。更长的任务换成POST /api/video/generate/async请求体完全相同响应立刻返回task_id之后围绕它做三件事操作接口说明查单个任务GET /api/tasks/{task_id}返回状态、进度completed 后 result 里带 video_url查任务列表GET /api/tasks?statusrunninglimit100按状态过滤最多 1000 条取消任务DELETE /api/tasks/{task_id}取消 pending / running 中的任务状态流转为pending → running → completed / failed / cancelled。拿到completed后从 result 取video_url即可。建议几秒轮询一次单个任务并设超时别拿列表接口空转。四、拆着用内容、配音、图像、帧渲染不想要整条视频时流水线每个环节都能单独调用按场景对号入座场景接口传入返回把主题拆成旁白POST /api/content/narrationtext、n_scenes、min/max_words旁白列表旁白转画面提示词POST /api/content/image-promptnarrations、min/max_words图像提示词列表生成标题POST /api/content/titletext标题文本转语音POST /api/tts/synthesizetext、workflow、ref_audio声音克隆audio_path、duration单张图生成POST /api/image/generateprompt、width/height512–2048、workflowimage_path单帧预览渲染POST /api/frame/rendertemplate、title、text、imageframe_path 与尺寸查可用工作流GET /api/resources/workflows/tts、/workflows/media—工作流列表含请求里要传的 key查背景音乐GET /api/resources/bgm—BGM 文件列表一个容易卡住的点template_params能自定义模板样式但模板支持哪些参数看不见。先调GET /api/frame/template/params?template1080x1920/image_default.html返回参数名、类型text / number / color / bool和默认值再照着传不用盲试。五、常见坑与规避方法现象原因怎么办请求报 frame_template 相关错误该字段必填且用于推断分辨率先调/api/resources/templates选模板同步接口超时生成耗时过长连接断开换异步接口 轮询任务n_scenes 不生效处于 fixed 模式改用 generate 模式传 voice_id 收到告警参数已废弃改用 tts_workflow配 ref_audio 可声音克隆视频链接 404 / 403/api/files/仅服务白名单目录直接使用接口返回的 video_urltemplate_params 无效传了模板未声明的参数先用/api/frame/template/params确认支持项最后提醒一点API 本身没有内置鉴权生产部署要放在反向代理后面自行加访问控制仓库里的workflows/、templates/是默认资源想自定义时把文件放进data/templates/、data/bgm/接口会自动合并且自定义优先。【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考