API Documentation

Base URL

https://api.dermiq.dev

Authentication

All API requests require a Bearer token. Generate an API key in your dashboard. Include it in every request header.

Authorization: Bearer diq_sk_your_key_here

POST /v1/analyze

Upload a face image for full skin analysis. Returns an analysis ID for polling. Full analysis includes all 15+ metrics and 26 mask visualizations. Consumes 1 credit per analysis.

Parameters

curl -X POST https://api.dermiq.dev/v1/analyze \
  -H "Authorization: Bearer diq_sk_..." \
  -F "file=@face.jpg"

# Response (202 Accepted):
{
  "analysis_id": "uuid",
  "status": "pending",
  "message": "Analysis queued for processing"
}

POST /v1/analyze/quick

Quick analysis — scores only, no mask visualizations. Faster processing, ideal for real-time applications. Consumes 1 credit.

GET /v1/results/:id

Poll for analysis results. Status progresses: pending → processing → completed. Most analyses complete in 1.5-2.5 seconds.

Response Fields

# Response when completed:
{
  "id": "uuid",
  "status": "completed",
  "analysis_type": "full",
  "result_json": {
    "all": { "score": 78.5 },
    "skin_age": 32,
    "skin_tone": {
      "fitzpatrick": "III",
      "monk": "05",
      "ita_angle": 34.2
    },
    "hd_acne": { "raw_score": 91.2, "ui_score": 91.2 },
    "hd_wrinkle": {
      "whole": { "ui_score": 72.1 },
      "forehead": { "ui_score": 65.3 },
      "crow_feet": { "ui_score": 80.4 }
    },
    "hd_pore": { "ui_score": 68.9 },
    "hd_redness": { "ui_score": 82.5 },
    "hd_oiliness": { "ui_score": 55.0 },
    "hd_texture": { "ui_score": 74.3 },
    "hd_dark_circles": { "ui_score": 60.1 },
    "hd_firmness": { "ui_score": 71.8 },
    "faceshape": "Oval",
    "eye_color": { "hex": "#6B8E23", "name": "Hazel" },
    "lip_color": { "hex": "#C75B76" },
    "hair_color": { "hex": "#3B2F2F", "name": "Dark Brown" }
  },
  "mask_filenames": [
    "hd_acne_output.png",
    "hd_wrinkle_output_all.png",
    "hd_pore_output.png",
    "hd_redness_output.png"
  ],
  "overall_score": 78.5,
  "skin_age": 32,
  "processing_time_ms": 2150
}

GET /v1/results/:id/masks/:name

Download a specific mask PNG visualization. Returns the image file directly.

curl https://api.dermiq.dev/v1/results/{id}/masks/hd_acne_output.png \
  -H "Authorization: Bearer diq_sk_..." \
  --output acne_mask.png

Skin Metrics Reference

All metrics returned in result_json. Scores are 0-100 (higher = healthier).

Rate Limits & Pricing

Error Codes