diff --git a/docs/en/getting-started/configuration.md b/docs/en/getting-started/configuration.md index bf37a14..fffe0e9 100644 --- a/docs/en/getting-started/configuration.md +++ b/docs/en/getting-started/configuration.md @@ -24,25 +24,29 @@ LLM (Large Language Model) is used to generate video scripts. --- -## Image Configuration +## Image/Video Generation Configuration Two options available: -### Local Deployment (Recommended) +### Local Deployment Using local ComfyUI service: 1. Install and start ComfyUI 2. Enter ComfyUI URL (default `http://127.0.0.1:8188`) 3. Click "Test Connection" to verify +4. (Optional) Enter ComfyUI API Key (get from [Comfy Platform](https://platform.comfy.org/profile/api-keys)) -### Cloud Deployment +### Cloud Deployment (Recommended) -Using RunningHub cloud service: +Using RunningHub cloud service, no local GPU required: 1. Register for a RunningHub account 2. Obtain API Key 3. Enter API Key in configuration +4. Configure advanced options (optional): + - **Concurrent Limit**: Set number of simultaneous tasks (1-10, default 1 for regular members) + - **Instance Type**: Choose 24GB or 48GB VRAM machine (48GB for large video generation) --- diff --git a/docs/en/reference/api-overview.md b/docs/en/reference/api-overview.md index 057bb2a..abdc6b7 100644 --- a/docs/en/reference/api-overview.md +++ b/docs/en/reference/api-overview.md @@ -1,10 +1,10 @@ # API Overview -Pixelle-Video Python API reference documentation. +Pixelle-Video provides both Python SDK and HTTP REST API. --- -## Core Classes +## Python SDK ### PixelleVideoCore @@ -17,10 +17,6 @@ pixelle = PixelleVideoCore() await pixelle.initialize() ``` ---- - -## Main Methods - ### generate_video() Primary method for generating videos. @@ -32,21 +28,114 @@ Primary method for generating videos. - `n_scenes` (int): Number of scenes - `title` (str, optional): Video title - `tts_workflow` (str): TTS workflow -- `image_workflow` (str): Image generation workflow +- `media_workflow` (str): Media generation workflow (image or video) - `frame_template` (str): Video template +- `template_params` (dict, optional): Custom template parameters - `bgm_path` (str, optional): BGM file path +- `bgm_volume` (float): BGM volume (0.0-1.0) **Returns**: `VideoResult` object --- -## Examples +## HTTP REST API -Check the `examples/` directory for more examples. +Start the API server: + +```bash +uv run uvicorn api.app:app --host 0.0.0.0 --port 8000 +``` + +### Video Generation - Synchronous + +`POST /api/video/generate/sync` + +Generate video synchronously, waits until completion. Suitable for small videos (< 30 seconds). + +**Request Body**: + +```json +{ + "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" +} +``` + +**Response**: + +```json +{ + "success": true, + "message": "Success", + "video_url": "http://localhost:8000/api/files/xxx/final.mp4", + "duration": 45.5, + "file_size": 12345678 +} +``` + +### Video Generation - Asynchronous + +`POST /api/video/generate/async` + +Generate video asynchronously, returns task ID immediately. Suitable for large videos. + +**Response**: + +```json +{ + "success": true, + "message": "Task created successfully", + "task_id": "abc123" +} +``` + +### Query Task Status + +`GET /api/tasks/{task_id}` + +**Response**: + +```json +{ + "task_id": "abc123", + "status": "completed", + "result": { + "video_url": "http://localhost:8000/api/files/xxx/final.mp4", + "duration": 45.5, + "file_size": 12345678 + } +} +``` + +--- + +## Request Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `text` | string | Yes | Topic or complete script | +| `mode` | string | No | `"generate"` (AI generates) or `"fixed"` (use text as-is) | +| `n_scenes` | int | No | Number of scenes (1-20), only used in generate mode | +| `title` | string | No | Video title (auto-generated if not provided) | +| `frame_template` | string | No | Template path, e.g., `1080x1920/image_default.html` | +| `template_params` | object | No | Custom template parameters (colors, backgrounds, etc.) | +| `media_workflow` | string | No | Media workflow (image or video generation) | +| `tts_workflow` | string | No | TTS workflow | +| `ref_audio` | string | No | Reference audio path for voice cloning | +| `prompt_prefix` | string | No | Image style prefix | +| `bgm_path` | string | No | BGM file path | +| `bgm_volume` | float | No | BGM volume (0.0-1.0, default 0.3) | --- ## More Information -Detailed API documentation coming soon. +API documentation is also available via Swagger UI: `http://localhost:8000/docs` diff --git a/docs/en/reference/config-schema.md b/docs/en/reference/config-schema.md index 60767dd..b822a80 100644 --- a/docs/en/reference/config-schema.md +++ b/docs/en/reference/config-schema.md @@ -8,14 +8,16 @@ Detailed explanation of the `config.yaml` configuration file. ```yaml llm: - provider: openai api_key: "your-api-key" base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" model: "qwen-plus" comfyui: comfyui_url: "http://127.0.0.1:8188" + comfyui_api_key: "" # ComfyUI API key (optional) runninghub_api_key: "" + runninghub_concurrent_limit: 1 # Concurrent limit (1-10) + runninghub_instance_type: "" # Instance type (optional, set to "plus" for 48GB VRAM) image: default_workflow: "runninghub/image_flux.json" @@ -27,15 +29,17 @@ comfyui: tts: default_workflow: "selfhost/tts_edge.json" + +template: + default_template: "1080x1920/image_default.html" ``` --- ## LLM Configuration -- `provider`: Provider (currently only supports openai-compatible interfaces) - `api_key`: API key -- `base_url`: API service address +- `base_url`: API service address (supports any OpenAI-compatible interface) - `model`: Model name --- @@ -44,8 +48,16 @@ comfyui: ### Basic Configuration -- `comfyui_url`: Local ComfyUI address -- `runninghub_api_key`: RunningHub API key (optional) +- `comfyui_url`: Local ComfyUI address (default `http://127.0.0.1:8188`) +- `comfyui_api_key`: ComfyUI API key (optional, for [Comfy Platform](https://platform.comfy.org/profile/api-keys)) + +### RunningHub Cloud Configuration + +- `runninghub_api_key`: RunningHub API key (required for cloud workflows) +- `runninghub_concurrent_limit`: Concurrent execution limit (1-10, default 1 for regular members) +- `runninghub_instance_type`: Instance type (optional) + - Empty or unset: Use 24GB VRAM machine + - `"plus"`: Use 48GB VRAM machine (suitable for large video generation) ### Image Configuration @@ -65,6 +77,12 @@ comfyui: --- +## Template Configuration + +- `default_template`: Default frame template path (e.g., `1080x1920/image_default.html`) + +--- + ## More Information The configuration file is automatically created on first run. diff --git a/docs/en/user-guide/web-ui.md b/docs/en/user-guide/web-ui.md index 76846af..844fcf9 100644 --- a/docs/en/user-guide/web-ui.md +++ b/docs/en/user-guide/web-ui.md @@ -11,6 +11,7 @@ The Web interface uses a three-column layout: - **Left Panel**: Content input and audio settings - **Middle Panel**: Voice and visual settings - **Right Panel**: Video generation and preview +- **Sidebar**: System configuration and FAQ --- @@ -27,6 +28,14 @@ First-time use requires configuring LLM and image generation services. See [Conf - **AI Generate Content**: Enter a topic, AI creates script automatically - **Fixed Script Content**: Enter complete script directly +### Fixed Script Split Mode + +When using fixed script mode, you can choose how to split the content: + +- **By Paragraph**: Split by empty lines, each paragraph becomes a scene +- **By Line**: Split by line breaks, each line becomes a scene +- **By Sentence**: Smart sentence boundary detection, each sentence becomes a scene + ### Background Music - Built-in music supported @@ -50,17 +59,19 @@ First-time use requires configuring LLM and image generation services. See [Conf ## Visual Settings -### Image Generation +### Image/Video Generation -- Select image generation workflow -- Set image dimensions +- Select media generation workflow (image or video) - Adjust prompt prefix to control style ### Video Template -- Choose video template -- Supports portrait/landscape/square -- Preview template effects +- **Template Preview Gallery**: Visually preview all available templates +- Supports portrait (1080x1920) / landscape (1920x1080) / square (1080x1080) +- Template types: + - `static_*.html`: Static templates (no AI-generated media) + - `image_*.html`: Image templates (requires AI-generated images) + - `video_*.html`: Video templates (requires AI-generated videos) --- @@ -69,9 +80,19 @@ First-time use requires configuring LLM and image generation services. See [Conf After clicking "Generate Video", the system will: 1. Generate video script -2. Generate images for each scene +2. Generate images/videos for each scene 3. Synthesize voice narration 4. Compose final video Automatically previews when complete. +--- + +## FAQ + +The sidebar includes built-in FAQ for quick reference: + +- Common configuration issues +- Generation failure solutions +- Performance optimization tips + diff --git a/docs/zh/getting-started/configuration.md b/docs/zh/getting-started/configuration.md index 76a4875..6f872e5 100644 --- a/docs/zh/getting-started/configuration.md +++ b/docs/zh/getting-started/configuration.md @@ -24,25 +24,29 @@ LLM(大语言模型)用于生成视频文案。 --- -## 图像配置 +## 图像/视频生成配置 支持两种方式: -### 本地部署(推荐) +### 本地部署 使用本地 ComfyUI 服务: 1. 安装并启动 ComfyUI 2. 填写 ComfyUI URL(默认 `http://127.0.0.1:8188`) 3. 点击「测试连接」确认服务可用 +4. (可选)填写 ComfyUI API Key(从 [Comfy Platform](https://platform.comfy.org/profile/api-keys) 获取) -### 云端部署 +### 云端部署(推荐) -使用 RunningHub 云端服务: +使用 RunningHub 云端服务,无需本地 GPU: 1. 注册 RunningHub 账号 2. 获取 API Key 3. 在配置中填写 API Key +4. 配置高级选项(可选): + - **并发限制**: 设置同时执行的任务数(1-10,普通会员默认为 1) + - **实例类型**: 选择 24GB 或 48GB 显存机器(48GB 适合大尺寸视频生成) --- diff --git a/docs/zh/reference/api-overview.md b/docs/zh/reference/api-overview.md index 2939719..bcdd467 100644 --- a/docs/zh/reference/api-overview.md +++ b/docs/zh/reference/api-overview.md @@ -1,10 +1,10 @@ # API 概览 -Pixelle-Video Python API 参考文档。 +Pixelle-Video 提供 Python SDK 和 HTTP REST API 两种方式。 --- -## 核心类 +## Python SDK ### PixelleVideoCore @@ -17,10 +17,6 @@ pixelle = PixelleVideoCore() await pixelle.initialize() ``` ---- - -## 主要方法 - ### generate_video() 生成视频的主要方法。 @@ -32,21 +28,114 @@ await pixelle.initialize() - `n_scenes` (int): 分镜数量 - `title` (str, optional): 视频标题 - `tts_workflow` (str): TTS 工作流 -- `image_workflow` (str): 图像生成工作流 +- `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 -查看 `examples/` 目录获取更多示例。 +启动 API 服务器: + +```bash +uv run uvicorn api.app:app --host 0.0.0.0 --port 8000 +``` + +### 视频生成 - 同步 + +`POST /api/video/generate/sync` + +同步生成视频,等待完成后返回结果。适合小视频(< 30 秒)。 + +**请求体**: + +```json +{ + "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": "阅读的力量" +} +``` + +**响应**: + +```json +{ + "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。适合大视频。 + +**响应**: + +```json +{ + "success": true, + "message": "Task created successfully", + "task_id": "abc123" +} +``` + +### 查询任务状态 + +`GET /api/tasks/{task_id}` + +**响应**: + +```json +{ + "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) | --- ## 更多信息 -详细的 API 文档即将推出。 +API 文档也可通过 Swagger UI 访问:`http://localhost:8000/docs` diff --git a/docs/zh/reference/config-schema.md b/docs/zh/reference/config-schema.md index fb6c8f5..0b93d73 100644 --- a/docs/zh/reference/config-schema.md +++ b/docs/zh/reference/config-schema.md @@ -8,14 +8,16 @@ ```yaml llm: - provider: openai api_key: "your-api-key" base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" model: "qwen-plus" comfyui: comfyui_url: "http://127.0.0.1:8188" + comfyui_api_key: "" # ComfyUI API 密钥(可选) runninghub_api_key: "" + runninghub_concurrent_limit: 1 # 并发限制 (1-10) + runninghub_instance_type: "" # 实例类型(可选,设为 "plus" 使用 48GB 显存) image: default_workflow: "runninghub/image_flux.json" @@ -27,15 +29,17 @@ comfyui: tts: default_workflow: "selfhost/tts_edge.json" + +template: + default_template: "1080x1920/image_default.html" ``` --- ## LLM 配置 -- `provider`: 提供商(目前仅支持 openai 兼容接口) - `api_key`: API 密钥 -- `base_url`: API 服务地址 +- `base_url`: API 服务地址(支持任何 OpenAI 兼容接口) - `model`: 模型名称 --- @@ -44,8 +48,16 @@ comfyui: ### 基础配置 -- `comfyui_url`: 本地 ComfyUI 地址 -- `runninghub_api_key`: RunningHub API 密钥(可选) +- `comfyui_url`: 本地 ComfyUI 地址(默认 `http://127.0.0.1:8188`) +- `comfyui_api_key`: ComfyUI API 密钥(可选,用于 [Comfy Platform](https://platform.comfy.org/profile/api-keys)) + +### RunningHub 云端配置 + +- `runninghub_api_key`: RunningHub API 密钥(使用云端工作流时必填) +- `runninghub_concurrent_limit`: 并发执行限制(1-10,普通会员默认为 1) +- `runninghub_instance_type`: 实例类型(可选) + - 留空或不设置:使用 24GB 显存机器 + - `"plus"`: 使用 48GB 显存机器(适合大尺寸视频生成) ### 图像配置 @@ -65,6 +77,12 @@ comfyui: --- +## 模板配置 + +- `default_template`: 默认帧模板路径(例如 `1080x1920/image_default.html`) + +--- + ## 更多信息 配置文件会自动在首次运行时创建。 diff --git a/docs/zh/user-guide/web-ui.md b/docs/zh/user-guide/web-ui.md index a0cad90..a23ad9d 100644 --- a/docs/zh/user-guide/web-ui.md +++ b/docs/zh/user-guide/web-ui.md @@ -11,6 +11,7 @@ Web 界面采用三栏布局: - **左侧栏**: 内容输入与音频设置 - **中间栏**: 语音与视觉设置 - **右侧栏**: 视频生成与预览 +- **侧边栏**: 系统配置与 FAQ --- @@ -27,6 +28,14 @@ Web 界面采用三栏布局: - **AI 生成内容**: 输入主题,AI 自动创作文案 - **固定文案内容**: 直接输入完整文案 +### 固定文案分割方式 + +使用固定文案模式时,可选择文案的分割方式: + +- **按段落分割**: 以空行为分隔符,每个段落作为一个分镜 +- **按行分割**: 以换行符为分隔符,每行作为一个分镜 +- **按句子分割**: 智能识别句子边界,每句话作为一个分镜 + ### 背景音乐 - 支持内置音乐 @@ -50,17 +59,19 @@ Web 界面采用三栏布局: ## 视觉设置 -### 图像生成 +### 图像/视频生成 -- 选择图像生成工作流 -- 设置图像尺寸 +- 选择媒体生成工作流(图像或视频) - 调整提示词前缀控制风格 ### 视频模板 -- 选择视频模板 -- 支持竖屏/横屏/方形 -- 可预览模板效果 +- **模板预览画廊**: 可视化预览所有可用模板 +- 支持竖屏 (1080x1920) / 横屏 (1920x1080) / 方形 (1080x1080) +- 模板类型: + - `static_*.html`: 静态模板(无 AI 生成媒体) + - `image_*.html`: 图像模板(需要 AI 生成图像) + - `video_*.html`: 视频模板(需要 AI 生成视频) --- @@ -69,9 +80,19 @@ Web 界面采用三栏布局: 点击「生成视频」按钮后,系统会: 1. 生成视频文案 -2. 为每个分镜生成配图 +2. 为每个分镜生成配图/视频 3. 合成语音解说 4. 合成最终视频 生成完成后自动预览。 +--- + +## FAQ + +侧边栏内置了常见问题解答(FAQ),点击可快速查看: + +- 常见配置问题 +- 生成失败解决方案 +- 性能优化建议 +