Scan API Documentation
Integrate AI skin analysis — acne, pigmentation, dryness, wrinkles, dark circles, skin type, and an overall score — directly into your own app, clinic software, or website. One API call, full unlocked JSON results, no per-report paywall.
Authentication
Send your key on every request as the X-Api-Key header. Keys are shown once at subscribe/regenerate time — store yours securely (server-side only, never in client-side/browser code).
Endpoint
POSThttps://aiskinscan.in/api/v1/scan
Content-Type: multipart/form-data
Field: image — JPEG or PNG, up to 12 MB, one face per photo.
Code examples
curl -X POST https://aiskinscan.in/api/v1/scan \ -H "X-Api-Key: YOUR_API_KEY" \ -F "image=@face.jpg"
Example response
Trimmed for readability — every condition has the same shape, and region_geometry has one entry per facial region with full polygon points.
{
"scan_id": "908279e4-d8f8-48e2-8faa-98e89535886f",
"status": "ok",
"locked": false,
"created_at": "2026-07-17T09:42:10.626Z",
"model_version": "1.1.0-acne-cnn",
"processing_ms": 549,
"face": {
"detected": true,
"alignment": { "roll_deg": 1.2, "yaw_ratio": 0.03 },
"quality": { "brightness": 148.6, "sharpness": 461.1, "quality_ok": true, "warnings": [] },
"bbox": [0.3085, 0.2104, 0.3095, 0.2858]
},
"conditions": {
"acne": {
"score": 27.2, "severity": "Mild",
"metrics": { "lesion_count": 6, "affected_area_pct": 1.03 },
"regions": [
{ "region": "forehead", "score": 0, "severity": "None", "metrics": { "lesion_count": 0 } },
{ "region": "nose", "score": 64.4, "severity": "Moderate", "metrics": { "lesion_count": 2 } }
/* ... left_cheek, right_cheek, chin, jawline */
]
},
"pigmentation": { "score": 21.1, "severity": "Mild", "metrics": { }, "regions": [ /* ... */ ] },
"dryness": { "score": 20.6, "severity": "Mild", "metrics": { }, "regions": [ /* ... */ ] },
"wrinkles": { "score": 28.9, "severity": "Mild", "metrics": { }, "regions": [ /* ... */ ] },
"dark_circles": { "score": 60.1, "severity": "Moderate", "metrics": { }, "regions": [ /* ... */ ] }
},
"overall": {
"skin_score": 70.3,
"grade": "B",
"summary": "Main areas to focus on: dark circles."
},
"skin_type": "Dry",
"skin_type_metrics": { "t_zone_shine": 0.0212, "cheek_shine": 0.106, "roughness_index": 0.21 },
"region_geometry": [
{ "name": "forehead", "polygon": [[0.33, 0.25], [0.35, 0.23], "..."], "heat": { "acne": 0, "dryness": 0.2 } }
/* ... one entry per face region, for rendering a heatmap over the photo */
],
"flagged_for_doctor_review": false,
"disclaimer": "This is an AI-assisted screening, not a medical diagnosis. Please consult a certified dermatologist."
}Response fields
| Field | Type | Notes |
|---|---|---|
| scan_id | string (UUID) | Unique identifier for this scan. |
| status | string | "ok" when analysis succeeded. |
| locked | boolean | Always false — API responses are the full, unlocked result (no paywall). |
| created_at | string (ISO 8601) | When the scan was processed. |
| model_version | string | AI model version that produced this result. |
| processing_ms | number | Server-side processing time in milliseconds. |
| face.detected | boolean | Whether a face was found (always true on a 200 response). |
| face.quality | object | brightness, sharpness, quality_ok, warnings[] — soft photo-quality signals. |
| conditions | object | Keyed by acne, pigmentation, dryness, wrinkles, dark_circles — each has score (0-100, higher = more severe), severity (None/Mild/Moderate/Severe), metrics, and a regions[] breakdown. |
| overall.skin_score | number (0-100) | Composite score — higher is healthier. |
| overall.grade | string | A (excellent) through E (needs attention). |
| skin_type | string | Oily, Dry, Combination, or Normal. |
| region_geometry | array | Per-region polygon coordinates + per-condition heat values (0-1), normalized to the image — for rendering a face heatmap. |
| flagged_for_doctor_review | boolean | true if any condition scored Severe. |
| disclaimer | string | Legal disclaimer text to display alongside results. |
Errors
| HTTP | Body shape | Meaning |
|---|---|---|
| 403 | { "message": "Missing API key." } | No X-Api-Key header sent. |
| 403 | { "message": "Invalid or unscoped API key." } | Key is wrong, revoked, or lacks scan access. |
| 403 | { "message": "Your Scan API subscription is inactive or expired..." } | Key is valid but the subscription lapsed — renew at /api-access. |
| 400 | { "error_code": "invalid_image", ... } | The uploaded file isn't a decodable image. |
| 422 | { "error_code": "no_face_detected", ... } | No face was found in the photo. |
| 422 | { "error_code": "quality_too_low", "details": [...] } | Photo failed a hard quality gate (too dark/bright/blurry/tilted/glasses, etc). details[] lists every reason. |
| 500 | { "error_code": "pipeline_error", ... } | Unexpected server-side failure — safe to retry. |
Photo guidelines
Results are most reliable with the same conditions our own camera capture flow enforces:
- One person, facing the camera, no glasses
- Even, adequate lighting — not backlit, not too dim or blown out
- In focus (not blurry) and reasonably close (face fills a meaningful part of the frame)
- Head roughly level, not tilted or turned far to one side
Photos that fail these checks return a 422 with a specific error_code (see Errors above) instead of an unreliable result.
Rate limits & fair use
There's no hard per-minute cap today — usage is expected to stay reasonable for a single integration. If your traffic grows significantly, reach out first so we can make sure your plan and our infrastructure are sized for it.