医生解读 API

AI 分析给出的是算法结论。医生解读是在同一份心电数据上，由执业医师复核 AI 结果并出具人工结论。

人工过程，时效以小时计

提交后由医生排队处理，不是秒级返回。请按分钟级轮询，详见轮询建议。

需单独开通，不含在套餐权益内

医生解读不包含在基础版、高阶版等任何套餐权益中—— 它是人工服务，额度按需单独约定。需要使用请联系我们开通，长程与短程两项可分别开通。额度按数据时长扣减，见计费规则。

支持的分析类型

分析接口	解读提交接口
`/api/v1/advanced/ecg/holter/fast/submit`（长程快速分析）	`/api/v1/advanced/interpretation/holter`
`/api/v1/advanced/ecg/holter/submit`（长程完整分析）	`/api/v1/advanced/interpretation/holter`
`/api/v1/advanced/ecg/analyze`（ECG 完整分析）	`/api/v1/advanced/interpretation/ecg`
`/api/v1/basic/ecg/1-lead/analyze`（ECG 基础分析）	`/api/v1/advanced/interpretation/ecg`

两条长程通道共用同一个提交接口与同一份配额，两条短程通道同理。

计费规则

医生解读按数据时长扣减额度，而不是按调用次数。长程与短程各扣各的额度。

类型	规则
短程	1 分钟记 1 次，超出部分每 1 分钟记 1 次，不足 1 分钟按 1 分钟计
长程	每满 24 小时记 1 次；不足 24 小时的部分，不到 2 小时记 0.5 次，满 2 小时按 24 小时计

数据时长	扣减
短程不超过 1 分钟	1 次
短程超过 1 分钟、不超过 2 分钟	2 次
短程超过 4 分钟、不超过 5 分钟	5 次
长程不到 2 小时	0.5 次
长程 2 小时（含）～ 24 小时	1 次
长程超过 24 小时、不到 26 小时	1.5 次
长程 26 小时（含）～ 48 小时	2 次

解读流程

接口列表

接口	方法	说明
`/api/v1/advanced/interpretation/holter`	POST	为一次长程分析申请医生解读（快速与完整通用）
`/api/v1/advanced/interpretation/ecg`	POST	为一次 ECG 短程分析申请医生解读（基础与完整通用）
`/api/v1/advanced/interpretation/result/:interpretationId`	GET	查询解读状态与结果

Step 1：申请解读

POST /api/v1/advanced/interpretation/holter

请求体参数

参数	类型	必填	说明
`sourceId`	string	是	长程分析（快速或完整）提交接口返回的分析 ID，也就是查询该次分析结果时用的那个 ID

请求示例

curl -X POST "https://api.heartvoice.com.cn/api/v1/advanced/interpretation/holter" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceId": "2092896927501512704" }'

POST /api/v1/advanced/interpretation/ecg

请求体参数

参数	类型	必填	说明
`sourceId`	string	是	ECG 完整分析或基础分析响应体里的 `recordId`，与其它分析字段平级

请求示例

curl -X POST "https://api.heartvoice.com.cn/api/v1/advanced/interpretation/ecg" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceId": "2103548812345678901" }'

响应示例

{
  "errorCode": "0",
  "msg": "成功",
  "data": "2092896927501598321"
}

说明

返回值 data 为本次解读的 interpretationId，是字符串形式的 19 位数字，请勿按数值类型解析（JavaScript 等语言会丢失精度）。
接口返回成功表示解读申请已受理，不代表医生已出结论。
同一次分析不能重复申请，重复提交返回 000021，改用上次返回的 interpretationId 查询即可。
长程分析结果为无效数据时不能申请解读，返回 000023。这类数据医生也判读不了，请重新采集。

错误响应

HTTP 状态	`errorCode`	说明	建议处理
400	`000005`	未开通医生解读，或剩余额度不足以覆盖本次数据时长	医生解读不含在套餐权益内，请联系我们开通或追加额度
400	`000002`	`sourceId` 缺失或格式非法	检查是否传了完整的 19 位 ID 字符串
400	`000019`	待解读的分析记录不存在，或不属于当前 API Key	确认 `sourceId` 取自本 Key 的分析响应
400	`000020`	该分析尚未完成	先轮询到分析 `SUCCESS` 再申请解读
400	`000021`	该分析已申请过医生解读	直接用上次返回的 `interpretationId` 查询
400	`000023`	该分析结果为无效数据，无法申请解读	重新采集后再分析，不要对同一份数据重试
429	`000006`	请求过于频繁	降低请求频率后重试
500	`000022`	医生解读服务暂不可用	稍后对同一个 `sourceId` 重试

Step 2：查询解读结果

GET /api/v1/advanced/interpretation/result/:interpretationId

路径参数

参数	类型	必填	说明
`interpretationId`	string	是	申请解读时返回的 ID

请求示例

curl -X GET "https://api.heartvoice.com.cn/api/v1/advanced/interpretation/result/2092896927501598321" \
  -H "Authorization: Bearer YOUR_API_KEY"

返回字段说明

字段	类型	说明
`status`	string	解读状态，取值见下表
`report`	object	解读结果，仅 `status = SUCCESS` 时非空

`status` 取值

取值	含义	是否继续轮询
`PROCESSING`	解读中	是
`SUCCESS`	解读完成，`report` 即为结果	否
`FAILED`	解读失败	否

解读中示例

{
  "errorCode": "0",
  "msg": "成功",
  "data": {
    "status": "PROCESSING",
    "report": null
  }
}

长程解读报告

由 /api/v1/advanced/interpretation/holter 申请的解读返回该结构（快速与完整两条通道相同）。

report 是医生复核后的完整分析结果：与长程分析结果同构，同名字段含义完全一致，见长程分析结果 JSON 字段说明。在此之上多出下面三个字段。

字段	类型	说明
`diagContent`	string	医生诊断结论。多行文本，换行为 `\r\n`
`reportEcgFragments`	object[]	医生复核后勾选的代表性片段。每项含 `label`（节律标签）与 `idx`（片段起止采样点下标）。与分析结果里的 `labelIdx` 同类，区别是这份经过医生复核
`pdfUrl`	string	医生出具的报告 PDF 下载地址，未上传时为 `null`

{
  "errorCode": "0",
  "msg": "成功",
  "data": {
    "status": "SUCCESS",
    "report": {
      "premature": {
        "totalPAC": 0, "singlePAC": 0, "pairedPAC": 0, "pairedPACCnt": 0,
        "bigeminyPAC": 0, "bigeminyPACCnt": 0, "triadPAC": 0, "triadPACCnt": 0,
        "totalSVT": 0, "totalSVTCnt": 0,
        "totalPVC": 4, "singlePVC": 2, "pairedPVC": 1, "pairedPVCCnt": 2,
        "bigeminyPVC": 0, "bigeminyPVCCnt": 0, "triadPVC": 0, "triadPVCCnt": 0,
        "totalVT": 0, "totalVTCnt": 0,
        "totalPJC": 0, "singlePJC": 0, "pairedPJC": 0, "pairedPJCCnt": 0,
        "bigeminyPJC": 0, "bigeminyPJCCnt": 0, "triadPJC": 0, "triadPJCCnt": 0,
        "totalJT": 0, "totalJTCnt": 0
      },
      "SNB": null,
      "SNT": {
        "idx": [309735, 321922],
        "maxBeatCount": 110,
        "maxDuration": 60,
        "totalDuration": 700
      },
      "hr": {
        "avgHr": 99,
        "minHr": 79,
        "minHrIdx": 291866,
        "maxHr": 138,
        "maxHrIdx": 157900,
        "maxTopHr": [
          { "hr": 138, "idx": 157900 },
          { "hr": 135, "idx": 158433 },
          { "hr": 132, "idx": 157379 },
          { "hr": 132, "idx": 158979 },
          { "hr": 132, "idx": 160646 }
        ],
        "minTopHr": [
          { "hr": 83, "idx": 380846 },
          { "hr": 82, "idx": 409429 },
          { "hr": 81, "idx": 351327 },
          { "hr": 79, "idx": 291866 },
          { "hr": 78, "idx": 350439 }
        ]
      },
      "diagDescription": "记录全过程为窦性心律，部分时间PP差>0.16s；心率介于79~138次/分，平均心率99次/分，心率正常。偶发室性早搏，单发室早1次。",
      "diagContent": "结论:\r\n1.窦性心律，窦性心律不齐\r\n2.偶发室性早搏\r\n",
      "reportEcgFragments": [
        { "label": "SINGLE_PVC", "idx": [8538, 8651] },
        { "label": "SINGLE_PVC", "idx": [157900, 157987] },
        { "label": "PAIRED_PVC", "idx": [161975, 162178] }
      ],
      "pdfUrl": "https://ecgdata-1255716792.cos.ap-shanghai.myqcloud.com/oem/1033064347457294336/2609081349599242.pdf?sign=xxx"
    }
  }
}

数据得不出结论时的返回：

{
  "errorCode": "0",
  "msg": "成功",
  "data": {
    "status": "SUCCESS",
    "report": {
      "premature": null,
      "SNB": null,
      "SNT": null,
      "hr": null,
      "diagDescription": "无效数据，请重新采集",
      "diagContent": "结论:\r\n1.无效数据\r\n",
      "reportEcgFragments": null,
      "pdfUrl": "https://ecgdata-1255716792.cos.ap-shanghai.myqcloud.com/oem/1033064347457294336/2609081349599242.pdf?sign=xxx"
    }
  }
}

短程解读报告

由 /api/v1/advanced/interpretation/ecg 申请的解读返回该结构。

字段	类型	说明
`conclusion`	string	医生结论
`labels`	string[]	医生确认的疾病标签，医生未选标签时为空数组。标签字典见 ECG 高阶版 API 中的诊断标签对照表

{
  "errorCode": "0",
  "msg": "成功",
  "data": {
    "status": "SUCCESS",
    "report": {
      "conclusion": "窦性心律，可见房性早搏，未见明显 ST-T 改变。建议心内科门诊复查。",
      "labels": ["SN", "PAC"]
    }
  }
}

两种报告结构完全不同

短程只有 conclusion 与 labels 两个字段；长程是一份与分析结果同构的嵌套对象，另带 pdfUrl。请按申请时用的接口写解析逻辑，不要用同一套字段读两种报告。

错误响应

HTTP 状态	`errorCode`	说明
400	`000018`	解读记录不存在，或该记录不属于当前 API Key
429	`000006`	请求过于频繁

信封 errorCode 恒为 "0"

只要查询请求本身被正确处理，响应信封的 errorCode 就是 "0"。解读失败体现在 data.status = "FAILED"，而不是信封的错误码，请不要把 status = FAILED 当作查询失败去重试。

轮询建议

医生解读是人工过程，时效与医生排班有关，通常在小时级。

提交后至少等待 5 分钟再发起第一次查询，之后每 5～15 分钟查询一次。
总超时按业务需要设置，建议不低于 24 小时。

不要按秒轮询

解读进度由医生决定，高频查询不会让结果更早返回，反而容易触发 000006 频率限制。

支持的分析类型​

计费规则​

解读流程​

接口列表​

Step 1：申请解读​

POST /api/v1/advanced/interpretation/holter​

请求体参数​

请求示例​

POST /api/v1/advanced/interpretation/ecg​

请求体参数​

请求示例​

响应示例​

说明​

错误响应​

Step 2：查询解读结果​

GET /api/v1/advanced/interpretation/result/:interpretationId​

路径参数​

请求示例​

返回字段说明​

status 取值​

解读中示例​

长程解读报告​

短程解读报告​

错误响应​

轮询建议​

支持的分析类型

计费规则

解读流程

接口列表

Step 1：申请解读

POST /api/v1/advanced/interpretation/holter

请求体参数

请求示例

POST /api/v1/advanced/interpretation/ecg

请求体参数

请求示例

响应示例

说明

错误响应

Step 2：查询解读结果

GET /api/v1/advanced/interpretation/result/:interpretationId

路径参数

请求示例

返回字段说明

`status` 取值

解读中示例

长程解读报告

短程解读报告

错误响应

轮询建议