Documentation

Service Endpoints and Path Rules

Base URL consists of the protocol, host name, and, if present, the gateway prefix. It does not includebusiness paths such as /api/v1/.... When calling the service, append each endpoint’s relative path to the Base URL.

Environment	Base URL（example）
Production (current convention)	`https://www.toothhelper.tech/detectapi`

API integration details

Purpose	Full URL
Unified detection	`https://www.toothhelper.tech/detectapi/api/v1/detect`
API integration details	`https://www.toothhelper.tech/detectapi/api/v1/intraoral/detect`
API integration details	`https://www.toothhelper.tech/detectapi/api/v1/panoramic/detect`
API integration details	`https://www.toothhelper.tech/detectapi/api/v1/cephalometric/detect`
Health check	`https://www.toothhelper.tech/detectapi/health`

API integration details

Base URL Do not repeat a trailing slash at the end of the Base URL / to avoid malformed URLs such as .../detectapi//api/... .
If using independent deployment or a custom domainAPI integration details confirmed in writing by the service provider; endpoint paths such as /api/v1/... API integration details /health usually remain unchanged.

1. API Overview

Method	relative path	Description
POST	`/api/v1/detect`	RecommendedAPI integration details `image_type` API integration details
POST	`/api/v1/intraoral/detect`	API integration details `image_type`
POST	`/api/v1/panoramic/detect`	API integration details `image_type`
POST	`/api/v1/cephalometric/detect`	API integration details `image_type`
GET	`/health`	Service availability probe; see below

1.1 Health Check `GET /health`

Used for operations monitoring and load-balancer health probesAPI integration detailsIt does not accept image files or perform inferenceAPI integration details does not need to call this endpoint.

2. Calling Method

2.1 Request Conventions

Item	API integration details
Content-Type	`multipart/form-data`
Image format	`jpg`、`jpeg`、`png`
Single file size	The upper limit is configured by the service provider at the deployment layer; oversized files return `FILE_TOO_LARGE` (HTTP 413, depending on the actual gateway).

API integration details

Field	Required	Description
`file`	Yes	Image file to be detected
`image_type`	When using `/api/v1/detect` , Required	`intraoral`（intraoral）、`panoramic`（panoramic）、`cephalometric`API integration details
`landmark_num`	No	Only valid when `image_type=cephalometric` API integration detailsAPI integration details `46`API integration details `INVALID_LANDMARK_NUM`
`ceph_landmark_num`	No	API integration details `landmark_num` has the same meaning; use either one
`lang`	No	`zh` (default) or `en`

2.3 Authentication

API integration details

Authorization: Bearer <TOKEN>

<TOKEN> API integration details HTTP 401，error_code as UNAUTHORIZED。

API integration details

Replace <TOKEN> API integration details https://www.toothhelper.tech/detectapi。

API integration details

API integration details

panoramic

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

API integration details

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

Fixed-type routes (image_type can be omitted `image_type`）

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

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

3. Image Types and Main Outputs

`image_type`	Image type	Main outputs
`intraoral`	API integration details	API integration details
`panoramic`	API integration details	API integration details
`cephalometric`	API integration details	An array of `landmarks` landmarks aligned to the image pixel coordinate system (46 pointsAPI integration details

API integration details

API integration details`teeth[].diseases[]` API integration details `name`）

API integration detailsDental FluorosisAPI integration details

Chinese `name`（example）
caries
Tooth Wear
Wedge-Shaped Defect
Residual Crown
Gingival Recession

API integration details`image_level_diseases[]` API integration details `name`）

Chinese `name`（example）
Dental Crowding
Dental Calculus
API integration details
API integration details
Dental Fluorosis

API integration details

API integration detailsAPI integration detailsAPI integration detailsAPI integration detailsAPI integration detailsservice providerAPI integration details

API integration details

teeth[]API integration detailsfdiAPI integration details segmentationAPI integration details

5.2 `segmentation` API integration details

API integration details segmentation.polygons_raw API integration detailsAPI integration detailsAPI integration details polygons API integration details polygons_raw API integration details segmentation.mode as polygon API integration details polygonsAPI integration details bboxAPI integration details polygons API integration details nullAPI integration detailsAPI integration detailsAPI integration details

5.3 lesion

API integration details teeth[].diseases[]API integration details image_level_diseases API integration details name API integration details

API integration details API integration detailsAPI integration detailsAPI integration details）：

API integration details	API integration details
`impacted_tooth`	API integration details
`full_crown`	API integration details
`periapical_radiolucency`	API integration details
`tooth_filling`	API integration details
`retained_primary_tooth`	API integration details
`embedded_tooth`	API integration details
`alveolar_bone_resorption`	API integration details
`residual_root`	API integration details
`elongation`	API integration details
`implant`	API integration details
`tooth_bridge`	API integration details
`residual_crown`	Residual Crown
`general_caries`	caries
`root_canal_filling`	API integration details
`wedge_shaped_abrasion`	Wedge-Shaped Defect
`microdontia`	API integration details
`high_density_bone_anomaly`	API integration details
`supernumerary_tooth`	API integration details
`limited_eruption_space`	API integration details
`low_density_bone_anomaly`	API integration details

API integration details

API integration detailsAPI integration detailsAPI integration detailsservice providerAPI integration details

API integration details`landmarks` API integration details

API integration details

API integration details coordinate_system API integration detailsAPI integration details，API integration detailsAPI integration details API integration details。

API integration details

API integration detailsAPI integration details。landmark_num / ceph_landmark_num API integration detailsAPI integration detailsAPI integration details error_code: INVALID_LANDMARK_NUMAPI integration details

API integration details

API integration detailsAPI integration detailsAPI integration detailsAPI integration detailsAPI integration details landmarks API integration details

API integration details

API integration details API integration detailsAPI integration detailsAPI integration detailsAPI integration details meta API integration details landmark_numAPI integration details 46API integration details disease_models_failedAPI integration detailsdoes not includeAPI integration details

6.5 `landmarks` API integration details

Field	API integration details	Description
`index`	API integration details	API integration details
`name`	API integration details `null`	API integration details
`definition_zh`	API integration details `null`	API integration details `null`）
`x`	API integration details `null`	API integration details `null`
`y`	API integration details `null`	API integration details `null`
`valid`	API integration details	API integration details`false` API integration details

API integration details teeth API integration details image_level_diseases API integration details

6.6 `summary`（cephalometric）

API integration details summary API integration details total_landmarksAPI integration details landmarks API integration details visible_landmarks（valid as true API integration detailsdoes not includeAPI integration details

7. Response JSON StructureDescription

API integration details

Field	Description
`success`	API integration details
`image_type`	API integration details
`inference_status`	`ok`API integration details`partial`API integration details
`error` / `error_code`	API integration details `null`
`request_id`	API integration details
`elapsed_ms`	API integration details
`coordinate_system`	API integration details
`image`	API integration details `width`、`height`API integration details
`teeth`	API integration details
`landmarks`	API integration details
`image_level_diseases`	API integration details
`summary`	API integration details `total_landmarks`、`visible_landmarks`
`meta`	API integration details

7.2 intraoral / panoramic：`teeth[]` API integration details `diseases[]`API integration details

Field	Description
`fdi`	API integration details
`tooth_bbox`	API integration details `[x1,y1,x2,y2]`
`segmentation`	API integration details`polygons`、`bbox` API integration details `polygons_raw`
`status`	API integration details`API integration details` / `API integration details` / `API integration details`
`diseases[]`	API integration details `name`、`status`、`confidence`、`bbox` API integration details

API integration details

API integration details

（meta API integration details

API integration details

API integration details

API integration details polygons / polygons_raw API integration details

API integration details

API integration details

API integration details landmarks API integration details 46API integration details summary.total_landmarks API integration details meta.landmark_num API integration details

8. Common Error Codes

`error_code`	API integration details	Description
`UNAUTHORIZED`	401	API integration details
`NO_FILE`	400	API integration details
`MISSING_IMAGE_TYPE`	400	API integration details `image_type`
`INVALID_IMAGE_TYPE`	400	API integration details `image_type`
`FILE_TOO_LARGE`	413	API integration details
`UNSUPPORTED_MEDIA_TYPE`	415	API integration details
`INVALID_IMAGE`	400	API integration details
`INVALID_LANDMARK_NUM`	400	API integration details
`FILE_NOT_FOUND`	400	API integration details
`DETECTION_ERROR`	500	API integration details

API integration details request_id、elapsed_ms、coordinate_system API integration details

9. Notes

API integration details 「Service Endpoints and Path Rules」 API integration details
API integration detailsAPI integration detailsservice providerAPI integration details

Oral Imaging AI Detection API

Service Endpoints and Path Rules

API integration details

API integration details

1. API Overview

1.1 Health Check GET /health

2. Calling Method

2.1 Request Conventions

API integration details

2.3 Authentication

API integration details

API integration details

panoramic

API integration details

Fixed-type routes (image_type can be omitted image_type）

3. Image Types and Main Outputs

API integration details

API integration detailsteeth[].diseases[] API integration details name）

API integration detailsimage_level_diseases[] API integration details name）

API integration details

API integration details

API integration details

5.2 segmentation API integration details

5.3 lesion

API integration details

API integration detailslandmarks API integration details

API integration details

API integration details

API integration details

API integration details

6.5 landmarks API integration details

6.6 summary（cephalometric）

7. Response JSON StructureDescription

API integration details

7.2 intraoral / panoramic：teeth[] API integration details diseases[]API integration details

API integration details

API integration details

API integration details

8. Common Error Codes

9. Notes

1.1 Health Check `GET /health`

Fixed-type routes (image_type can be omitted `image_type`）

API integration details`teeth[].diseases[]` API integration details `name`）

API integration details`image_level_diseases[]` API integration details `name`）

5.2 `segmentation` API integration details

API integration details`landmarks` API integration details

6.5 `landmarks` API integration details

6.6 `summary`（cephalometric）

7.2 intraoral / panoramic：`teeth[]` API integration details `diseases[]`API integration details