467 lines
8.9 KiB
Markdown
467 lines
8.9 KiB
Markdown
# Video Analysis API 文档
|
||
|
||
## 概述
|
||
|
||
Video Analysis API 提供视频上传、内容分析、总结生成和视频对比功能。所有 API 端点都遵循 RESTful 设计原则。
|
||
|
||
**Base URL**: `http://localhost:8080/api/videos`
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... },
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
## API 端点
|
||
|
||
### 1. 上传视频
|
||
|
||
上传视频文件到服务器。
|
||
|
||
**端点**: `POST /api/videos/upload`
|
||
|
||
**请求格式**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
- `file` (file, required): 视频文件
|
||
|
||
**支持的视频格式**: mp4, avi, mov, mkv, wmv, flv, webm
|
||
|
||
**文件大小限制**: 500MB
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"video_id": "507f1f77bcf86cd799439011",
|
||
"filename": "example.mp4",
|
||
"file_size": 10485760,
|
||
"status": "uploaded",
|
||
"upload_time": "2024-01-15T10:30:00.000Z"
|
||
},
|
||
"message": "Video uploaded successfully"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 文件格式不支持或文件大小超限
|
||
- `500`: 服务器内部错误
|
||
|
||
---
|
||
|
||
### 2. 获取视频列表
|
||
|
||
获取所有已上传的视频列表。
|
||
|
||
**端点**: `GET /api/videos`
|
||
|
||
**查询参数**:
|
||
- `limit` (integer, optional): 返回数量限制，默认 100
|
||
- `skip` (integer, optional): 跳过数量，默认 0
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "507f1f77bcf86cd799439011",
|
||
"filename": "example.mp4",
|
||
"file_size": 10485760,
|
||
"status": "analyzed",
|
||
"upload_time": "2024-01-15T10:30:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取视频详情
|
||
|
||
获取指定视频的详细信息，包括分析结果和总结。
|
||
|
||
**端点**: `GET /api/videos/{video_id}`
|
||
|
||
**路径参数**:
|
||
- `video_id` (string, required): 视频 ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439011",
|
||
"filename": "example.mp4",
|
||
"file_path": "/path/to/video.mp4",
|
||
"file_size": 10485760,
|
||
"mime_type": "video/mp4",
|
||
"status": "analyzed",
|
||
"upload_time": "2024-01-15T10:30:00.000Z",
|
||
"analysis": {
|
||
"id": "507f1f77bcf86cd799439012",
|
||
"content": "这段视频描绘了...",
|
||
"fps": 2,
|
||
"created_at": "2024-01-15T10:35:00.000Z"
|
||
},
|
||
"summary": {
|
||
"id": "507f1f77bcf86cd799439013",
|
||
"summary_text": "视频主要内容总结...",
|
||
"created_at": "2024-01-15T10:40:00.000Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `404`: 视频不存在
|
||
|
||
---
|
||
|
||
### 4. 分析视频内容
|
||
|
||
使用阿里云 DashScope API 分析视频内容。
|
||
|
||
**端点**: `POST /api/videos/{video_id}/analyze`
|
||
|
||
**路径参数**:
|
||
- `video_id` (string, required): 视频 ID
|
||
|
||
**请求体** (可选):
|
||
```json
|
||
{
|
||
"prompt": "自定义分析提示词"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439012",
|
||
"video_id": "507f1f77bcf86cd799439011",
|
||
"content": "这段视频描绘了...",
|
||
"fps": 2,
|
||
"created_at": "2024-01-15T10:35:00.000Z"
|
||
},
|
||
"message": "Video analyzed successfully"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 视频不存在或分析失败
|
||
- `404`: 视频不存在
|
||
|
||
**注意**: 分析过程可能需要较长时间，取决于视频长度。
|
||
|
||
---
|
||
|
||
### 5. 生成视频总结
|
||
|
||
为视频生成内容总结。
|
||
|
||
**端点**: `POST /api/videos/{video_id}/summarize`
|
||
|
||
**路径参数**:
|
||
- `video_id` (string, required): 视频 ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439013",
|
||
"video_id": "507f1f77bcf86cd799439011",
|
||
"summary_text": "这段视频主要讲述了...",
|
||
"created_at": "2024-01-15T10:40:00.000Z"
|
||
},
|
||
"message": "Summary generated successfully"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 视频不存在或总结生成失败
|
||
- `404`: 视频不存在
|
||
|
||
---
|
||
|
||
### 6. 获取视频总结
|
||
|
||
获取视频的总结内容。
|
||
|
||
**端点**: `GET /api/videos/{video_id}/summary`
|
||
|
||
**路径参数**:
|
||
- `video_id` (string, required): 视频 ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439013",
|
||
"video_id": "507f1f77bcf86cd799439011",
|
||
"summary_text": "这段视频主要讲述了...",
|
||
"created_at": "2024-01-15T10:40:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `404`: 总结不存在
|
||
|
||
---
|
||
|
||
### 7. 对比多个视频
|
||
|
||
对比多个视频的内容，找出相似之处和不同之处。
|
||
|
||
**端点**: `POST /api/videos/compare`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"video_ids": [
|
||
"507f1f77bcf86cd799439011",
|
||
"507f1f77bcf86cd799439014"
|
||
]
|
||
}
|
||
```
|
||
|
||
**请求参数**:
|
||
- `video_ids` (array, required): 视频 ID 数组，至少需要 2 个
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439015",
|
||
"video_ids": [
|
||
"507f1f77bcf86cd799439011",
|
||
"507f1f77bcf86cd799439014"
|
||
],
|
||
"comparison_result": "这两个视频的相似之处是...不同之处是...",
|
||
"created_at": "2024-01-15T11:00:00.000Z"
|
||
},
|
||
"message": "Comparison completed successfully"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 视频数量不足或对比失败
|
||
- `404`: 某个视频不存在
|
||
|
||
---
|
||
|
||
### 8. 获取对比结果
|
||
|
||
获取指定对比任务的结果。
|
||
|
||
**端点**: `GET /api/videos/compare/{comparison_id}`
|
||
|
||
**路径参数**:
|
||
- `comparison_id` (string, required): 对比任务 ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "507f1f77bcf86cd799439015",
|
||
"video_ids": [
|
||
"507f1f77bcf86cd799439011",
|
||
"507f1f77bcf86cd799439014"
|
||
],
|
||
"comparison_result": "这两个视频的相似之处是...不同之处是...",
|
||
"created_at": "2024-01-15T11:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `404`: 对比结果不存在
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
### 视频状态 (status)
|
||
- `uploaded`: 已上传，等待分析
|
||
- `analyzing`: 分析中
|
||
- `analyzed`: 已分析完成
|
||
- `failed`: 分析失败
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| HTTP 状态码 | 说明 |
|
||
|------------|------|
|
||
| 200 | 请求成功 |
|
||
| 201 | 创建成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### cURL 示例
|
||
|
||
#### 上传视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/upload \
|
||
-F "file=@/path/to/video.mp4"
|
||
```
|
||
|
||
#### 分析视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/507f1f77bcf86cd799439011/analyze \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
#### 生成总结
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/507f1f77bcf86cd799439011/summarize \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
#### 对比视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/compare \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"video_ids": [
|
||
"507f1f77bcf86cd799439011",
|
||
"507f1f77bcf86cd799439014"
|
||
]
|
||
}'
|
||
```
|
||
|
||
### Python 示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
# 上传视频
|
||
with open('video.mp4', 'rb') as f:
|
||
response = requests.post(
|
||
'http://localhost:8080/api/videos/upload',
|
||
files={'file': f}
|
||
)
|
||
video_data = response.json()
|
||
video_id = video_data['data']['video_id']
|
||
|
||
# 分析视频
|
||
response = requests.post(
|
||
f'http://localhost:8080/api/videos/{video_id}/analyze'
|
||
)
|
||
analysis = response.json()
|
||
|
||
# 生成总结
|
||
response = requests.post(
|
||
f'http://localhost:8080/api/videos/{video_id}/summarize'
|
||
)
|
||
summary = response.json()
|
||
|
||
# 对比视频
|
||
response = requests.post(
|
||
'http://localhost:8080/api/videos/compare',
|
||
json={
|
||
'video_ids': ['video_id_1', 'video_id_2']
|
||
}
|
||
)
|
||
comparison = response.json()
|
||
```
|
||
|
||
### JavaScript 示例
|
||
|
||
```javascript
|
||
// 上传视频
|
||
const formData = new FormData();
|
||
formData.append('file', fileInput.files[0]);
|
||
|
||
fetch('http://localhost:8080/api/videos/upload', {
|
||
method: 'POST',
|
||
body: formData
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
console.log('Uploaded:', data.data.video_id);
|
||
});
|
||
|
||
// 分析视频
|
||
fetch(`http://localhost:8080/api/videos/${videoId}/analyze`, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
}
|
||
})
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
console.log('Analysis:', data.data.content);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 配置要求
|
||
|
||
### 主要配置：config.yaml
|
||
|
||
所有配置主要在 `config.yaml` 文件中设置：
|
||
|
||
```yaml
|
||
dashscope:
|
||
api_key: "your-dashscope-api-key" # 必需
|
||
|
||
mongodb:
|
||
uri: "mongodb://localhost:27017"
|
||
database: "videoSummary"
|
||
|
||
server:
|
||
host: "0.0.0.0"
|
||
port: 8080
|
||
mode: "debug"
|
||
```
|
||
|
||
**注意**:
|
||
- 所有配置均在 `config.yaml` 文件中设置
|
||
- 请确保配置文件中的值正确
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **API Key 安全**: 请确保 DashScope API Key 在 `config.yaml` 中设置，不要将包含 API Key 的 `config.yaml` 提交到代码仓库
|
||
2. **文件大小**: 当前限制为 500MB，可在 `config.yaml` 中配置
|
||
3. **处理时间**: 视频分析和总结生成可能需要较长时间，取决于视频长度和 API 响应速度
|
||
4. **CORS**: API 已启用 CORS，支持跨域请求
|
||
5. **错误处理**: 所有 API 调用都应检查 `success` 字段并处理错误情况
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2024-01-15)
|
||
- 初始版本发布
|
||
- 支持视频上传、分析、总结和对比功能
|
||
|