PetVital AI 量測 API

概覽

對狗、貓做非接觸式生命徵象量測。上傳一段拍到寵物臉部的影片，回傳心率、呼吸率、心率變異與壓力指數。

原理是 rPPG（遠端光體積變化描記法）：血液流過皮下微血管時，反射光會有極細微的週期性變化，從影片的顏色訊號還原出脈搏波形。伺服器端採 CHROM 與 POS 兩種色彩空間投影混合，再以帶通濾波與頻譜分析取出心率與呼吸率。

本 API 與 PetVital 網頁版共用同一份演算法程式碼，兩邊算出的數值一致。

服務位址

https://api-pet.zconai.com

自行部署時請換成貴司主機位址，路徑不變。

限制

• 影片上限 48 MB，超過回 413
• 有效影格不足 64 張（約 2 秒）無法計算，回 400
• 一支 15 秒影片處理時間約 2 秒

快速開始

拍一段 15 秒的狗臉影片，直接送出：

curl -X POST https://api-pet.zconai.com/api/v1.0/measure \
     -F video=@dog.mp4 \
     -F species=dog

回傳：

{
  "ok": true,
  "version": "1.0.0",
  "data": {
    "hr": 98, "rr": 21, "sqi": 60,
    "sdnn": 51, "rmssd": 29, "lfhf": 0.11, "stress": 57,
    "peaks": 26,
    "meta": { "frames_used": 450, "elapsed_ms": 1877 }
  },
  "reference": { "hr": [60, 140], "rr": [10, 30] }
}

下方每個端點都可以直接用貴司自己的影片試打。

認證

讀取服務設定中…

若貴司的部署有開啟金鑰驗證，每次呼叫需帶其中一種標頭：

X-API-Key: <金鑰>
Authorization: Bearer <金鑰>

金鑰不符回 401。金鑰由日康提供，設定在容器的 API_KEYS 環境變數。

影片量測

上傳影片，回傳完整量測結果。結尾有沒有斜線都可以。

請求參數

以 multipart/form-data 送出；或用 application/json，把影片放在 video_base64。

cURL 範例

curl -X POST https://api-pet.zconai.com/api/v1.0/measure \
     -F video=@cat.mp4 \
     -F species=cat \
     -F waveform=true

JSON（Base64）範例

curl -X POST https://api-pet.zconai.com/api/v1.0/measure \
     -H "Content-Type: application/json" \
     -d '{"video_base64":"AAAAIGZ0eXBpc29t...","species":"dog"}'

RGB 序列量測

前端已經自己算好取樣區域平均色時走這條，不必上傳影片。

裝置端逐格取出 ROI 的平均 RGB，只送三串數字上來。一段 15 秒的量測約 40 KB，比影片省兩個數量級的頻寬，適合行動網路或攝影機端直傳。

curl -X POST https://api-pet.zconai.com/api/v1.0/measure/series \
     -H "Content-Type: application/json" \
     -d '{"r":[141.2,141.5],"g":[122.4,122.9],"b":[101.1,101.3],"species":"dog","fps":30}'

取樣區域要固定，不要每格重新定位，否則訊號會被位移汙染。建議取畫面中央偏上、涵蓋鼻口的矩形。

參數查詢

回傳演算法使用的頻帶與各物種正常區間，不需要參數。

健康檢查

給負載平衡器或容器健康檢查用，回傳版本與已運行秒數。

curl https://api-pet.zconai.com/health
{"ok":true,"version":"1.0.0","uptime":3721}

回應欄位

這些數值是健康趨勢參考，不是醫療診斷依據。動物臨床判讀請由獸醫師執行。

錯誤碼

失敗時一律回這個格式：

{"ok":false,"error":{"code":"NO_VIDEO","message":"請以 multipart 欄位 video 或 JSON video_base64 上傳影片"}}

拍攝建議

量測準度九成取決於影片品質。以下條件差別很大：

• 長度 15 秒、30 fps。低於 5 秒心率變異會失去意義。
• 解析度 640×480 以上。伺服器會統一縮到 320×240 取樣，更高解析度不會更準，但太低會不足。
• 鼻口入鏡並填滿畫面中央。毛色淺、皮膚薄的部位訊號最強。
• 光線充足且穩定。日光燈與螢幕的閃爍會混進訊號，室內建議用連續光源。
• 鏡頭與寵物盡量不動。晃動的影格會被自動跳過，跳太多就會回 INSUFFICIENT_DATA。
• 關掉自動曝光與自動白平衡。中途變更曝光等同在訊號裡插入一個階躍。

回應的 sqi 與 meta.frames_skipped_motion 可以拿來當拍攝品質的即時回饋，引導使用者重拍。

自行部署

本服務以 Docker image 交付，內含 Node.js 執行環境與 ffmpeg，不需要另外安裝相依套件。

系統需求

• Linux 主機，Docker Engine 20.10 以上、Docker Compose v2
• 建議 2 vCPU / 4 GB 以上
• 對外服務請自行在前面架 nginx 與 SSL

部署步驟

docker load -i petvital-api-1.0.0.tar.gz
docker compose up -d
curl http://127.0.0.1:8080/health

docker-compose.yml

services:
  petvital-api:
    image: petvital-api:1.0.0
    container_name: petvital-api
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      NODE_ENV: production
      PORT: "8080"
      MAX_UPLOAD_MB: "48"
      # API_KEYS: "your-key"   # 需要金鑰驗證時填入，逗號分隔

部署完成後，本文件頁面會一併掛在該主機的根路徑，可直接在內網用它試打。