Server Endpoints and Path Conventions

Base URL consists of the protocol, hostname, and (if applicable) a gateway prefix. It does not include business paths (such as /api/v1/...). Append each endpoint’s relative path below to the Base URL when calling the API.

Common Full URLs (production example)

Conventions

• Do not append a trailing / to the Base URL, to avoid malformed paths such as .../detectapi//api/....
• If you use a dedicated deployment or custom domain, replace the example root URL above with the root URL confirmed in writing by the service provider; endpoint paths /api/v1/... and /health typically remain unchanged.

1. API Overview

1.1 Health Check GET /health

Used for operations monitoring, load-balancer health checks, and similar scenarios to confirm that the detection service process is reachable. Does not accept image files or run inference. Business workflows for intraoral, panoramic, or cephalometric detection do not need to call this endpoint.

2. How to Call the API

2.1 Request Conventions

2.2 Form Fields

2.3 Authentication

If the service provider has enabled access control, include the following request header:

Authorization: Bearer <TOKEN>

<TOKEN> is issued by the service provider. If the header is missing or validation fails, the API returns HTTP 401 with error_code UNAUTHORIZED.

2.4 Request Examples (production Base URL)

Replace <TOKEN> with your actual credential. Base URL below: https://www.toothhelper.tech/detectapi.

Intraoral (unified endpoint)

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

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"

Cephalometric (46 anatomical landmarks)

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

Fixed-type routes (image_type optional)

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=@ceph.jpg"

3. Image Types and Primary Outputs

4. Intraoral Images: Output Field Reference

4.1 Per-Tooth Abnormalities (name in teeth[].diseases[])

An entry appears only when a given abnormality on that tooth reaches suspected or confirmed status. Dental fluorosis is not included in this array; see Section 4.2 for image-level findings.

The current intraoral per-tooth model covers the following conditions. In JSON, name is returned in Chinese; when lang=en, the same entry also includes name_en:

Distinction from image-level crowding: Tilted tooth and rotated tooth are single-tooth detection results in teeth[].diseases[]; dental crowding is an image-level conclusion in image_level_diseases[]. Both may coexist and are not interchangeable.

4.2 Image-Level Conclusions (name in image_level_diseases[])

Image-level name values are returned in Chinese. Common examples:

4.3 Algorithm Performance and Scope

Output is influenced by image quality, capture conditions, patient characteristics, and model version, among other factors. This document does not provide fixed accuracy guarantees suitable for contracts or acceptance testing. For quantitative evaluation reports or acceptance metrics, please arrange separately with the service provider and obtain written materials.

5. Panoramic Images: Geometry Fields and Lesion Naming

5.1 Teeth and Segmentation

• teeth[]: includes tooth position (fdi) and geometry in segmentation (polygon when contours are available; otherwise bounding box or similar, per actual response).

5.2 segmentation and Contour-Related Fields

When mask output is available for panoramic tooth segmentation, the API may return raw, unprocessed contours in segmentation.polygons_raw per tooth, enabling integrators to rasterize or perform geometry operations themselves. Display-oriented polygons may be simplified or quality-filtered and need not match polygons_raw. When segmentation.mode is polygon, display polygons are usually provided; otherwise the response may fall back to bbox, in which case polygons may be null. The API does not return a full-image H×W binary mask array.

5.3 Lesions

Lesions are in teeth[].diseases[]. For panoramic images, image_level_diseases is typically an empty array.

Unlike intraoral images, panoramic lesions are detected by a single multi-class model. Lesion name values are typically returned as English snake_case identifiers (e.g. impacted_tooth). Intraoral per-tooth labels follow a different scheme (see Section 4.1). Integrate based on actual API responses.

The table below lists common class identifiers and their reference meanings (for cross-reference with literature or internal annotation schemes; not an exhaustive closed enum):

5.4 Algorithm Performance and Scope

Same as Section 4.3: panoramic output depends on data and version factors and is not a clinical gold standard. Request quantitative metrics and formal evaluation criteria from the service provider.

6. Cephalometric: landmarks and Coordinates

6.1 Coordinate System

Consistent with intraoral and panoramic, the top-level coordinate_system specifies: origin at the top-left corner of the uploaded image, x-axis to the right, y-axis downward, units in pixels.

6.2 Landmark Configuration

The current API outputs 46 landmarks only for cephalometric images. If landmark_num / ceph_landmark_num is set to an unsupported value, the API returns error_code: INVALID_LANDMARK_NUM (HTTP 400). When these fields are omitted, behavior matches the current production default.

6.3 Integration and Visualization

Successful responses return detection results as structured JSON, suitable for direct storage, display, or integration with HIS, imaging workstations, and other systems. To overlay cephalometric landmarks or text labels on the image, align and draw using x, y, valid, name, and related fields from landmarks against your local image copy.

6.4 meta (cephalometric)

On successful cephalometric analysis, meta includes landmark_num (currently 46) and disease_models_failed, consistent with other image-type endpoints (typically an empty array for cephalometric). Additional keys may change by version; rely on actual production responses.

6.5 landmarks Array Elements

For cephalometric images, teeth and image_level_diseases are empty arrays.

6.6 summary (cephalometric)

On success, summary provides total_landmarks (total count, matching landmarks length) and visible_landmarks (count where valid is true), giving a quick view of anatomical coverage and reliable points. This differs from tooth statistics in intraoral/panoramic responses by design.

7. Response JSON Structure

7.1 Top-Level Common Fields

7.2 Intraoral / Panoramic: teeth[] and diseases[] (summary)

7.3 Intraoral Success Response (excerpt)

{
                      "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 and image-level fields depend on the actual environment.)

7.4 Panoramic Success Response (excerpt)

{
                      "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": {}
                    }

(Tooth counts, summary fields, and presence of polygons / polygons_raw depend on actual inference results.)

7.5 Cephalometric Success Response (excerpt)

{
                      "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": []
                      }
                    }

(The example shows only the first two landmarks entries; the full array length is 46, consistent with summary.total_landmarks and meta.landmark_num.)

8. Common Error Codes

Failed responses may still include request_id, elapsed_ms, coordinate_system, and other fields to aid troubleshooting.

9. Supplementary Notes

• The production entry point is governed by the Server Endpoints and Path Conventions section above and the service provider’s latest written guidance.
• Access tokens, per-file size limits, concurrency and rate limits, logging and audit policies, and similar matters are agreed between you and the service provider at deployment and commercial terms; this document does not enumerate them.