服務端點與路徑約定

Base URL 由協議、主機名及（如有）網關前綴組成，不包含業務路徑（如 /api/v1/...）。調用時將下文各接口的相對路徑拼接到 Base URL 之後。

常用完整 URL（生產示例）

約定

• Base URL 末尾請勿重複 /，以免出現 .../detectapi//api/... 等錯誤拼接。
• 若使用獨立部署或定製域名，請將上表中的示例根地址整體替換為服務提供方書面確認的根地址；接口路徑 /api/v1/... 與 /health 通常保持不變。

1. 接口一覽

1.1 健康檢查 GET /health

用於運維監控、負載均衡探活等場景，用於確認檢測服務進程是否可達。不接收影像文件、不執行推理。業務側進行口內/全景/側位檢測時無需調用本接口。

2. 調用方式

2.1 請求約定

2.2 表單字段

2.3 鑑權

若服務提供方已啓用訪問控制，請在請求頭攜帶：

Authorization: Bearer <TOKEN>

<TOKEN> 由服務提供方分配。未攜帶或校驗失敗時，返回 HTTP 401，error_code 為 UNAUTHORIZED。

2.4 請求示例（生產 Base URL 示例）

將 <TOKEN> 替換為實際密鑰；以下 Base URL 為 https://api.dusheng.tech/detectapi。

口內（統一接口）

curl -X POST "https://api.dusheng.tech/detectapi/api/v1/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@口內照.jpg" \
  -F "image_type=intraoral" \
  -F "lang=zh"

全景

curl -X POST "https://api.dusheng.tech/detectapi/api/v1/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@全景.jpg" \
  -F "image_type=panoramic" \
  -F "lang=zh"

頭影側位（46 個解剖關鍵點）

curl -X POST "https://api.dusheng.tech/detectapi/api/v1/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@側位.jpg" \
  -F "image_type=cephalometric" \
  -F "lang=zh"

固定類型路由（可不傳 image_type）

curl -X POST "https://api.dusheng.tech/detectapi/api/v1/panoramic/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@全景.jpg"

curl -X POST "https://api.dusheng.tech/detectapi/api/v1/cephalometric/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@側位.jpg"

3. 影像類型與主要輸出

4. 口內影像：輸出字段説明

4.1 牙位級異常（teeth[].diseases[] 中的 name）

僅當該牙位上某類異常達到「疑似」或「確證」時，對應條目才會出現。氟牙症不在此數組中，見 4.2 全圖級。

當前口內牙位級模型覆蓋下列疾病（name 為中文；lang=en 時同條目中提供 name_en）：

與全圖級「牙列擁擠」的區別：傾斜牙 / 扭曲牙 為單牙檢測結果，出現在 teeth[].diseases[]；牙列擁擠 為整圖結論，出現在 image_level_diseases[]，二者可同時存在、互不替代。

4.2 全圖級結論（image_level_diseases[] 中的 name）

4.3 算法表現與適用範圍

算法輸出受影像質量、拍攝條件、患者個體及算法版本等多因素影響。本文檔不提供作為合同或驗收依據的固定準確率承諾；若需定量評測報告或驗收指標，請與服務提供方另行約定並獲取書面材料。

5. 全景片：幾何字段與病灶命名

5.1 牙齒與分割

• teeth[]：包含牙位（fdi）、幾何描述 segmentation（在輪廓可用時為多邊形，否則可為外接矩形等，以實際返回為準）。

5.2 segmentation 與輪廓相關字段

全景牙位分割在具備掩膜輸出時，接口可在每顆牙的 segmentation.polygons_raw 中返回未經展示後處理的原始輪廓，便於接入方自行進行柵格化或幾何運算。用於界面展示的 polygons 可能經過簡化或質量過濾，與 polygons_raw 不必一致。當 segmentation.mode 為 polygon 時，通常提供展示用 polygons；否則可能退化為 bbox，此時 polygons 可為 null。接口不返回整幅圖像的 H×W 二值掩膜數組。

5.3 病灶

病灶位於 teeth[].diseases[]。全景場景下 image_level_diseases 在多數情況下為空數組。

與口內不同：全景病灶由單模型多類檢測輸出，部分類別在 JSON 中可能以 英文 snake_case（如 impacted_tooth）作為 name 返回；口內牙位級 name 以中文規範名為主（見第 4.1 節）。集成時請以實際返回為準。

下列為英文標識與中文含義對照（便於與文獻或內部標註體系對照，不代表接口枚舉的完整封閉列表）：

5.4 算法表現與適用範圍

同第 4.3 節：全景算法輸出受數據與版本等因素影響，不作為臨牀金標準。定量指標與正式評測口徑請向服務提供方索取。

6. 頭影側位：landmarks 與座標

6.1 座標系

與口內、全景一致，頂層 coordinate_system 約定為：原點在上傳圖像左上角，x 軸向右、y 軸向下，單位為像素。

6.2 關鍵點配置

當前接口對頭影側位僅輸出 46 個關鍵點。landmark_num / ceph_landmark_num 若傳入非支持取值，將返回 error_code: INVALID_LANDMARK_NUM（HTTP 400）。不傳上述字段時，行為與當前線上默認配置一致。

6.3 對接與可視化説明

成功響應以結構化 JSON 返回檢測結果，便於直接入庫、展示或與 HIS／影像工作站等系統對接。若需在畫面上疊加側位關鍵點或文字標註，可將 landmarks 中的 x、y、valid、name 等與本地持有的影像進行對齊繪製即可。

6.4 meta（側位）

側位成功時，meta 中會給出 landmark_num（當前為 46），以及與其他影像類型接口保持一致的 disease_models_failed 字段（側位場景下多為空數組）。其餘擴展鍵若隨版本有所調整，以線上實際返回為準。

6.5 landmarks 數組元素

側位場景下 teeth 與 image_level_diseases 均為空數組。

6.6 summary（側位）

側位成功時，summary 提供 total_landmarks（關鍵點總數，與 landmarks 長度一致）與 visible_landmarks（valid 為 true 的點數），便於快速瞭解本次頭影分析覆蓋了多少個解剖點及其可信數量；與口內／全景中的牙位統計字段不同，屬接口設計上的正常差異。

7. 響應 JSON 結構説明

7.1 頂層常用字段

7.2 口內 / 全景：teeth[] 與 diseases[]（摘要）

7.3 口內成功響應示例（節選）

{
  "success": true,
  "image_type": "intraoral",
  "inference_status": "ok",
  "error": null,
  "error_code": null,
  "request_id": "intraoral_20260504_165326_92967e50",
  "elapsed_ms": 8420,
  "coordinate_system": {
    "origin": "top_left",
    "x_axis": "right",
    "y_axis": "down",
    "unit": "pixel",
    "bbox_format": "xyxy_absolute"
  },
  "image": { "width": 1920, "height": 1080 },
  "teeth": [
    {
      "fdi": "11",
      "tooth_bbox": [100.0, 200.0, 180.0, 320.0],
      "segmentation": { "mode": "polygon", "bbox": [100.0, 200.0, 180.0, 320.0], "polygons": [[[102.1, 205.3]]] },
      "status": "確證",
      "diseases": [
        {
          "name": "齲齒",
          "name_en": "Caries",
          "status": "確證",
          "confidence": 0.88,
          "bbox": [110.0, 220.0, 160.0, 300.0],
          "geometry": { "type": "bbox", "bbox": [110.0, 220.0, 160.0, 300.0], "polygons": null }
        }
      ]
    }
  ],
  "image_level_diseases": [],
  "summary": {
    "total_teeth_detected": 28,
    "diseased_teeth_count": 3,
    "disease_counts": { "齲齒": 2 }
  },
  "meta": {}
}

（meta 及全圖級字段以實際環境為準。）

7.4 全景成功響應示例（節選）

{
  "success": true,
  "image_type": "panoramic",
  "inference_status": "ok",
  "error": null,
  "error_code": null,
  "request_id": "panoramic_20260504_143022_e4f5a6b7",
  "elapsed_ms": 15200,
  "coordinate_system": {
    "origin": "top_left",
    "x_axis": "right",
    "y_axis": "down",
    "unit": "pixel",
    "bbox_format": "xyxy_absolute"
  },
  "image": { "width": 3000, "height": 1200 },
  "teeth": [
    {
      "fdi": "36",
      "tooth_bbox": [1400.0, 520.0, 1580.0, 780.0],
      "segmentation": {
        "mode": "bbox",
        "bbox": [1400.0, 520.0, 1580.0, 780.0],
        "polygons": null,
        "polygons_raw": [[[1405.0, 525.0], [1575.0, 530.0], [1560.0, 770.0], [1410.0, 765.0]]]
      },
      "tooth_conf": 0.86,
      "position_zh": "左下第一磨牙",
      "status": "疑似",
      "diseases": [
        {
          "name": "齲齒",
          "name_en": "Caries",
          "status": "疑似",
          "confidence": 0.42,
          "bbox": [1420.0, 560.0, 1550.0, 700.0],
          "iou": 0.35,
          "geometry": {
            "type": "bbox",
            "bbox": [1420.0, 560.0, 1550.0, 700.0],
            "polygons": null
          }
        }
      ]
    }
  ],
  "image_level_diseases": [],
  "summary": {
    "total_teeth_detected": 28,
    "diseased_teeth_count": 5,
    "disease_counts": { "齲齒": 3, "根尖周病變": 1 }
  },
  "meta": {}
}

（牙數、統計字段及 polygons / polygons_raw 是否出現，以實際推理結果為準。）

7.5 側位成功響應示例（節選）

{
  "success": true,
  "image_type": "cephalometric",
  "inference_status": "ok",
  "error": null,
  "error_code": null,
  "request_id": "cephalometric_20260504_120000_a1b2c3d4",
  "elapsed_ms": 1200,
  "coordinate_system": {
    "origin": "top_left",
    "x_axis": "right",
    "y_axis": "down",
    "unit": "pixel",
    "bbox_format": "xyxy_absolute"
  },
  "image": { "width": 2400, "height": 3000 },
  "teeth": [],
  "landmarks": [
    {
      "index": 0,
      "name": "A",
      "definition_zh": "Subspinale / A point，上頜前部骨性輪廓的最深凹點。",
      "x": 1120.5,
      "y": 580.2,
      "valid": true
    },
    {
      "index": 1,
      "name": "ANS",
      "definition_zh": "Anterior nasal spine，前鼻棘尖端。",
      "x": null,
      "y": null,
      "valid": false
    }
  ],
  "image_level_diseases": [],
  "summary": {
    "total_landmarks": 46,
    "visible_landmarks": 44
  },
  "meta": {
    "landmark_num": 46,
    "disease_models_failed": []
  }
}

（示例中 landmarks 僅展示前兩項；完整數組長度為 46，與 summary.total_landmarks 及 meta.landmark_num 一致。）

8. 常見錯誤碼

失敗響應中仍可能包含 request_id、elapsed_ms、coordinate_system 等字段，便於定位問題。

9. 附則

• 生產環境入口以本文 「服務端點與路徑約定」 一節及服務提供方最新書面説明為準。
• 訪問令牌、單文件大小、併發與限流、日誌與審計策略等，均由服務提供方在部署與商務層面約定，本文不逐項展開。