AI视频分析API常见问题和排查清单

1. 环境假设

摄像头/视频源：支持 RTSP/GB28181 协议的标准网络摄像机（1080P/4K，H.264/H.265 编码，15--25fps）。
平台版本：AI 视频分析平台 v3.5+（启用 OpenAPI 开放网关组件）。
网络环境：第三方业务服务器与 AI 平台服务器处于同局域网，或通过 VPN/专网互联，具备基础的 HTTP/HTTPS 通信能力。
通信协议：RESTful API (HTTP/HTTPS)、Webhook/WebSocket（告警回调）、RTSP/GB28181（视频流）。
操作系统与工具 ：Ubuntu 20.04/22.04 LTS 或 CentOS 7.9；调试工具包括 cURL、Postman、tcpdump、netstat/ss、ffmpeg。

2. 接入原理

AI 视频分析平台与第三方系统的 API 协同流转逻辑如下：

视频源 (IPC/NVR) ➔ (RTSP/GB28181 推流) ➔ AI视频分析平台 (流媒体服务) ➔ (视频解码与抽帧) ➔ 算法服务 (推理引擎) ➔ (结构化结果与抓拍) ➔ 告警服务/事件总线 ➔ (Webhook/WebSocket/RESTful API) ➔ 第三方应用系统。

设备接口：第三方系统通过 API 向平台注册/查询设备，指定视频流地址与通信参数。
算法任务接口：第三方系统通过 API 下发算法任务，限定分析区域（ROI）、置信度阈值与运行调度。
告警记录接口：平台生成异常事件后，通过 Webhook 向第三方系统主动推送回调，或提供 RESTful API 供第三方按时间、设备及算法类型检索历史记录。

3. 完整步骤

步骤一：OpenAPI 网关连通性与 HTTP 状态诊断

操作目的：确认第三方服务器到 AI 平台 OpenAPI 端口的基础网络可达性。
操作方法 ：在第三方服务器执行 curl 探测网关健康检查端点：

Bash
复制代码
```
curl -v -X GET https://ai-api.domain.com:8443/healthz --insecure
```
检查结果 ：返回 HTTP/1.1 200 OK 且 Response Body 显示 {"status":"UP"}，确认网络通道与 API 网关正常。

步骤二：JWT Token 鉴权与鉴权失效定位

操作目的：排查第三方系统调用 API 时发生的鉴权失败或 Authorization 头格式异常。

操作方法 ：使用 cURL 模拟获取 Token，并使用返回的 Token 发起鉴权验证：

Bash

复制代码

# 1. 获取 Token
TOKEN=$(curl -s -X POST https://ai-api.domain.com:8443/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"app_01", "client_secret":"sec_xxxx"}' | jq -r '.access_token')

# 2. 带有 Bearer 前缀请求设备列表
curl -i -X GET https://ai-api.domain.com:8443/api/v1/devices \
  -H "Authorization: Bearer ${TOKEN}"

检查结果 ：返回 HTTP/1.1 200 OK，JSON 包含设备列表；若返回 401 Unauthorized，则检查 Token 是否过期或缺失 Bearer 关键字。

步骤三：设备接口排查与 RTSP 拉流验证

操作目的：排除第三方系统通过 API 注册设备后，平台因视频流无法解析而导致设备离线的问题。
操作方法：
1. 调用 API 获取设备状态：GET /api/v1/devices/{device_id}。
2. 若状态为 offline，在 AI 平台服务器上使用 ffmpeg 手动测试 RTSP 拉流：
Bash
复制代码
```
ffmpeg -rtsp_transport tcp -i "rtsp://admin:pass@192.168.1.100:554/h264/ch1/main/av_stream" -vframes 1 -f image2 -y /tmp/test.jpg
```
检查结果 ：若生成 /tmp/test.jpg 且无报错，说明网络与流媒体正常；若提示 Connection refused 或 401 Unauthorized，则为主机网络阻断或 RTSP 账号密码错误。

步骤四：算法任务创建诊断与 ROI 参数校验

操作目的：定位第三方系统下发算法任务失败（如 400 Bad Request）或算法未正常运行的问题。

操作方法 ：检查创建任务的 POST Body JSON 格式，确保多边形坐标在 [0.0, 1.0] 归一化范围内：

Bash

复制代码

curl -i -X POST https://ai-api.domain.com:8443/api/v1/tasks \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "dev_1001",
    "algorithm_id": "algo_fire_detection",
    "confidence_threshold": 0.8,
    "roi_config": {"points": [[0.1,0.1],[0.9,0.1],[0.9,0.9],[0.1,0.9]]}
  }'

检查结果 ：接口返回 201 Created 且 task_status 为 running。若返回 400，核对 roi_config 的顶点数是否大于等于 3 且无嵌套语法错误。

步骤五：告警 Webhook 推送抓包与日志定位

操作目的：解决平台已触发告警，但第三方系统未收到 Webhook 异步回调的问题。
操作方法：
1. 在第三方 Webhook 接收服务器上抓取 8080/8443 端口的 HTTP 报文：
Bash
复制代码
```
tcpdump -i any port 8080 -X -s 0
```
1. 在 AI 平台后台发起一次"模拟告警测试"或模拟真实触发。
检查结果：观察控制台是否收到来自 AI 平台 IP 的 POST 请求；若收到请求但平台日志显示推送失败，检查第三方系统返回的 HTTP 响应码（必须为 2xx）。

步骤六：告警记录 RESTful API 分页与时间戳排查

操作目的：排查第三方系统主动调用 API 查询历史告警记录时返回空数据的问题。

操作方法：使用 Unix 时间戳（秒级 10 位）发起带范围过滤的查询请求：

Bash

复制代码

curl -G https://ai-api.domain.com:8443/api/v1/alerts \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "device_id=dev_1001" \
  --data-urlencode "start_time=1700000000" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=10"

检查结果 ：返回 JSON 中 total > 0 且 items 列表包含结构化告警及图片 URL。若为空，核对时间戳单位（避免传入 13 位毫秒级时间戳）。

4. 参数说明

以下是 API 集成与排错过程中关键参数的标准说明：

参数类别	参数项	示例 / 默认值	说明
网关配置	OpenAPI Endpoint	`[https://ai-api.domain.com:8443](https://ai-api.domain.com:8443)`	第三方系统调用的统一 API 入口
鉴权参数	Header Token 格式	`Authorization: Bearer <JWT>`	标头必须包含 `Bearer` 空格分隔符
鉴权参数	Token 有效期	`7200s`	超时前需调用 `/auth/refresh` 刷新
设备配置	视频拉流协议	`RTSP` / `GB28181`	摄像头输出协议（建议 TCP 传输）
设备配置	RTSP 默认端口	`554`	网络防火墙需放行 TCP 554 端口
算法任务	置信度阈值	`0.10 ~ 1.00`	建议配置在 `0.75 ~ 0.85` 之间
算法任务	ROI 坐标系	`[[0.0,0.0] ~ [1.0,1.0]]`	画面归一化相对坐标，避免分辨率变更失效
告警接口	Webhook 超时	`3000ms`	第三方 Webhook 接口应在 3s 内响应
告警接口	时间戳格式	`10位 Unix Timestamp`	历史记录 API 查询使用秒级时间戳
重试控制	Webhook 重试策略	`3 次 (退避 2s, 4s, 8s)`	推送失败后的重试策略

5. 截图建议

在整理企业内部的排错指南与 API 对接手册时，建议配置以下诊断位置截图：

OpenAPI 网关架构与故障排查流程图：展示从第三方请求、网关鉴权、路由转发到流媒体/算法服务的故障排查分支。
Postman/Swagger 鉴权失败与成功对比图 ：展示未带 Bearer 导致 401 报错与正确带 Token 返回 200 的 Response 对比。
RTSP 地址拉流测试界面 ：展示通过 VLC 或命令行 ffplay/ffmpeg 读取摄像头视频流的画面与控制台输出。
ROI 归一化坐标绘制示意图：展示视频画面叠加 0~1 坐标网格后，ROI 多边形顶点的标注方式。
Tcpdump / Wireshark Webhook 抓包图：展示平台向第三方 Webhook 推送告警 Payload 及第三方响应 200 OK 的 TCP 报文串。

6. 常见错误和排查

针对第三方系统调用设备、算法任务与告警记录接口时的常见故障，整理排查清单如下：

复制代码

+-----------------------------------------------------------------------------------+
|                            API 故障诊断与排查决策树                                |
+-----------------------------------------------------------------------------------+
                                         │
                         ┌───────────────┴───────────────┐
                         ▼                               ▼
                 [ HTTP 状态码异常 ]             [ 业务数据/逻辑异常 ]
                         │                               │
         ┌───────────────┼───────────────┐       ┌───────┴───────┐
         ▼               ▼               ▼       ▼               ▼
     [ 401/403 ]     [ 400 Bad ]     [ 502/504 ] [ 设备离线 ]    [ 告警未收到 ]
     鉴权/权限失效    参数/ROI错误     网关/服务超时 RTSP/网络故障  Webhook/网络隔离

故障 1：HTTP 401 Unauthorized

原因分析 ：Token 已失效、未在 Header 中传入 Authorization，或未加 Bearer 前缀。

排查命令：

Bash

复制代码

curl -i -H "Authorization: Bearer <YOUR_TOKEN>" https://ai-api.domain.com:8443/api/v1/devices

解决方法 ：检查 Token 刷新逻辑；确认请求头拼写为 Authorization: Bearer eyJhbGci...。

故障 2：HTTP 400 Bad Request (Invalid ROI Coordinate)

原因分析 ：算法任务创建接口中传入的 roi_config 坐标超出 [0, 1] 范围，或顶点数量少于 3 个。

排查命令：

Bash

复制代码

# 使用 jq 校验 JSON 结构的坐标点
echo '$REQUEST_BODY' | jq '.roi_config.points'

解决方法：检查第三方前端/后端坐标转换逻辑，将绝对像素坐标（如 1920x1080）除以分辨率转换为 0.0~1.0 的浮点数。

故障 3：HTTP 504 Gateway Timeout

原因分析：API 网关转发至内部后端服务超时，通常因底层数据库卡死或流媒体服务无响应。

排查命令：

Bash

复制代码

# 在 AI 平台服务器查看网关与核心服务日志
docker logs --tail 100 -f ai-api-gateway

解决方法：重启 API 网关或流媒体服务；检查平台服务器 CPU 及内存占用率。

故障 4：设备添加成功，但 API 返回 `device_status: offline`

原因分析：RTSP URL 中的账号密码包含特殊字符未做 URL 编码，或平台服务器与摄像头 554 端口网络不通。
排查命令：

Bash
复制代码
```
nc -zv 192.168.1.100 554
```
解决方法 ：对 RTSP URL 中的特殊字符（如 @ 转为 %40）进行 URL Encode；放开网络安全组策略。

故障 5：Webhook 推送失败，平台日志提示 `Connection Refused`

原因分析：第三方系统回调地址填写错误，或第三方服务器防火墙未放行端口。

排查命令：

Bash

复制代码

# 从 AI 平台服务器探测第三方 Webhook 端口
curl -i -X POST http://192.168.2.50:8080/webhook/alarm

解决方法 ：确保第三方 Webhook 服务已启动且监听在 0.0.0.0；检查防火墙规则。

故障 6：告警记录 API 返回空数据 (`"items": []`)

原因分析 ：查询参数 start_time / end_time 传入了 13 位毫秒级时间戳，导致检索区间溢出。

排查命令：

Bash

复制代码

# 验证时间戳位数（应为 10 位）
date -d @1700000000

解决方法：将第三方系统传入的时间戳除以 1000 转换为秒级 Unix 时间戳。

故障 7：Webhook 收到重复告警回调

原因分析 ：第三方 Webhook 接口响应时间超过平台设定的 3000ms，导致平台判定超时并触发重试机制。

排查命令：

Bash

复制代码

# 查看第三方接口响应耗时
curl -o /dev/null -s -w "HTTP: %{http_code} Total Time: %{time_total}s\n" -X POST http://192.168.2.50:8080/webhook/alarm

解决方法：将第三方接收端改造为"异步处理"模式，接收到请求后立即返回 HTTP 200，随后交由后台队列异步处理。

故障 8：告警抓拍图外链无法加载 (HTTP 404 / Connection Timeout)

原因分析 ：平台配置的 media_base_url 使用了内网 IP 或回环地址（127.0.0.1），第三方客户端在公网无法访问。

排查命令：

Bash

复制代码

curl -I http://ai-platform-ip:9000/snapshots/20260812/alarm_01.jpg

解决方法：进入平台【系统参数设置】，将媒体资源访问基地址（Base URL）修改为第三方系统可达的 IP 或公网映射域名。

7. 性能和安全注意事项

性能层面：
1. Token 缓存复用 ：第三方系统切勿在每次调用业务 API 前都请求一次 /auth/token 接口，应在本地缓存 Token 并根据 expires_in 提前 60 秒刷新。
2. 高频查询改成 Webhook 订阅 ：禁止每秒轮询 /api/v1/alerts 接口，避免占用网关连接数，统一采用 Webhook 异步回调。
安全层面：
1. 开启 HTTPS 全链路传输 ：包含 OpenAPI 网关与第三方 Webhook 回调端点，避免 client_secret 与告警数据明文传输。
2. Webhook 报文签名验签：在 Webhook 回调中配置 HMAC-SHA256 签名 Secret，第三方系统接收数据时校验 Header 签名，防止非授权系统伪造告警。

8. 延伸阅读/产品能力

在复杂的系统集成项目中，除了调用基础的设备、算法和告警 API 外，往往还需要涉及 RTSP/RTMP 视频流转推、WebRTC 低延迟播放、多算法级联编排以及千万级历史告警的检索优化。

如果您在集成过程中需要了解更多的高高级 API 接口规范、多语言 SDK (Java/Python/Go) 以及高性能消息队列对接方案，获取最新的技术指南与架构设计文档。

9. 获取更多支持

在 API 接入或故障排查过程中遇到瓶颈？下载完整的 Postman Collection API 测试集合、排错脚本包以及申请专家团队技术支持。

AI视频分析API常见问题和排查清单

1. 环境假设

2. 接入原理

3. 完整步骤

步骤一：OpenAPI 网关连通性与 HTTP 状态诊断

步骤二：JWT Token 鉴权与鉴权失效定位

步骤三：设备接口排查与 RTSP 拉流验证

步骤四：算法任务创建诊断与 ROI 参数校验

步骤五：告警 Webhook 推送抓包与日志定位

步骤六：告警记录 RESTful API 分页与时间戳排查

4. 参数说明

5. 截图建议

6. 常见错误和排查

故障 1：HTTP 401 Unauthorized

故障 2：HTTP 400 Bad Request (Invalid ROI Coordinate)

故障 3：HTTP 504 Gateway Timeout

故障 4：设备添加成功，但 API 返回 device_status: offline

故障 5：Webhook 推送失败，平台日志提示 Connection Refused

故障 6：告警记录 API 返回空数据 ("items": [])

故障 7：Webhook 收到重复告警回调

故障 8：告警抓拍图外链无法加载 (HTTP 404 / Connection Timeout)

7. 性能和安全注意事项

8. 延伸阅读/产品能力

9. 获取更多支持

故障 4：设备添加成功，但 API 返回 `device_status: offline`

故障 5：Webhook 推送失败，平台日志提示 `Connection Refused`

故障 6：告警记录 API 返回空数据 (`"items": []`)