Ignis API 开发文档 | 非接触式健康监测 WebSocket 接入

调用方式与鉴权

☁️ 远程云服务

直接调用 Ignis 官方云端 API，无需部署服务器。

Endpoint: wss://health.yanshutech.com/ws/
鉴权: 必须携带 API Key
Key 获取: 前往设置 > API 访问密钥查看
收费: 每个 WebSocket 连接消耗 1 个积分（按连接计费，不按测量次数计费——单个连接可以持续较长时间）。一次连接最长约 12 小时后需要重新建立，重新建立即按新连接计费。

企业 License 按授权终端/实例计价，计费范围以合同为准，不适用自助 Cloud API 的积分/连接规则。也可另行协商 100,000 completed scans（10 万次完成检测）套餐；完成检测定义、失败/重试计数、有效期及价格需在合同中明确，一次连接不等于一次测量。请联系 wuac@yanshutech.com。

🏠 私有化/本地部署

在您自己的内网服务器或 Docker 容器中运行。

Endpoint: ws://YOUR_LOCAL_IP:9100
鉴权: 可选 (根据配置，通常本地测试可留空 Key)
说明: 适合对数据隐私有极高要求的场景

URL 格式示例

ws://{HOST}/ws/?token={API_KEY}

可用客户端：官方 Web 产品（浏览器摄像头）、官方 Android App（APK）、以及任意平台的 WebSocket 客户端（Linux / Windows / macOS / iOS / Android 均可自行实现帧推流）。白标/贴牌基于 WebSocket API 与 Android App 提供；目前不提供现成的标准 native iOS/Android SDK 包，native SDK 按项目单独交付。

示例代码下载

以下代码提供了完整的接入示例，右键点击链接选择“另存为”即可下载。

文件名	类型	说明	操作
js_simple.html	Web 前端	最简 HTML+JS 客户端，演示如何调用摄像头并推流	查看/下载
python_simple.py	Python 脚本	使用 OpenCV 采集并推送二进制流的 Python 示例	下载
rtsp_simple.html	Web 工具	RTSP 拉流测试控制台，用于发送 start/stop 指令	查看/下载
metrics.html	文档	详细的生理指标与 JSON 字段对照表	查看

核心协议

客户端（浏览器/Python/Android）采集摄像头画面，将帧数据通过 WebSocket 二进制(Binary) 发送给服务器。

二进制包结构 (Binary Packet Structure)

字节偏移	数据类型	端序 (Endian)	说明
Byte 0	Uint8	-	类型位 (固定为 `0`，代表视频帧)
Byte 1-8	Float64	Little Endian	时间戳 (单位：秒，双精度浮点数)
Byte 9...	Bytes	-	JPEG 图片数据 (完整的文件流)

代码示例

Python (OpenCV + struct)

import struct
import time
import cv2

# 1. 压缩图片
_, jpeg = cv2.imencode('.jpg', frame, [int(cv2.IMWRITE_JPEG_QUALITY), 90])

# 2. 构建包头: Type(0) + Timestamp(double)
# < 代表小端模式, B=uchar, d=double
header = struct.pack('<Bd', 0, time.time())

# 3. 发送
ws.send(header + jpeg.tobytes(), opcode=2)

JavaScript (Browser)

// 假设 jpegBuffer 是图片ArrayBuffer
const timestamp = Date.now() / 1000;
const totalLen = 1 + 8 + jpegBuffer.byteLength;
const buffer = new ArrayBuffer(totalLen);
const view = new DataView(buffer);

// 1. 写入类型和时间戳 (True = Little Endian)
view.setUint8(0, 0); 
view.setFloat64(1, timestamp, true);

// 2. 写入图片数据
new Uint8Array(buffer, 9).set(new Uint8Array(jpegBuffer));

ws.send(buffer);

通过 WebSocket 发送 JSON 指令，告知服务器主动去拉取指定的 RTSP 视频流。

1. 开启分析 (start_rtsp)

{
  "action": "start_rtsp",
  "rtsp_url": "rtsp://admin:123456@192.168.1.100:554/stream",
  "stream_id": "camera_01"  // 选填，用于后续停止任务的唯一标识
}

2. 停止分析 (stop_rtsp)

{
  "action": "stop_rtsp",
  "stream_id": "camera_01" // 优先使用 ID 停止
  // 或者 "rtsp_url": "..." 
}

返回数据字典

服务器将通过 WebSocket 实时下发 JSON 格式的分析结果。数据结构如下：

更多字段说明（研究字段默认折叠）请查看 metrics.html

🩺 生理指标 (Physiological)

JSON 路径	单位	说明
`spo2`	%	血氧饱和度（估算值）。不能替代血氧仪；异常结果应使用专业设备复核。
`hrv.meanHr`	bpm	平均心率。
`hrv.sdnn`	ms	SDNN (Standard Deviation of NN intervals)。
`hrv.rmssd`	ms	RMSSD。主要反映副交感神经活性。
`SBP` / `DBP`	mmHg	收缩压 / 舒张压估算值（健康参考估算，不能替代血压计）。
`Breathing_RATE`	rpm	呼吸频率。

🧠 心理与健康趋势

JSON 路径	说明
`emotion_short_res`	实时情绪趋势。枚举值：`Neutral`, `Happy`, `Sad`等。
`stress_score`	压力指数 (0-100)，趋势性评分。
`attention_score`	专注度趋势评分。

健康参考声明：上述指标均为算法估算值，不构成医学诊断或心理评估。实验性 / 研究性字段不在本商用字典中展示，也不属于标准商用功能承诺；研究用途及项目交付范围需另行书面约定。如有健康问题，请咨询专业医生。