ECG 长程快速分析 API
长程快速分析与长程分析并行提供,文件上传方式与请求参数完全一致,区别在于分析在秒级完成,并返回明确的任务状态。
异步处理
快速分析采用异步模式,提交任务后通过轮询查询接口获取结果。
与长程分析的区别
两条通道并存,可按需选择。
| 长程分析 | 长程快速分析 | |
|---|---|---|
| 获取上传地址 | /api/v1/advanced/ecg/holter/upload-url | 同左 |
| 提交接口 | /api/v1/advanced/ecg/holter/submit | /api/v1/advanced/ecg/holter/fast/submit |
| 查询接口 | /api/v1/advanced/ecg/holter/result/:id | /api/v1/advanced/ecg/holter/fast/result/:taskId |
| 提交请求体 | fileUrl + 采集参数 | 同左 |
| 查询返回 | data 为 null 表示尚未完成 | data.status 显式给出任务状态 |
| 结果字段 | data.report 是 JSON 字符串,需二次解析 | data.result 已是 JSON 对象 |
| 结果内容 | 心率、HRV、QTc、节律、早搏、PDF 报告 | 心率、HRV、节律、早搏 |
| 记录时长上限 | 无 | 24 小时 |
结果字段不是超集
快速分析结果不包含 QT 间期校正(qtc)、有效信号时长(totalValidDuration)与 PDF 报告(pdfUrl)。如业务依赖这些字段,请使用长程分析。
分析流程
接口列表
| 接口 | 方法 | 说明 |
|---|---|---|
/api/v1/advanced/ecg/holter/upload-url | GET | 获取文件上传地址(与长程分析共用) |
/api/v1/advanced/ecg/holter/fast/submit | POST | 提交一条快速分析任务 |
/api/v1/advanced/ecg/holter/fast/result/:taskId | GET | 查询快速分析任务状态与结果 |
Step 1:获取上传地址
GET /api/v1/advanced/ecg/holter/upload-url
用于获取心电二进制文件的上传地址。该接口与长程分析通道相同,已接入长程分析的调用方无需改动这一步。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
fileType | string | 是 | 文 件类型,当前仅支持 BINARY16、BIN3_16 |
请求示例
curl -X GET "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/upload-url?fileType=BINARY16" \
-H "Authorization: Bearer YOUR_API_KEY"
响应示例
{
"errorCode": "0",
"msg": "成功",
"data": "https://ecgdata-1255716792.cos.ap-shanghai.myqcloud.com/openapi/2039546102478438400/2604021132295727.BINARY16?sign=xxx"
}
说明
- 返回值
data为文件上传地址。 - 客户端拿到地址后,自行完成文件上传。
- 上传地址有有效期,请在获取后尽快上传并提交分析。
- 上传文件格式说明如下。
文件上传示例
客户端获取到上传地址后,可直接使用该地址上传原始心电文件。示例如下:
curl -X PUT --location "https://ecgdata-1255716792.cos.ap-shanghai.myqcloud.com/openapi/2039546102478438400/2604021132295727.BINARY16?sign=xxx" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-binary @/path/to/your/file.BINARY16
说明:
- 将命令中的 URL 替换为 Step 1 接口实际返回的上传地址。
- 将
/path/to/your/file.BINARY16替换为本地待上传文件路径。 - 文件扩展名应与申请上传地址时传入的
fileType保持一致。
上传文件格式说明
当前支持以下两种二进制文件格式:
BINARY16 格式(单导联)
- 2 个字节为一组,表示 1 个 ECG 信号点。
- 第 1、2 字节表示第 1 个信号点。
- 第 3、4 字节表示第 2 个信号点。
- 以此类推。
- 字节按大端有符号数转换为十进制值。
字节1 字节2 -> 第1个信号点
字节3 字节4 -> 第2个信号点
字节5 字节6 -> 第3个信号点
...
BIN3_16 格式(三导联)
- 6 个字节为一组。
- 第 1、2 字节表示第 1 个导联的第 1 个点。
- 第 3、4 字节表示第 2 个导联的第 1 个点。
- 第 5、6 字节表示第 3 个导联的第 1 个点。
- 后续按相同顺序依次表示下一采样点的三导联数据。
- 字节按大端有符号数转换为十进制值。
字节1 字节2 -> 第1导联第1个点
字节3 字节4 -> 第2导联第1个点
字节5 字节6 -> 第3导联第1个点
字节7 字节8 -> 第1导联第2个点
字节9 字节10 -> 第2导联第2个点
字节11 字节12 -> 第3导联第2个点
...
Step 2:提交快速分析任务
POST /api/v1/advanced/ecg/holter/fast/submit
文件上传完成后,调用该接口提交分析任务。请求体与长程分析提交接口一致。
请求体参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
fileUrl | string | 是 | Step 1 返回的文件上传地址,原样回传 |
adcGain | number | 是 | 增益系数,不能为 0 |
adcZero | number | 是 | 基线电压 |
sampleRate | integer | 是 | 采样率,取值范围 1 ~ 10000 |
deviceId | string | 否 | 设备 ID |
startTime | string | 否 | 记录开始时间,格式必须为 yyyy-MM-dd HH:mm:ss |
subject | object | 否 | 受检者信息 |
subject 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 否 | 姓名,最长 20 个字符 |
age | integer | 否 | 年龄 |
gender | string | 否 | 性别,最长 5 个字符 |
note
单条记录的时长不得超过 24 小时,超出的记录请拆分后分次提交。
结果中的位置(idx)需要配合 startTime 换算为实际时刻,建议传入。
请求示例
curl -X POST "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/fast/submit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileUrl": "https://ecgdata-1255716792.cos.ap-shanghai.myqcloud.com/openapi/2039546102478438400/2604021132295727.BINARY16?sign=xxx",
"adcGain": 1000,
"adcZero": 0,
"sampleRate": 256,
"deviceId": "DEVICE_001",
"startTime": "2026-04-02 10:00:00",
"subject": {
"name": "张三",
"age": 56,
"gender": "男"
}
}'
响应示例
{
"errorCode": "0",
"msg": "成功",
"data": "2092896927501512704"
}
说明
- 返回值
data为本次快速分析的任务 ID(taskId)。 taskId是字符串形式的 19 位数字,请勿按数值类型解析(JavaScript 等语言会丢失精度)。- 接口返回成功表示任务已受理,不代表分析已完成,需通过 Step 3 查询结果。
错误响应
| HTTP 状态 | errorCode | 说明 | 建议处理 |
|---|---|---|---|
| 400 | 000002 | 必填参数缺失或取值不合法 | 依据 msg 修正后重试 |
| 400 | 000008 | 参数取值不合法,或文件不可读取、记录时长超过 24 小时 | 依据 msg 修正后重试 |
| 429 | 000006 | 请求过于频繁 | 降低请求频率后重试 |
| 429 | 000014 | 分析服务繁忙 | 稍后重试 |
| 429 | 000015 | 当前账号同时进行的分析任务过多 | 待已提交的任务完成后再提交 |
| 500 | 000017 | 分析服务暂不可用 | 稍后重试 |
Step 3:查询快速分析结果
GET /api/v1/advanced/ecg/holter/fast/result/:taskId
根据提交接口返回的任务 ID 轮询任务状态与结果。请将路径中的 :taskId 替换为实际任务 ID。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 提交接口返回的任务 ID |
请求示例
curl -X GET "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/fast/result/2092896927501512704" \
-H "Authorization: Bearer YOUR_API_KEY"
返回字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 任务状态,取值见下表 |
result | object | 分析结果,仅 status = SUCCESS 时非空 |
status 取值
| 取值 | 含义 | 是否继续轮询 |
|---|---|---|
PENDING | 排队中 | 是 |
RUNNING | 分析中 | 是 |
SUCCESS | 分析完成 | 否,result 即为结果 |
FAILED | 分析失败 | 否 |