ECG 长程分析 API

长程心电分析（Holter Analysis）支持24小时及以上的连续心电数据分析，提供专业的长程心电报告。

异步处理

长程分析采用异步模式，提交任务后通过轮询或Webhook获取结果。分析时长取决于数据量和分析深度。

分析流程

接口列表

接口	方法	说明
`/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报告
`/api/v1/advanced/ecg/holter/cancel/:task_id`	POST	取消分析任务

Step 1: 获取上传凭证

POST /api/v1/advanced/ecg/holter/upload-url

获取文件上传的预签名URL，用于安全上传大文件。

请求参数

参数	类型	必填	说明
filename	string	✅	文件名（含扩展名）
file_size	number	✅	文件大小（字节）
file_format	string	✅	文件格式：aiecg / edf / mit / csv
duration_hours	number	✅	记录时长（小时）
checksum	string	❌	文件MD5校验值

请求示例

curl -X POST "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "patient_001_24h.aiecg",
    "file_size": 86400000,
    "file_format": "aiecg",
    "duration_hours": 24
  }'

响应示例

{
  "status": "success",
  "data": {
    "task_id": "holter_task_abc123xyz",
    "upload_url": "https://upload.aiecg.com/holter/xxxxx?signature=xxxxx",
    "upload_method": "PUT",
    "upload_headers": {
      "Content-Type": "application/octet-stream"
    },
    "expires_at": "2024-01-15T11:30:00Z",
    "max_file_size": 500000000
  }
}

上传文件

使用返回的 upload_url 上传文件：

curl -X PUT "https://upload.aiecg.com/holter/xxxxx?signature=xxxxx" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @patient_001_24h.aiecg

Step 2: 提交分析任务

POST /api/v1/advanced/ecg/holter/submit

文件上传完成后，提交分析任务。

请求参数

参数	类型	必填	说明
task_id	string	✅	上一步获取的task_id
sampling_rate	number	✅	采样率 (Hz)
gain	number	✅	增益系数
zero_voltage	number	✅	零点电压
patient_info	object	❌	患者信息
analysis_options	object	❌	分析选项
callback_url	string	❌	Webhook回调URL
priority	string	❌	优先级：normal/high/urgent

patient_info 参数

{
  "patient_id": "P001",
  "name": "张三",
  "age": 55,
  "gender": "male",
  "chief_complaint": "心悸、胸闷",
  "medical_history": "高血压病史5年",
  "current_medications": ["阿司匹林", "美托洛尔"]
}

analysis_options 参数

{
  "arrhythmia_detection": true,
  "st_analysis": true,
  "hrv_analysis": true,
  "pacemaker_detection": false,
  "doctor_review": true,
  "report_language": "zh-CN"
}

请求示例

curl -X POST "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "holter_task_abc123xyz",
    "sampling_rate": 256,
    "gain": 1000,
    "zero_voltage": 512,
    "patient_info": {
      "patient_id": "P001",
      "age": 55,
      "gender": "male",
      "chief_complaint": "心悸、胸闷"
    },
    "analysis_options": {
      "arrhythmia_detection": true,
      "st_analysis": true,
      "hrv_analysis": true,
      "doctor_review": true
    },
    "callback_url": "https://your-server.com/webhook/holter",
    "priority": "normal"
  }'

响应示例

{
  "status": "success",
  "data": {
    "task_id": "holter_task_abc123xyz",
    "status": "processing",
    "estimated_completion": "2024-01-15T14:30:00Z",
    "queue_position": 3,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Step 3: 查询任务状态

GET /api/v1/advanced/ecg/holter/status/:task_id

查询分析任务的当前状态。路径参数 task_id 为任务ID。

请求示例

curl -X GET "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/status/holter_task_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "status": "success",
  "data": {
    "task_id": "holter_task_abc123xyz",
    "status": "doctor_reviewing",
    "progress": {
      "overall": 85,
      "stages": {
        "upload": {"status": "completed", "progress": 100},
        "preprocessing": {"status": "completed", "progress": 100},
        "ai_analysis": {"status": "completed", "progress": 100},
        "doctor_review": {"status": "in_progress", "progress": 40}
      }
    },
    "estimated_completion": "2024-01-15T14:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:45:00Z"
  }
}

任务状态说明

状态	说明
`pending`	等待处理
`uploading`	文件上传中
`preprocessing`	数据预处理中
`ai_analyzing`	AI分析中
`doctor_reviewing`	医生审核中（如开启）
`completed`	分析完成
`failed`	分析失败
`cancelled`	已取消

Step 4: 获取分析结果

GET /api/v1/advanced/ecg/holter/result/:task_id

任务完成后，获取详细的分析结果。路径参数 task_id 为任务ID。

请求示例

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

响应示例

{
  "status": "success",
  "data": {
    "task_id": "holter_task_abc123xyz",
    "report_id": "RPT_20240115_001",
    "analysis_time": "2024-01-15T14:28:35Z",
    
    "summary": {
      "recording_duration": "23:45:32",
      "analyzable_duration": "23:30:15",
      "data_quality": "good",
      "overall_conclusion": "窦性心律，偶发室性早搏，偶发房性早搏"
    },
    
    "heart_rate": {
      "total_beats": 102458,
      "average_hr": 72,
      "max_hr": 128,
      "max_hr_time": "2024-01-15T09:23:45Z",
      "min_hr": 52,
      "min_hr_time": "2024-01-15T03:15:22Z",
      "hr_distribution": {
        "below_60": 8.5,
        "60_to_100": 85.2,
        "above_100": 6.3
      }
    },
    
    "arrhythmia": {
      "summary": {
        "total_abnormal_beats": 856,
        "abnormal_percentage": 0.84
      },
      "ventricular": {
        "pvc_count": 523,
        "pvc_per_hour": 22.1,
        "pvc_singles": 498,
        "pvc_pairs": 12,
        "pvc_runs": 1,
        "longest_pvc_run": 3,
        "r_on_t": 0
      },
      "supraventricular": {
        "pac_count": 333,
        "pac_per_hour": 14.1,
        "pac_singles": 320,
        "pac_pairs": 6,
        "pac_runs": 1,
        "longest_pac_run": 4
      },
      "atrial_fibrillation": {
        "detected": false,
        "episodes": 0,
        "total_duration": 0,
        "burden_percentage": 0
      },
      "pauses": {
        "count": 2,
        "longest_pause": 2.1,
        "longest_pause_time": "2024-01-15T04:22:33Z"
      }
    },
    
    "st_segment": {
      "st_depression_episodes": 3,
      "st_elevation_episodes": 0,
      "max_depression": -1.2,
      "max_depression_time": "2024-01-15T11:45:00Z",
      "total_ischemic_time": "00:15:30",
      "ischemic_burden": 1.1
    },
    
    "hrv": {
      "time_domain": {
        "sdnn": 128,
        "sdnn_index": 52,
        "sdann": 112,
        "rmssd": 32,
        "pnn50": 8.5
      },
      "frequency_domain": {
        "total_power": 3250,
        "vlf": 1850,
        "lf": 920,
        "hf": 480,
        "lf_hf_ratio": 1.92
      },
      "interpretation": "HRV指标正常，自主神经功能良好"
    },
    
    "representative_strips": [
      {
        "type": "normal_sinus",
        "time": "2024-01-15T08:30:00Z",
        "description": "正常窦性心律",
        "strip_url": "https://api.heartvoice.com.cn/strips/xxx_normal.png"
      },
      {
        "type": "pvc",
        "time": "2024-01-15T10:15:22Z",
        "description": "室性早搏",
        "strip_url": "https://api.heartvoice.com.cn/strips/xxx_pvc.png"
      },
      {
        "type": "max_hr",
        "time": "2024-01-15T09:23:45Z",
        "description": "最快心率 128 BPM",
        "strip_url": "https://api.heartvoice.com.cn/strips/xxx_max_hr.png"
      },
      {
        "type": "min_hr",
        "time": "2024-01-15T03:15:22Z",
        "description": "最慢心率 52 BPM",
        "strip_url": "https://api.heartvoice.com.cn/strips/xxx_min_hr.png"
      },
      {
        "type": "pause",
        "time": "2024-01-15T04:22:33Z",
        "description": "最长停搏 2.1秒",
        "strip_url": "https://api.heartvoice.com.cn/strips/xxx_pause.png"
      }
    ],
    
    "diagnosis": {
      "primary": [
        "窦性心律",
        "偶发室性早搏",
        "偶发房性早搏"
      ],
      "secondary": [
        "夜间心率正常下降",
        "无明显ST段改变"
      ],
      "risk_assessment": {
        "arrhythmia_risk": "low",
        "ischemia_risk": "low",
        "overall_risk": "low"
      }
    },
    
    "recommendations": [
      {
        "priority": "low",
        "category": "follow_up",
        "content": "早搏数量在正常范围，建议定期复查"
      },
      {
        "priority": "medium",
        "category": "lifestyle",
        "content": "避免过度劳累和熬夜，保持规律作息"
      },
      {
        "priority": "low",
        "category": "monitoring",
        "content": "如有心悸加重，建议及时复查"
      }
    ],
    
    "reviewer": {
      "ai_model": "AIECG-Holter-v2.1",
      "ai_confidence": 0.94,
      "doctor_reviewed": true,
      "doctor_id": "DR_001",
      "review_time": "2024-01-15T14:20:00Z"
    }
  }
}

Step 5: 下载PDF报告

GET /api/v1/advanced/ecg/holter/report/:task_id

获取标准格式的PDF报告下载链接。路径参数 task_id 为任务ID。

请求参数

参数	类型	必填	说明
format	string	❌	报告格式：pdf(默认)/html
template	string	❌	报告模板：standard/detailed/summary

请求示例

curl -X GET "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/report/holter_task_abc123xyz?format=pdf&template=standard" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

{
  "status": "success",
  "data": {
    "report_url": "https://reports.aiecg.com/holter/xxx.pdf?token=xxx",
    "expires_at": "2024-01-15T18:00:00Z",
    "file_size": 2458624,
    "pages": 8
  }
}

Webhook 回调

如果在提交任务时指定了 callback_url，任务完成或失败时会发送Webhook通知。

Webhook 请求体

{
  "event": "holter_analysis_completed",
  "task_id": "holter_task_abc123xyz",
  "status": "completed",
  "timestamp": "2024-01-15T14:28:35Z",
  "data": {
    "report_id": "RPT_20240115_001",
    "summary": "窦性心律，偶发室性早搏，偶发房性早搏",
    "result_url": "https://api.heartvoice.com.cn/api/v1/advanced/ecg/holter/result/holter_task_abc123xyz"
  },
  "signature": "sha256=xxxxxxxx"
}

验证签名

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

支持的数据格式

AIECG 格式（推荐）

我们的专有格式，支持高效压缩和完整元数据。

{
  "format": "aiecg",
  "version": "1.0",
  "header": {
    "sampling_rate": 256,
    "gain": 1000,
    "zero_voltage": 512,
    "duration_seconds": 86400,
    "start_time": "2024-01-14T10:00:00Z"
  },
  "data": [512, 515, 520, ...]
}

EDF/EDF+ 格式

标准的欧洲数据格式，广泛用于医疗设备。

MIT-BIH 格式

PhysioNet标准格式，包含 .dat 和 .hea 文件。

CSV 格式

简单的逗号分隔格式，需包含时间戳列。

代码示例

JavaScript
Python

import { AIECG } from '@aiecg/sdk';
import fs from 'fs';

const client = new AIECG('YOUR_API_KEY');

async function analyzeHolter(filePath) {
  // 1. 获取上传凭证
  const uploadInfo = await client.holter.getUploadUrl({
    filename: 'patient_24h.aiecg',
    fileSize: fs.statSync(filePath).size,
    fileFormat: 'aiecg',
    durationHours: 24
  });
  
  // 2. 上传文件
  await client.holter.uploadFile(uploadInfo.upload_url, filePath);
  
  // 3. 提交分析任务
  const task = await client.holter.submit({
    taskId: uploadInfo.task_id,
    samplingRate: 256,
    gain: 1000,
    zeroVoltage: 512,
    patientInfo: { age: 55, gender: 'male' },
    analysisOptions: { doctorReview: true }
  });
  
  console.log(`任务已提交: ${task.task_id}`);
  
  // 4. 轮询状态
  let status;
  do {
    await new Promise(r => setTimeout(r, 30000)); // 30秒轮询
    status = await client.holter.getStatus(task.task_id);
    console.log(`进度: ${status.progress.overall}%`);
  } while (status.status !== 'completed' && status.status !== 'failed');
  
  // 5. 获取结果
  if (status.status === 'completed') {
    const result = await client.holter.getResult(task.task_id);
    console.log(`诊断: ${result.diagnosis.primary.join(', ')}`);
    
    // 下载PDF报告
    const report = await client.holter.downloadReport(task.task_id);
    console.log(`报告下载: ${report.report_url}`);
  }
}

import aiecg
import time

client = aiecg.Client(api_key='YOUR_API_KEY')

def analyze_holter(file_path):
    # 1. 获取上传凭证
    upload_info = client.holter.get_upload_url(
        filename='patient_24h.aiecg',
        file_format='aiecg',
        duration_hours=24
    )
    
    # 2. 上传文件
    client.holter.upload_file(upload_info['upload_url'], file_path)
    
    # 3. 提交分析任务
    task = client.holter.submit(
        task_id=upload_info['task_id'],
        sampling_rate=256,
        gain=1000,
        zero_voltage=512,
        patient_info={'age': 55, 'gender': 'male'},
        analysis_options={'doctor_review': True}
    )
    
    print(f"任务已提交: {task['task_id']}")
    
    # 4. 轮询状态
    while True:
        time.sleep(30)  # 30秒轮询
        status = client.holter.get_status(task['task_id'])
        print(f"进度: {status['progress']['overall']}%")
        
        if status['status'] in ['completed', 'failed']:
            break
    
    # 5. 获取结果
    if status['status'] == 'completed':
        result = client.holter.get_result(task['task_id'])
        print(f"诊断: {', '.join(result['diagnosis']['primary'])}")
        
        # 下载PDF报告
        report = client.holter.download_report(task['task_id'])
        print(f"报告下载: {report['report_url']}")

# 使用
analyze_holter('/path/to/patient_24h.aiecg')

定价

分析类型	高阶版价格
24小时Holter	¥50/次
48小时Holter	¥80/次
7天Holter	¥150/次

分析流程​

接口列表​

Step 1: 获取上传凭证​

POST /api/v1/advanced/ecg/holter/upload-url​

请求参数​

请求示例​

响应示例​

上传文件​

Step 2: 提交分析任务​

POST /api/v1/advanced/ecg/holter/submit​

请求参数​

patient_info 参数​

analysis_options 参数​

请求示例​

响应示例​

Step 3: 查询任务状态​

GET /api/v1/advanced/ecg/holter/status/:task_id​

请求示例​

响应示例​

任务状态说明​

Step 4: 获取分析结果​

GET /api/v1/advanced/ecg/holter/result/:task_id​

请求示例​

响应示例​

Step 5: 下载PDF报告​

GET /api/v1/advanced/ecg/holter/report/:task_id​

请求参数​

请求示例​

响应示例​

Webhook 回调​

Webhook 请求体​

验证签名​

支持的数据格式​

AIECG 格式（推荐）​

EDF/EDF+ 格式​

MIT-BIH 格式​

CSV 格式​

代码示例​

定价​

相关文档​

分析流程

接口列表

Step 1: 获取上传凭证

POST /api/v1/advanced/ecg/holter/upload-url

请求参数

请求示例

响应示例

上传文件

Step 2: 提交分析任务

POST /api/v1/advanced/ecg/holter/submit

请求参数

patient_info 参数

analysis_options 参数

请求示例

响应示例

Step 3: 查询任务状态

GET /api/v1/advanced/ecg/holter/status/:task_id

请求示例

响应示例

任务状态说明

Step 4: 获取分析结果

GET /api/v1/advanced/ecg/holter/result/:task_id

请求示例

响应示例

Step 5: 下载PDF报告

GET /api/v1/advanced/ecg/holter/report/:task_id

请求参数

请求示例

响应示例

Webhook 回调

Webhook 请求体

验证签名

支持的数据格式

AIECG 格式（推荐）

EDF/EDF+ 格式

MIT-BIH 格式

CSV 格式

代码示例

定价

相关文档