服务端点与路径约定

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://www.toothhelper.tech/detectapi。

口内（统一接口）

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

全景

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

头影侧位（46 个解剖关键点）

curl -X POST "https://www.toothhelper.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://www.toothhelper.tech/detectapi/api/v1/panoramic/detect" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@全景.jpg"

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

3. 影像类型与主要输出

4. 口内影像：输出字段说明

4.1 牙位级异常（teeth[].diseases[] 中的 name）

仅当该牙位上某类异常达到「疑似」或「确证」时，对应条目才会出现。氟牙症不在此数组中，见 4.2 全图级。

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 在多数情况下为空数组。病灶 name 以接口实际返回为准。

下列为英文标识与中文含义对照（便于与文献或内部标注体系对照，不代表接口枚举的完整封闭列表）：

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 服务端产物说明

侧位检测不在服务端生成关键点叠加示意图或标注图片；若业务需要可视化，请由客户端或业务系统根据 landmarks 自行绘制。

6.4 响应与隐私相关字段

成功响应的 JSON 不包含模型版本号，亦不包含模型名称或网络结构等标识字段。侧位成功时 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. 附则

• 生产环境入口以本文 「服务端点与路径约定」 一节及服务提供方最新书面说明为准。
• 访问令牌、单文件大小、并发与限流、日志与审计策略等，均由服务提供方在部署与商务层面约定，本文不逐项展开。