JTJAI_Media/HTTP_API_DOC.md

RTSP视频流管理HTTP服务器 API文档

概述

这是一个用于管理RTSP视频流拉取结果的HTTP服务器，提供查询和删除视频文件的功能。

启动服务器

编译

cd /Users/wenhongquan/CLionProjects/jtjai_media
cmake --build cmake-build-debug --target jtjai_http_server

运行

# 使用默认参数（输出目录：./output，端口：8080）
./cmake-build-debug/jtjai_http_server

# 指定输出目录
./cmake-build-debug/jtjai_http_server ./output

# 指定输出目录和端口
./cmake-build-debug/jtjai_http_server ./output 8080

参数说明

• 参数1：输出目录路径（默认：./output）
• 参数2：监听端口（默认：8080）

API端点

1. 列出所有时间戳目录

请求

GET /api/timestamps

响应示例

{
  "count": 3,
  "timestamps": [
    {
      "timestamp": "20251010_163200",
      "video_count": 2,
      "total_size": 8385920
    },
    {
      "timestamp": "20251010_163100",
      "video_count": 2,
      "total_size": 8385920
    },
    {
      "timestamp": "20251010_163000",
      "video_count": 2,
      "total_size": 8385920
    }
  ]
}

字段说明

• count: 时间戳目录总数
• timestamp: 时间戳目录名称
• video_count: 该目录下的视频数量
• total_size: 该目录下所有视频的总大小（字节）

---

2. 列出所有视频

请求

GET /api/videos

响应示例

{
  "count": 6,
  "videos": [
    {
      "filename": "test_stream1.mp4",
      "full_path": "./output/20251010_163000/test_stream1.mp4",
      "timestamp_dir": "20251010_163000",
      "file_size": 1027405,
      "created_time": "2025-10-10 16:30:26",
      "stream_index": "1"
    },
    {
      "filename": "test_stream2.mp4",
      "full_path": "./output/20251010_163000/test_stream2.mp4",
      "timestamp_dir": "20251010_163000",
      "file_size": 7358515,
      "created_time": "2025-10-10 16:30:26",
      "stream_index": "2"
    }
  ]
}

字段说明

• filename: 文件名
• full_path: 完整路径
• timestamp_dir: 所属时间戳目录
• file_size: 文件大小（字节）
• created_time: 创建时间
• stream_index: 流索引（从文件名提取）

---

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

请求

GET /api/videos?timestamp=20251010_163000

或者

GET /api/videos/20251010_163000

响应示例

{
  "timestamp": "20251010_163000",
  "count": 2,
  "videos": [
    {
      "filename": "test_stream1.mp4",
      "full_path": "./output/20251010_163000/test_stream1.mp4",
      "timestamp_dir": "20251010_163000",
      "file_size": 1027405,
      "created_time": "2025-10-10 16:30:26",
      "stream_index": "1"
    }
  ]
}

---

4. 删除单个视频文件

请求

DELETE /api/video?path=./output/20251010_163000/test_stream1.mp4

响应示例（成功）

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

响应示例（失败）

{
  "success": false,
  "path": "./output/20251010_163000/test_stream1.mp4",
  "message": "文件删除失败"
}

安全限制

• 只能删除输出目录内的文件
• 尝试删除输出目录外的文件会返回403 Forbidden

---

5. 删除整个时间戳目录

请求

DELETE /api/timestamp/20251010_163000

响应示例（成功）

{
  "success": true,
  "timestamp": "20251010_163000",
  "path": "./output/20251010_163000",
  "message": "目录删除成功"
}

响应示例（失败）

{
  "success": false,
  "timestamp": "20251010_163000",
  "path": "./output/20251010_163000",
  "message": "目录删除失败"
}

注意

• 删除目录会删除该目录下的所有文件（包括视频、报告等）
• 此操作不可逆，请谨慎使用

---

错误响应

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

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

常见错误状态码

• 400 Bad Request: 请求参数错误
• 403 Forbidden: 无权访问或删除
• 404 Not Found: 请求的资源不存在
• 500 Internal Server Error: 服务器内部错误

---

使用示例

使用curl命令

列出所有时间戳目录

curl http://localhost:8080/api/timestamps

列出所有视频

curl http://localhost:8080/api/videos

列出指定时间戳的视频

curl http://localhost:8080/api/videos/20251010_163000

删除单个视频

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

删除整个时间戳目录

curl -X DELETE http://localhost:8080/api/timestamp/20251010_163000

使用JavaScript (浏览器)

// 列出所有视频
fetch('http://localhost:8080/api/videos')
  .then(response => response.json())
  .then(data => console.log(data));

// 删除视频
fetch('http://localhost:8080/api/video?path=./output/20251010_163000/test_stream1.mp4', {
  method: 'DELETE'
})
  .then(response => response.json())
  .then(data => console.log(data));

使用Python

import requests

# 列出所有视频
response = requests.get('http://localhost:8080/api/videos')
print(response.json())

# 删除视频
response = requests.delete('http://localhost:8080/api/video', 
                          params={'path': './output/20251010_163000/test_stream1.mp4'})
print(response.json())

---

CORS支持

服务器支持跨域请求（CORS），可以从任何域的网页中调用API。

---

注意事项

1. 安全性: 当前版本没有身份验证机制，请勿在公网环境中使用
2. 文件路径: 删除操作只能针对输出目录内的文件，防止误删系统文件
3. 并发: 服务器支持并发请求处理
4. 停止服务器: 按 Ctrl+C 可以优雅地停止服务器

---

目录结构

output/
├── 20251010_163000/        # 第1轮的输出
│   ├── test_stream1.mp4
│   ├── test_stream2.mp4
│   ├── rtsp_report.json
│   ├── report.txt
│   └── streams.csv
├── 20251010_163100/        # 第2轮的输出
│   ├── test_stream1.mp4
│   ├── test_stream2.mp4
│   ├── rtsp_report.json
│   ├── report.txt
│   └── streams.csv
└── 20251010_163200/        # 第3轮的输出
    ├── test_stream1.mp4
    ├── test_stream2.mp4
    ├── rtsp_report.json
    ├── report.txt
    └── streams.csv

服务器会扫描输出目录下所有的时间戳子目录，并提供统一的查询和管理接口。