视频点播

2026年 5月 20日下午3:36

# VOD API 接口文档

## 概述

VOD (Video on Demand) API 提供视频点播任务管理功能，包括任务查询、文件上传、任务删除、播放等操作。

## 通用响应格式

所有接口返回 JSON 格式数据：

```json
{
  "code": 200,
  "data": {},
  "error": ""
}
```

- `code`: HTTP 状态码
- `data`: 响应数据
- `error`: 错误信息（成功时为空）

---

## 1. 获取 VOD 任务列表

获取所有 VOD 任务列表，支持状态过滤、搜索和分页。

**接口**: `GET /api/vod/tasks`

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 否 | 任务状态过滤（如: "completed", "processing"），默认为 "all" |
| search | string | 否 | 搜索关键词（匹配任务名称或ID） |
| page | int | 否 | 页码，默认为 1 |
| page_size | int | 否 | 每页数量，默认为 20，最大 100 |

**响应示例**:

```json
{
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "task-001",
        "name": "sample-video.mp4",
        "status": "completed",
        "source_path": "/vod/input/sample-video.mp4",
        "output_path": "/vod/output/task-001",
        "created_at": "2026-01-27T10:30:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_page": 5
  }
}
```

---

## 2. 获取单个 VOD 任务

根据任务 ID 获取单个 VOD 任务详情。

**接口**: `GET /api/vod/tasks/{id}`

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 任务 ID |

**响应示例**:

```json
{
  "code": 200,
  "data": {
    "id": "task-001",
    "name": "sample-video.mp4",
    "status": "completed",
    "source_path": "/vod/input/sample-video.mp4",
    "output_path": "/vod/output/task-001",
    "created_at": "2026-01-27T10:30:00Z"
  }
}
```

**错误响应**:

- `400 Bad Request`: 任务 ID 为空
- `404 Not Found`: 任务不存在
- `500 Internal Server Error`: 服务器错误

---

## 3. 上传 VOD 文件

上传视频文件到 VOD 观察目录，上传后会自动创建切片任务。

**接口**: `POST /api/vod/upload`

**请求格式**: `multipart/form-data`

**表单字段**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 视频文件 |

**支持的视频格式**:

- TS (`.ts`)
- MP4 (`.mp4`)
- FLV (`.flv`)
- MKV (`.mkv`)
- AVI (`.avi`)
- MOV (`.mov`)
- M4V (`.m4v`)

**限制**:
- 最大文件大小：5GB
- 需要配置 `VodWatchPath`

**响应示例**:

```json
{
  "code": 200,
  "data": "File uploaded successfully, slice task will be created automatically"
}
```

**错误响应**:

- `400 Bad Request`: 无文件上传、表单无效或文件格式不支持
- `500 Internal Server Error`: VodWatchPath 未配置或文件保存失败

---

## 4. 删除 VOD 任务

删除指定的 VOD 任务，包括任务记录和相关文件。

**接口**: `DELETE /api/vod/tasks/{id}`

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 任务 ID |

**删除行为**:
1. 删除任务的输出文件目录
2. 如果配置了 `VodAutoDelete`，同时删除源文件
3. 从数据库删除任务记录
4. 触发 `vodSliceDeleted` 事件

**响应示例**:

```json
{
  "code": 200,
  "data": "Task deleted successfully"
}
```

**错误响应**:

- `400 Bad Request`: 任务 ID 为空
- `404 Not Found`: 任务不存在
- `500 Internal Server Error`: 服务器错误

---

## 5. 获取 VOD 播放 URL

获取已完成任务的播放 URL。

**接口**: `GET /api/vod/tasks/{id}/play`

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 任务 ID |

**响应示例**:

```json
{
  "code": 200,
  "data": {
    "url": "/vod/task-001/index.m3u8"
  }
}
```

**错误响应**:

- `400 Bad Request`: 任务 ID 为空或任务未完成
- `404 Not Found`: 任务不存在
- `500 Internal Server Error`: 服务器错误

---

## 6. 删除 VOD 输出文件

删除指定任务的输出文件（HLS 切片等），保留任务记录和源文件。

**接口**: `DELETE /api/vod/tasks/{id}/files`

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 任务 ID |

**响应示例**:

```json
{
  "code": 200,
  "data": "Output files deleted successfully"
}
```

**错误响应**:

- `400 Bad Request`: 任务 ID 为空或任务无输出文件
- `404 Not Found`: 任务不存在
- `500 Internal Server Error`: 服务器错误

---

## 任务状态

| 状态 | 说明 |
|------|------|
| pending | 等待处理 |
| processing | 处理中 |
| completed | 已完成 |
| failed | 失败 |

## 配置要求

以下配置项需要在 `config.ini` 中设置：

- `VodWatchPath`: VOD 文件观察目录（必须）
- `VodAutoDelete`: 是否自动删除源文件（可选）