JF Open Pro AI Smart Search
面向开发者杰峰 AI 智搜工具 (Python)
根据语义内容搜索杰峰云存报警视频，获取匹配的视频片段列表及播放信息。
🔒 安全说明
凭据存储：仅支持环境变量
| 方式 | 支持 | 说明 |
|---|
| 环境变量 | ✅ 支持 | 推荐方式，避免凭据出现在进程列表或日志中 |
| 命令行参数 | ❌ 不支持 | 避免凭据泄露风险 |
| 配置文件 | ❌ 不支持 | 避免明文存储凭据 |
网络访问：
- ✅ 仅访问杰峰官方 API 端点 (
api.jftechws.com / api-cn.jftech.com)
- ❌ 不访问第三方服务
- ❌ 不读取本地文件系统
脚本行为：
- ✅ 本地执行 Python 脚本（技能本身）
- ✅ 仅向指定的杰峰 API 端点发起 HTTPS 请求
- ❌ 不执行外部命令
- ❌ 不读取敏感系统文件
🚀 快速开始
设置环境变量
export JF_UUID="your-uuid" # 开放平台用户唯一标识
export JF_APPKEY="your-appkey" # 开放平台应用 Key
export JF_APPSECRET="your-appsecret" # 开放平台应用密钥
export JF_MOVECARD=5 # 签名算法偏移量 (0-9)
export JF_SN="your-device-sn" # 设备序列号
export JF_USER="admin" # 用户 ID（可选，默认：admin）
使用技能
# AI 智搜 - 搜索"人"相关的视频
python scripts/search_video.py --search "人"
# AI 智搜 - 搜索"车"相关的视频
python scripts/search_video.py --search "车"
# AI 智搜 - 搜索"狗"相关的视频
python scripts/search_video.py --search "狗"
# AI 智搜 - 搜索"戴帽子的人"
python scripts/search_video.py --search "戴帽子的人"
# 获取云存回放地址（指定时间）
python scripts/get_playback_url.py --start-time "2026-04-07 12:00:00" --stop-time "2026-04-07 12:45:00"
# 完整流程：AI 智搜 + 播放地址（推荐）
python scripts/ai_search_playback.py --search "人" --video-index 0
📋 环境变量
| 变量名 | 说明 | 必需 | 默认值 |
|---|
JF_UUID | 开放平台用户唯一标识 | 是 | - |
JF_APPKEY | 开放平台应用 Key | 是 | - |
JF_APPSECRET | 开放平台应用密钥 | 是 | - |
JF_MOVECARD | 签名算法偏移量 (0-9)，用于时间戳偏移增加签名安全性 | 是 | - |
JF_SN | 设备序列号 | 是 | - |
JF_USER | 用户 ID | 否 | admin |
JF_ENDPOINT | API 端点 | 否 | api.jftechws.com |
🛠️ 功能
1. AI 智搜视频
根据语义内容搜索 AI 标记的云存报警视频。
支持的搜索类型：
| 搜索类型 | 示例查询 | 说明 |
|---|
| 人物 | "人"、"戴帽子的人"、"穿红色衣服的人" | 基于人形 + 属性检测 |
| 车辆 | "车"、"白色轿车"、"卡车" | 基于车辆检测 |
| 动物 | "狗"、"猫" | 基于动物检测 |
| 行为 | "跑步的人"、"摔倒" | 基于行为分析 |
使用示例：
# 搜索"人"相关的视频
python scripts/search_video.py --search "人"
# 搜索"车"相关的视频
python scripts/search_video.py --search "车"
# 搜索"戴帽子的人"
python scripts/search_video.py --search "戴帽子的人"
返回字段说明：
| 字段 | 说明 | 示例 |
|---|
st | 录像开始时间（秒） | 1703275200 |
et | 录像结束时间（秒） | 1703275260 |
matchRate | 匹配度（0-1） | 0.95 |
queryTags | 检测到的标签列表 | ["person", "hat"] |
eventTime | 事件触发时间 | "2024-12-23 10:00:00" |
2. 云存回放地址获取
获取云存报警视频回放/播放地址。
使用示例：
# 指定时间范围获取回放地址
python scripts/get_playback_url.py --start-time "2026-04-07 12:00:00" --stop-time "2026-04-07 12:45:00"
# 完整流程：AI 智搜 + 播放地址（推荐）
python scripts/ai_search_playback.py --search "人" --video-index 0
工作流程：
1. AI 智搜搜索视频
↓
获取云存报警信息视频列表
↓
2. 选择目标视频
↓
提取 st（开始时间）和 et（结束时间）
↓
3. 调用云存报警视频回放 API
↓
st 对应 startTime
et 对应 stopTime
↓
4. 获取播放链接
📖 使用场景示例
场景 1: 搜索特定人员的活动记录
# 搜索"人"相关的视频
python scripts/search_video.py --search "人"
# 查看返回结果，选择感兴趣的视频片段
# 使用返回的 st 和 et 获取回放地址
python scripts/get_playback_url.py --start-time "2026-04-07 12:00:00" --stop-time "2026-04-07 12:45:00"
场景 2: 搜索车辆进出记录
# 搜索"车"相关的视频
python scripts/search_video.py --search "车"
场景 3: 完整流程 - 搜索并播放
# 一步完成：搜索"人"并获取第一个视频的回放地址
python scripts/ai_search_playback.py --search "人" --video-index 0
⚠️ 错误处理
| 错误码 | 说明 | 解决方案 |
|---|
2000 | 成功 | - |
12504 | 授权失败 - 设备未开通 AI 智搜套餐 | 登录开放平台为设备绑定 AI 智搜套餐卡 |
10001 | 参数错误 | 检查请求参数格式 |
10002 | 签名失败 | 检查 appKey/appSecret 和时间戳 |
错误码 12504 处理
错误信息： authorize failed, Please check it in the open platform
原因： 设备未开通 AI 智搜服务，或未绑定套餐卡
解决步骤：
- 登录杰峰开放平台：https://developer.jftech.com
- 进入 套餐管理 / 服务管理
- 找到 AI 智搜 或 云存视频搜索 套餐
- 为设备购买并绑定套餐卡
- 等待配置生效（通常 1-5 分钟）
- 重新调用 API 测试
⚠️ 注意事项
- 设备需开通云存服务 - AI 智搜需要云存套餐支持
- 设备需开通 AI 智搜套餐 - 需在开放平台绑定套餐卡
- 时间范围 - 只能搜索云存有效期内的视频
- 搜索精度 - 受 AI 算法识别精度影响
📚 官方参考资料
📁 脚本工具
可用脚本：
| 脚本 | 功能 |
|---|
search_video.py | AI 智搜 - 搜索云存报警视频 |
get_playback_url.py | 获取云存回放地址（指定时间或完整流程） |
ai_search_playback.py | 完整流程 - AI 智搜 + 播放地址一键获取 |
# 获取帮助
python scripts/search_video.py --help
python scripts/get_playback_url.py --help
python scripts/ai_search_playback.py --help
# AI 智搜
python scripts/search_video.py --search <搜索内容>
# 获取回放地址（指定时间）
python scripts/get_playback_url.py --start-time "YYYY-MM-DD HH:MM:SS" --stop-time "YYYY-MM-DD HH:MM:SS"
# 完整流程：AI 智搜 + 播放地址（推荐）
python scripts/ai_search_playback.py --search <搜索内容> --video-index <索引>
脚本路径：scripts/search_video.py, scripts/get_playback_url.py, scripts/ai_search_playback.py
技能版本： v1.0.0
语言： Python
最后更新： 2026-04-07
