Cerviray AI

How to Use the API

The API supports both GET and POST requests to http://cervirayai.aidot.ai/api/request. Use your license_key in all requests.

GET Request (Using File URL)

Parameters:

license_key: Your unique license key (required, query param).
file_url: The URL of the image to diagnose (required for GET, must be HTTP/HTTPS).

Example:

http://cervirayai.aidot.ai/api/request?license_key=YOUR_LICENSE_KEY&file_url=http://example.com/image.jpg

POST Request (Uploading File)

The POST request uses multipart/form-data to upload an image file directly.

Parameters:

license_key: Your unique license key (required, query param).
file: The image file to diagnose (required, form-data field, must be an image type like JPEG/PNG).

Request Format:

Content-Type: multipart/form-data
Query Param: license_key=YOUR_LICENSE_KEY
Form Field: file with the image file as the value

Example Response

The API returns a JSON object with the following fields:

satisfactory: Processing status with the following possible values:
- "TD0": "Unsatisfactory (Not a cervix image)"
- "TD1": "Unsatisfactory (Out of focus)"
- "TD2": "Unsatisfactory (Too dark)"
- "TD3": "Unsatisfactory (Cervix not clear)"
- "TD4": "Unsatisfactory (Taken from too far)"
- "OK0": "Satisfactory (Well-captured actual cervix image)"
- "OK1": "Satisfactory (Photo of paper or monitor)"
- "OK2": "Satisfactory (Slightly blurred image)"
result: Diagnosis result ("Normal", "CIN1", "CIN2, 3", "CIN3+").
score: Confidence score (0.0 to 1.0).
detection: Array of detected regions (empty for "Normal"). Each detection includes:
- label: "abnormal" or "cancer".
- x1, y1, x2, y2: Bounding box coordinates.

Example:

{
  "satisfactory": "OK0",
  "result": "CIN1",
  "score": "0.6786764860153198",
  "detection": [
    { "label": "abnormal", "x1": "1320", "y1": "84", "x2": "2198", "y2": "1294" },
    { "label": "abnormal", "x1": "769", "y1": "1126", "x2": "1340", "y2": "2133" },
    { "label": "abnormal", "x1": "1626", "y1": "1882", "x2": "2017", "y2": "2145" },
    { "label": "abnormal", "x1": "1765", "y1": "1594", "x2": "1947", "y2": "1881" }
  ]
}

Note: If the result is "Normal", the detection array will be empty.

Error Responses

The API may return the following error codes:

400 Bad Request: Missing or invalid parameters (e.g., no license_key, invalid file_url, or non-image file).
401 Unauthorized: Invalid license_key.
403 Forbidden: Insufficient tokens, with time until next recharge.
415 Unsupported Media Type: Uploaded file is not an image.
500 Internal Server Error: Database or file system failure.
504 Gateway Timeout: Diagnosis request timed out.

Example Error:

{
  "detail": "Insufficient tokens: 0 available. Next recharge in 01:23:45"
}

Additional Information