API 概览¶

Pixelle-Video 提供 Python SDK 和 HTTP REST API 两种方式。

Python SDK¶

PixelleVideoCore¶

主要服务类，提供视频生成功能。

from pixelle_video.service import PixelleVideoCore

pixelle = PixelleVideoCore()
await pixelle.initialize()

generate_video()¶

生成视频的主要方法。

参数:

text (str): 主题或完整文案
mode (str): 生成模式 ("generate" 或 "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)

返回: VideoResult 对象

HTTP REST API¶

启动 API 服务器：

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

视频生成 - 同步¶

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
}

视频生成 - 异步¶

POST /api/video/generate/async

异步生成视频，立即返回任务 ID。适合大视频。

响应:

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

查询任务状态¶

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

请求参数说明¶

参数	类型	必填	说明
`text`	string	是	主题或完整文案
`mode`	string	否	`"generate"` (AI 生成) 或 `"fixed"` (固定文案)
`n_scenes`	int	否	分镜数量 (1-20)，仅 generate 模式有效
`title`	string	否	视频标题（不填则自动生成）
`frame_template`	string	否	模板路径，如 `1080x1920/image_default.html`
`template_params`	object	否	模板自定义参数（颜色、背景等）
`media_workflow`	string	否	媒体工作流（图像或视频生成）
`tts_workflow`	string	否	TTS 工作流
`ref_audio`	string	否	声音克隆参考音频路径
`prompt_prefix`	string	否	图像风格前缀
`bgm_path`	string	否	BGM 文件路径
`bgm_volume`	float	否	BGM 音量 (0.0-1.0，默认 0.3)