API Overview

Basic information

Base URL: https://api.heartvoice.com.cn

All requests must include the API Key in the Header:

Authorization: Bearer YOUR_API_KEY

---

ECG endpoints

Basic tier endpoints

Endpoint	Method	Description	Tier requirement
/api/v1/basic/ecg/1-lead/analyze	POST	Single-lead ECG analysis	Basic+
/api/v1/basic/ecg/12-lead/analyze	POST	12-lead ECG analysis	Basic+

Input parameters

• Single-lead: ecgData (array), ecgSampleRate, adcGain, adcZero
• 12-lead: dataI/II/III/AVR/AVL/AVF, data1-6 (V1-V6), ecgSampleRate, adcGain, adcZero
• Note: For each lead, the ECG signal data length must be within 10s–300s. The sampling rate must be greater than 0. Gain default is 1.0, and zero/baseline default is 0.0.

Output results

• Diagnosis label list (diagnosis)
• Signal quality grade (sqGrade)
• Whether the lead is reversed/miswired (isReverse)
• Whether it is abnormal (isAbnormal)
• ECG parameters (avgHr, avgQrs, prInterval, avgQt, avgP, avgQtc)
• PAC/PVC counts (pacCount, pvcCount)

📖 View detailed document

---

Advanced tier endpoints

Endpoint	Method	Description	Tier requirement
/api/v1/advanced/ecg/analyze	POST	Full ECG analysis	Advanced
/api/v1/advanced/ecg/heart-age	POST	Heart age assessment	Advanced
/api/v1/advanced/ecg/mental-state	POST	Mental/emotional state assessment	Advanced
/api/v1/advanced/ecg/deepLife	POST	Micro health check	Advanced

Full ECG analysis includes:

• ✅ All Basic-tier analysis results
• ✅ Heart age (heartAge)
• ✅ Respiratory rate (respiratoryRate)
• ✅ HRV (hrv)
• ✅ Pressure index (pressure)
• ✅ Emotion index (emotion)
• ✅ Fatigue index (fatigue)
• ✅ Vitality index (vitality)

Heart age assessment provides:

• Heart age value
• Signal quality rating

Mental/emotional state assessment provides:

• Pressure index and emotion index
• Fatigue index and vitality index

Micro health check provides:

• Risk analysis for nine major system diseases (anyEcg)
• Mapping structure: body system → phecode condition code → risk probability and grade

📖 View detailed document

---

Long-term ECG analysis endpoints (asynchronous)

Endpoint	Method	Description	Tier requirement
/api/v1/advanced/ecg/holter/upload-url	POST	Get file upload credential	Advanced
/api/v1/advanced/ecg/holter/submit	POST	Submit long-term analysis task	Advanced
/api/v1/advanced/ecg/holter/status/:task_id	GET	Query task status	Advanced
/api/v1/advanced/ecg/holter/result/:task_id	GET	Get analysis results	Advanced
/api/v1/advanced/ecg/holter/report/:task_id	GET	Download PDF report	Advanced

Long-term ECG (Holter) analysis highlights:

• ✅ Supports continuous ECG data from 24 hours up to 7 days
• ✅ Asynchronous processing with optional Webhook callbacks
• ✅ Comprehensive arrhythmia statistics (e.g., PAC/PVC/AF)
• ✅ ST-segment analysis and HRV analysis
• ✅ Representative ECG image segments
• ✅ Optional physician manual review (Ultra tier)
• ✅ Standard-format PDF reports

📖 View detailed document

---

PPG endpoints

Advanced tier endpoints

Endpoint	Method	Description	Tier requirement
/api/v1/advanced/ppg/blood-pressure	POST	Blood pressure estimation	Advanced
/api/v1/advanced/ppg/vascular-health	POST	Vascular health assessment	Advanced

Blood pressure estimation input:

• ECG data (ecgData, ecgSampleRate, adcGain, adcZero)
• PPG data (ppgData object: red, green, infrared)
• PPG sampling rate (ppgSampleRate)

Blood pressure estimation output:

• Signal quality (sqGrade)
• Systolic blood pressure (sbp)
• Diastolic blood pressure (dbp)

Vascular health assessment input:

• ECG data (ecgData, ecgSampleRate, adcGain, adcZero)
• PPG data (ppgData object: red, green, infrared)
• PPG sampling rate (ppgSampleRate)

Vascular health assessment output:

• Signal quality (sqGrade)
• Vascular age (vascularAge)

PPG data format

PPG data must provide three light-source channels:

• red: red light data array
• green: green light data array
• infrared: infrared light data array

📖 View detailed document

---

Common response fields

Signal Quality Grade (sqGrade)

Most analysis endpoints return the sqGrade field to indicate the quality grade of the input signal:

sqGrade value	Grade	Description	Recommendation
> 0.9	Excellent	Signal quality is excellent	High confidence in results
0.7–0.9	Good	Signal quality is good	Results are generally reliable
0.5–0.7	Fair	Signal quality is average	Consider re-acquiring the signal
< 0.5	Unanalyzable	Signal quality is too low	Effective analysis is not possible; re-acquire

Factors affecting signal quality:

• Poor electrode contact
• Body movement / muscle tremor
• Electromagnetic interference (e.g., power-frequency interference)
• Acquisition device issues
• Poor lead-wire contact

Recommendations to improve signal quality:

1. Ensure good contact between electrodes/sensors and the skin
2. Keep still and relax muscles
3. Stay away from strong electromagnetic interference sources
4. Check that device connections are normal
5. Clean the skin and, if needed, use conductive gel/paste

---

Status code meanings

Status code	Meaning	Suggested handling
200	Success	-
400	Request parameter error	Check parameter format and required fields
401	Authentication failed	Check whether the API Key is correct
403	Insufficient permissions	Upgrade your tier or check your quota
429	Too many requests	Reduce request frequency and retry later
500	Server error	Contact technical support

---

Error response format

{
  "errorCode": "000004",
  "msg": "API Key is invalid or expired"
}

Common error codes

Error code	Description	Solution
000004	Invalid API Key	Check whether the Key is correct
000005	Quota exhausted	Contact technical support
000006	Rate limit triggered	Reduce request frequency
000007	No endpoint permission	Upgrade to the matching tier
000010	Signal duration out of allowed range	Increase or decrease data length
000011	Illegal sampling rate	Provide a correct sampling rate
000012	Empty signal data	Send non-empty signal data for analysis
000013	PPG multi-channel signal lengths are inconsistent	Keep all PPG signal channel lengths the same

---

Tier permissions (capabilities)

Endpoint group	Basic tier	Advanced tier
Single-lead ECG analysis	✅ 1,000 times/day	✅ 50,000 times/day
12-lead ECG analysis	✅	✅
Full ECG analysis	❌	✅
Heart age assessment	❌	✅
Mental/emotional state assessment	❌	✅
DeepLife micro health check	❌	✅
Long-term ECG analysis	❌	✅

---

Next steps

• ECG Basic detailed document
• ECG Advanced detailed document
• Authentication
• Service & Pricing