videoSummary/API.md

Video Analysis API 文档

概述

Video Analysis API 提供视频上传、内容分析、总结生成和视频对比功能。所有 API 端点都遵循 RESTful 设计原则。

Base URL: http://localhost:8080/api/videos

通用响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "message": "错误信息"
}

API 端点

1. 上传视频

上传视频文件到服务器。

端点: POST /api/videos/upload

请求格式: multipart/form-data

请求参数:

• file (file, required): 视频文件

支持的视频格式: mp4, avi, mov, mkv, wmv, flv, webm

文件大小限制: 500MB

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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

请求体 (可选):

{
  "prompt": "自定义分析提示词"
}

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "video_id": "507f1f77bcf86cd799439011",
    "summary_text": "这段视频主要讲述了...",
    "created_at": "2024-01-15T10:40:00.000Z"
  }
}

错误响应:

• 404: 总结不存在

---

7. 对比多个视频

对比多个视频的内容，找出相似之处和不同之处。

端点: POST /api/videos/compare

请求体:

{
  "video_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439014"
  ]
}

请求参数:

• video_ids (array, required): 视频 ID 数组，至少需要 2 个

响应示例:

{
  "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

响应示例:

{
  "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 示例

上传视频

curl -X POST http://localhost:8080/api/videos/upload \
  -F "file=@/path/to/video.mp4"

分析视频

curl -X POST http://localhost:8080/api/videos/507f1f77bcf86cd799439011/analyze \
  -H "Content-Type: application/json"

生成总结

curl -X POST http://localhost:8080/api/videos/507f1f77bcf86cd799439011/summarize \
  -H "Content-Type: application/json"

对比视频

curl -X POST http://localhost:8080/api/videos/compare \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439014"
    ]
  }'

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 示例

// 上传视频
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 文件中设置：

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)

• 初始版本发布
• 支持视频上传、分析、总结和对比功能