视频剪辑和处理

2026-06-22 09:18:45 +08:00
parent 9bc48060dc
commit 7d4ac82334
34 changed files with 3319 additions and 839 deletions
@@ -167,7 +167,181 @@ curl -X POST http://localhost:8900/generate \

 ---

-## 错误响应
+## 5. 字幕叠加任务接口
+
+**服务地址**：`http://127.0.0.1:3010`
+
+### 5.1 创建字幕叠加任务
+
+**接口路径**：`POST /video/caption`
+
+**功能说明**：将背景视频、字幕、文字/图片元素、背景音频合成输出最终视频。异步执行，返回 taskId。
+
+**请求参数**（Content-Type: `application/json`）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| video_urls | string[] | **是** | 背景视频 URL 列表，多个会自动拼接 |
+| audio_url | string | 否 | 背景音频 URL（配音/BGM），原视频会被消音 |
+| subtitles | SubtitleSegment[] | 否 | 字幕时间线列表 |
+| subtitle_style | SubtitleStyle | 否 | 字幕样式配置 |
+| elements | CaptionElement[] | 否 | 文字/图片元素列表 |
+| callback_url | string | 否 | 任务完成回调地址 |
+
+**SubtitleSegment（字幕时间线片段）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| start | float | **是** | 开始时间（秒） |
+| end | float | **是** | 结束时间（秒） |
+| text | string | **是** | 字幕文本 |
+
+**SubtitleStyle（字幕样式）：**
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| fontSize | int | 否 | 28 | 字号（px） |
+| fontColor | string | 否 | `#FFFFFF` | 字体颜色（十六进制） |
+| bgColor | string | 否 | `#000000` | 字幕背景色，空=透明 |
+| bgOpacity | float | 否 | 0.6 | 背景透明度，0-1 |
+| x | string | 否 | `"center"` | 水平位置：`"left"`/`"center"`/`"right"` 或像素值如 `"100"` |
+| y | string | 否 | `"bottom"` | 垂直位置：`"top"`/`"center"`/`"bottom"`、像素值如 `"200"`、或 CSS 表达式如 `"calc(100% - 300px)"` |
+
+**CaptionElement（自定义元素）：**
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| type | string | **是** | - | 元素类型：`"text"` 或 `"image"` |
+| text | string | type=text时必填 | - | 文字内容 |
+| imageUrl | string | type=image时必填 | - | 图片下载 URL |
+| x | string | 否 | `"center"` | 水平位置：`"left"`/`"center"`/`"right"` 或像素值 |
+| y | string | 否 | `"center"` | 垂直位置：`"top"`/`"center"`/`"bottom"`、像素值、或 `calc()` |
+| fontSize | int | 否 | 36 | 字号（px，type=text有效） |
+| fontColor | string | 否 | `#FFFFFF` | 字体颜色 |
+| bgColor | string | 否 | 透明 | 背景色，如 `"#FFFF00"` |
+| bgOpacity | float | 否 | 1.0 | 背景透明度，0-1 |
+| width | int | 否 | 原图尺寸 | 图片显示宽度（px，type=image有效） |
+| height | int | 否 | 原图尺寸 | 图片显示高度（px，type=image有效） |
+| startTime | float | 否 | 0 | 开始显示时间（秒），0=立即显示 |
+| duration | float | 否 | 0 | 持续时长（秒），0=一直显示到结束 |
+| trackIndex | int | 否 | 1 | 层级（类似 z-index），越大越靠前 |
+| animation | string | 否 | 无 | 动画：`"fadeIn"`/`"slideUp"`/`"slideLeft"`/`"scaleIn"` |
+
+**请求示例：**
+```bash
+curl --location --request POST 'http://127.0.0.1:3010/video/caption' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "video_urls": [
+    "http://example.com/video1.mp4",
+    "http://example.com/video2.mp4"
+  ],
+  "audio_url": "http://example.com/audio.mp3",
+  "subtitles": [
+    {"start": 0.0, "end": 3.0, "text": "第一段字幕"},
+    {"start": 3.0, "end": 6.0, "text": "第二段字幕"}
+  ],
+  "subtitle_style": {
+    "fontSize": 36,
+    "fontColor": "#FFFF00",
+    "bgColor": "#000000",
+    "bgOpacity": 0.7,
+    "x": "center",
+    "y": "bottom"
+  },
+  "elements": [
+    {
+      "type": "text",
+      "text": "标题文字",
+      "x": "center",
+      "y": "60",
+      "fontSize": 48,
+      "fontColor": "#FF0000",
+      "startTime": 0,
+      "duration": 0,
+      "trackIndex": 5,
+      "animation": "fadeIn"
+    },
+    {
+      "type": "image",
+      "imageUrl": "http://example.com/logo.png",
+      "x": "right",
+      "y": "top",
+      "width": 100,
+      "height": 100,
+      "startTime": 0,
+      "duration": 0,
+      "trackIndex": 5
+    }
+  ],
+  "callback_url": "https://your-server.com/callback"
+}'
+```
+
+**返回参数：**
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| taskId | string | 任务 ID，用于后续查询结果 |
+
+**返回示例：**
+```json
+{
+  "taskId": "CAPTION_20260602123456_abc123"
+}
+```
+
+---
+
+### 5.2 查询字幕任务结果
+
+**接口路径**：`GET /video/caption/{taskId}`
+
+**功能说明**：根据 taskId 查询字幕叠加任务的状态和输出文件。
+
+**路径参数：**
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| taskId | string | **是** | 创建任务时返回的 taskId |
+
+**返回参数：**
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| taskId | string | 任务 ID |
+| status | string | 任务状态：`"running"`（处理中）/ `"completed"`（完成）/ `"failed"`（失败） |
+| fileUrl | string | 完成时返回：输出视频下载 URL |
+| fileSize | int64 | 完成时返回：输出文件大小（字节） |
+| fileName | string | 完成时返回：输出文件名 |
+| durationStr | string | 完成时返回：视频时长（如 "0:45"） |
+| errorMessage | string | 失败时返回：错误信息 |
+
+**返回示例（完成时）：**
+```json
+{
+  "taskId": "CAPTION_20260602123456_abc123",
+  "status": "completed",
+  "fileUrl": "http://127.0.0.1:3010/storage/output.mp4",
+  "fileSize": 5242880,
+  "fileName": "output.mp4",
+  "durationStr": "0:45"
+}
+```
+
+**返回示例（处理中）：**
+```json
+{
+  "taskId": "CAPTION_20260602123456_abc123",
+  "status": "running"
+}
+```
+
+**返回示例（失败）：**
+```json
+{
+  "taskId": "CAPTION_20260602123456_abc123",
+  "status": "failed",
+  "errorMessage": "视频下载失败"
+}
+```

 当请求失败时，接口返回 HTTP 错误码和错误信息：