# 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) - 初始版本发布 - 支持视频上传、分析、总结和对比功能