JTJAI_Media/API_DOCUMENTATION.md

RTSP视频流管理系统 API 文档

基础信息

• 基础URL: http://localhost:8080
• 数据格式: JSON
• 编码: UTF-8

API 端点

1. 视频管理

1.1 列出所有视频

GET /api/videos

响应示例:

{
  "count": 10,
  "videos": [
    {
      "filename": "test_stream1.mp4",
      "full_path": "./output/20251011_082130/test_stream1.mp4",
      "timestamp_dir": "20251011_082130",
      "file_size": 787456,
      "created_time": "2025-10-11 08:21:45",
      "stream_index": "1"
    }
  ]
}

1.2 列出指定时间戳目录的视频

GET /api/videos/{timestamp}

路径参数:

• timestamp: 时间戳目录名，例如 20251011_082130

---

2. 时间戳目录管理

2.1 列出所有时间戳目录

GET /api/timestamps

响应示例:

{
  "count": 5,
  "timestamps": [
    {
      "timestamp": "20251011_082130",
      "video_count": 2,
      "total_size": 5748992
    }
  ]
}

2.2 删除时间戳目录

DELETE /api/timestamp/{timestamp}

路径参数:

• timestamp: 要删除的时间戳目录名

响应示例:

{
  "success": true,
  "path": "./output/20251011_082130",
  "message": "目录删除成功"
}

---

3. 轮询报告管理 🆕

3.1 列出所有轮询报告

GET /api/reports

响应示例:

{
  "count": 8,
  "reports": [
    {
      "timestamp": "20251011_082130",
      "has_report": true,
      "summary": {
        "total_streams": 2,
        "successful_streams": 2,
        "failed_streams": 0,
        "cancelled_streams": 0,
        "total_bytes": 0,
        "total_frames": 950,
        "success_rate": 1.0,
        "average_duration": 18.0,
        "earliest_start": "2025-10-11 08:21:30",
        "latest_end": "2025-10-11 08:21:50"
      },
      "generated_at": "2025-10-11 08:21:50"
    }
  ]
}

字段说明:

• total_streams: 总流数
• successful_streams: 成功拉取的流数量
• failed_streams: 失败的流数量
• cancelled_streams: 取消的流数量
• success_rate: 成功率 (0.0-1.0)
• total_frames: 总接收帧数
• average_duration: 平均持续时间（秒）

3.2 获取指定时间戳的轮询报告

GET /api/report/{timestamp}

路径参数:

• timestamp: 时间戳目录名

响应示例:

{
  "report_generated_at": "2025-10-11 08:21:50",
  "config": {
    "global_config": {
      "total_poll_duration_seconds": 60,
      "max_concurrent_streams": 2,
      "output_directory": "./output/20251011_082130"
    },
    "streams": [...]
  },
  "scheduler_stats": {
    "total_tasks": 2,
    "completed_tasks": 2,
    "failed_tasks": 0,
    "cancelled_tasks": 0
  },
  "streams": [
    {
      "stream_index": 1,
      "rtsp_url": "rtsp://example.com/stream1",
      "output_file": "./output/20251011_082130/test_stream2.mp4",
      "status": "完成",
      "start_time": "2025-10-11 08:21:30",
      "end_time": "2025-10-11 08:21:50",
      "bytes_received": 0,
      "frames_received": 549,
      "duration_seconds": 20,
      "error_message": "",
      "actual_duration_seconds": 20
    }
  ],
  "summary": {
    "total_streams": 2,
    "successful_streams": 2,
    "failed_streams": 0,
    "total_frames": 950,
    "success_rate": 1.0
  }
}

流状态说明:

• 完成: 流成功拉取
• 失败: 流拉取失败（会有error_message）
• 取消: 流被取消

---

4. 视频文件操作

4.1 删除视频文件

DELETE /api/video?path={path}

查询参数:

• path: 视频文件的完整路径

响应示例:

{
  "success": true,
  "path": "./output/20251011_082130/test_stream1.mp4",
  "message": "文件删除成功"
}

4.2 播放/下载视频

GET /videos/{timestamp}/{filename}

路径参数:

• timestamp: 时间戳目录名
• filename: 视频文件名

功能: 直接返回视频文件流，支持浏览器播放和下载

---

Web 界面

主页

GET /

系统主页，提供快速导航

视频管理界面

GET /manager

完整的视频和报告管理界面，包括：

• 时间戳目录浏览
• 所有视频列表
• 轮询报告查看 🆕
• 视频播放功能
• 文件删除功能

---

错误响应

所有错误响应遵循以下格式：

{
  "error": "错误类型",
  "message": "详细错误信息"
}

常见HTTP状态码:

• 200 OK: 请求成功
• 400 Bad Request: 请求参数错误
• 403 Forbidden: 权限不足
• 404 Not Found: 资源不存在
• 500 Internal Server Error: 服务器内部错误

---

使用示例

curl 示例

获取所有轮询报告

curl http://localhost:8080/api/reports

获取特定报告详情

curl http://localhost:8080/api/report/20251011_082130

删除视频文件

curl -X DELETE "http://localhost:8080/api/video?path=./output/20251011_082130/test_stream1.mp4"

JavaScript 示例

// 获取所有报告
async function loadReports() {
  const response = await fetch('http://localhost:8080/api/reports');
  const data = await response.json();
  console.log(`共有 ${data.count} 个报告`);
  return data.reports;
}

// 获取特定报告
async function getReport(timestamp) {
  const response = await fetch(`http://localhost:8080/api/report/${timestamp}`);
  const report = await response.json();
  return report;
}

---

注意事项

1. CORS支持: API支持跨域请求
2. 文件路径安全: 删除操作会检查文件路径，只能删除output目录下的文件
3. 视频播放: 支持HTTP Range请求，可以拖动播放进度
4. 轮询报告: 每次任务执行都会生成独立的JSON报告文件
5. 失败流展示: 报告中包含所有流的状态，包括失败和未拉取成功的流

更新日志

v1.1.0 (2025-10-11)

• ✨ 新增轮询报告API (/api/reports, /api/report/{timestamp})
• ✨ Web界面新增"轮询报告"选项卡
• ✨ 报告展示包含成功和失败的流信息
• 🔧 优化API文档和错误处理