接口总览
基础信息
Base URL: https://api.heartvoice.com.cn
所有请求需要在 Header 中携带 API Key：
Authorization: Bearer YOUR_API_KEY
ECG 心电分析接口
基础版接口
| 接口 | 方法 | 说明 | 套餐要求 |
|---|---|---|---|
/api/v1/basic/ecg/1-lead/analyze | POST | 单导联ECG分析 | 基础版+ |
/api/v1/basic/ecg/12-lead/analyze | POST | 12导联ECG分析 | 基础版+ |
输入参数：
- 单导联：ecgData（数组）、ecgSampleRate、adcGain、adcZero
- 12导联：dataI/II/III/AVR/AVL/AVF、data1-6（V1-V6）、ecgSampleRate、adcGain、adcZero
- 注：每个导联的心电信号数据长度限制在10s~300s，采样率必须大于0，增益默认1.0，零点默认0.0
输出结果：
- 诊断结论列表（diagnosis）
- 信号质量等级（sqGrade）
- 导联是否反接（isReverse）
- 是否异常（isAbnormal）
- 心电参数（avgHr、avgQrs、prInterval、avgQt、avgP、avgQtc）
- 早搏计数（pacCount、pvcCount）
📖 查看详细文档
高阶版接口
| 接口 | 方法 | 说明 | 套餐要求 |
|---|---|---|---|
/api/v1/advanced/ecg/analyze | POST | ECG完整分析 | 高阶版 |
/api/v1/advanced/ecg/heart-age | POST | 心脏年龄评估 | 高阶版 |
/api/v1/advanced/ecg/mental-state | POST | 心理情绪评估 | 高阶版 |
/api/v1/advanced/ecg/deepLife | POST | 微体检分析 | 高阶版 |
ECG完整分析 包含：
- ✅ 基础版所有分析结果
- ✅ 心脏年龄（heartAge）
- ✅ 呼吸频率（respiratoryRate）
- ✅ HRV心率变异性（hrv）
- ✅ 压力指数（pressure）
- ✅ 情绪指数（emotion）
- ✅ 疲劳指数（fatigue）
- ✅ 活力指数（vitality）
心脏年龄评估 提供：
- 心脏年龄值
- 信号质量评级
心理情绪评估 提供：
- 压力指数、情绪指数
- 疲劳指数、活力指数
微体检分析 提供：
- 人体九大系统疾病风险分析（anyEcg）
- Map结构：人体系统 → phecode病症码 → 风险概率与等级
📖 查看详细文档
长程心电分析接口（异步）
| 接口 | 方法 | 说明 | 套餐要求 |
|---|---|---|---|
/api/v1/advanced/ecg/holter/upload-url | POST | 获取文件上传凭证 | 高阶版 |
/api/v1/advanced/ecg/holter/submit | POST | 提交长程分析任务 | 高阶版 |
/api/v1/advanced/ecg/holter/status/:task_id | GET | 查询任务状态 | 高阶版 |
/api/v1/advanced/ecg/holter/result/:task_id | GET | 获取分析结果 | 高阶版 |
/api/v1/advanced/ecg/holter/report/:task_id | GET | 下载PDF报告 | 高阶版 |
长程心电分析 （Holter） 特点：
- ✅ 支持24小时-7天连续心电数据
- ✅ 异步处理，支持Webhook回调
- ✅ 完整心律失常统计（早搏、房颤等）
- ✅ ST段分析、HRV分析
- ✅ 代表性心电图片段
- ✅ 可选医生人工审核（Ultra版）
- ✅ 标准格式PDF报告
📖 查看详细文档
PPG 脉搏波分析接口
高阶版接口
| 接口 | 方法 | 说明 | 套餐要求 |
|---|---|---|---|
/api/v1/advanced/ppg/blood-pressure | POST | 血压估算 | 高阶版 |
/api/v1/advanced/ppg/vascular-health | POST | 血管健康评估 | 高阶版 |
血压估算 输入：
- ECG数据（ecgData、ecgSampleRate、adcGain、adcZero）
- PPG数据（ppgData对象：red、green、infrared）
- PPG采样率（ppgSampleRate）
血压估算 输出：
- 信号质量（sqGrade）
- 收缩压（sbp）
- 舒张压（dbp）
血管健康评估 输入：
- ECG数据（ecgData、ecgSampleRate、adcGain、adcZero）
- PPG数据（ppgData对象：red、green、infrared）
- PPG采样率（ppgSampleRate）
血管健康评估 输出：
- 信号质量（sqGrade）
- 血管年龄（vascularAge）
PPG数据格式
PPG数据需提供三种光源数据：
red：红光数据数组green：绿光数据数组infrared：红外光数据数组
📖 查看详细文档
通用响应字段说明
信号质量等级（sqGrade）
多数分析接口会返回 sqGrade 字段，表示输入信号的质量等级：
| sqGrade 值 | 质量等级 | 说明 | 建议 |
|---|---|---|---|
| > 0.9 | 优 | 信号质量优秀 | 分析结果可信度高 |
| 0.7 - 0.9 | 良 | 信号质量良好 | 分析结果基本可信 |
| 0.5 - 0.7 | 中 | 信号质量一般 | 建议重新采集信号 |
| < 0.5 | 不可分析 | 信号质量过低 | 无法进行有效分析，必须重新采集 |
影响信号质量的因素：
- 电极接触不良
- 身体移动、肌肉颤动
- 环境电磁干扰（如工频干扰）
- 采集设备故障
- 导联线接触不良
提高信号质量的建议：
- 确保电极/传感器与皮肤良好接触
- 保持身体静止，放松肌肉
- 远离强电磁干扰源
- 检查设备连接是否正常
- 清洁皮肤，必要时使用导电膏
状态码说明
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查参数格式和必填项 |
| 401 | 认证失败 | 检查API Key是否正确 |
| 403 | 权限不足 | 升级套餐或检查配额 |
| 429 | 请求过多 | 降低请求频率，稍后重试 |
| 500 | 服务器错误 | 联系技术支持 |
错误响应格式
{
"errorCode": "000004",
"msg": "API Key无效或已过期"
}
常见错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 000004 | API Key无效 | 检查Key是否正确 |
| 000005 | 配额已用完 | 联系技术支持 |
| 000006 | 触发限流 | 降低请求频率 |
| 000007 | 无接口权限 | 升级到对应套餐 |
| 000010 | 信号时长不在允许范围内 | 增加或减少数据长度 |
| 000011 | 采样率非法 | 传递正确的采样率 |
| 000012 | 信号数据为空 | 传递非空的信号数据进行分析 |
| 000013 | PPG多组信号长度不一致 | 保持多组ppg信号长度一致 |
套餐权限对照
| 接口 | 基础版 | 高阶版 |
|---|---|---|
| 单导联ECG分析 | ✅ 1000次/天 | ✅ 50000次/天 |
| 12导联ECG分析 | ✅ | ✅ |
| ECG完整分析 | ❌ | ✅ |
| 心脏年龄评估 | ❌ | ✅ |
| 心理情绪评估 | ❌ | ✅ |
| DeepLife微体检 | ❌ | ✅ |
| 长程心电分析 | ❌ | ✅ |