Developers

API Reference

Everything you need to integrate the Rupam.ai skin analysis engine into your product.

Base URLhttps://xidomain.com/rupam/v1HTTPS onlyJSON / multipart

On this page

Getting Your API Key Authentication Core API Error Responses Rate Limits Quick Start Example SDK Flow Summary

Getting Your API Key

API keys authenticate your application with the Rupam platform. Each account supports one active key at a time.

1Log in to the Rupam Dashboard
2Navigate to the Dashboard page (/dashboard)
3Find the API Keys section
4Click + Generate Key
5Copy the key immediately — it is shown once only
6Click Done to close

One key at a time. If a key already exists, you must Revoke & Generate to replace it. Existing keys display their prefix (sk_live_...), creation date, and last used date.

API key format

text

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authentication

Rupam uses a two-step auth flow. Your API key is a long-lived credential; exchange it for short-lived access and refresh tokens to make API calls.

Step 1 — Exchange API Key for Tokens

POST/auth/token

bash

curl -X POST https://xidomain.com/rupam/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "plan": {
    "name": "Pro",
    "rpm": 10,
    "rph": 200,
    "rpd": 1000,
    "rpp": 10000
  }
}

Field	Meaning
`rpm`	Requests per minute
`rph`	Requests per hour
`rpd`	Requests per day
`rpp`	Requests per plan period

Step 2 — Use Access Token

Include the access token in the Authorization header of every subsequent request.

http

Authorization: Bearer <access_token>

Refresh Access Token

Access tokens expire. Use the refresh token to get a new one without re-exchanging your API key.

POST/auth/refresh

bash

curl -X POST https://xidomain.com/rupam/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "plan": {
    "name": "Pro",
    "rpm": 10,
    "rph": 200,
    "rpd": 1000,
    "rpp": 10000
  }
}

Core API

Skin Analysis

Run the full skin analysis ML pipeline on a user's image. Accepts a multipart form upload.

POST/analyze

Form fields

Field	Type	Description
`image`	file	Face image (JPEG / PNG, max 10 MB)
`collect_image`	boolean	Store image for asset generation

bash

curl -X POST https://xidomain.com/rupam/v1/analyze \
  -H "Authorization: Bearer <access_token>" \
  -F "image=@/path/to/face.jpg" \
  -F "collect_image=true" \
  --max-time 210

Response

json

{
  "request_id": "req_a1b2c3d4",
  "status": "completed",
  "conditions": {
    "acne": {
      "score": 72,
      "severity": "moderate",
      "regions": ["forehead", "chin"]
    },
    "wrinkles": {
      "score": 15,
      "severity": "mild",
      "regions": ["eye_area"]
    }
  },
  "overall_skin_score": 68,
  "suggestions": [
    "Use a salicylic acid cleanser twice daily",
    "Apply SPF 30+ sunscreen every morning"
  ],
  "overlays": {
    "composite_url": "https://...",
    "condition_urls": { "acne": "https://..." }
  }
}

Timeout. The analysis pipeline can take up to 200 seconds. Set your HTTP client timeout to at least 210 seconds.

Get Analysis Assets

Fetch overlay images for a completed analysis. Assets may generate asynchronously — poll until status is ready.

GET/analyze/{request_id}/assets

bash

curl https://xidomain.com/rupam/v1/analyze/req_a1b2c3d4/assets \
  -H "Authorization: Bearer <access_token>"

Response

json

{
  "request_id": "req_a1b2c3d4",
  "status": "ready",
  "assets": {
    "composite": "https://...",
    "conditions": {
      "acne": "https://...",
      "wrinkles": "https://..."
    }
  }
}

Status values

Value	Meaning
`pending`	Generation not started
`partial`	Some assets ready, still processing
`ready`	All assets available

Error Responses

All errors follow a consistent shape regardless of HTTP status code.

json

{
  "detail": "Human-readable error message"
}

HTTP Status	Meaning
`400`	Bad request — invalid input
`401`	Unauthorized — missing or expired token
`403`	Forbidden — valid token, insufficient permissions
`404`	Resource not found
`409`	Conflict — e.g. email already registered
`422`	Validation error — malformed request body
`429`	Rate limit exceeded — check Retry-After header
`503`	Service unavailable — models not yet loaded

Rate Limits

Limits are per API key and enforced at multiple time windows simultaneously.

Window	Response Header
`Per minute`	X-RateLimit-RPM-Remaining
`Per hour`	X-RateLimit-RPH-Remaining
`Per day`	X-RateLimit-RPD-Remaining
`Per plan period`	X-RateLimit-RPP-Remaining

On 429, check the Retry-After header for the number of seconds until your next allowed request.

Quick Start Example

A complete end-to-end example: exchange your API key for tokens, then run a skin analysis.

PythonJavaScript

import httpx

BASE_URL = "https://xidomain.com/rupam/v1"
API_KEY  = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 1. Exchange API key for tokens
auth         = httpx.post(f"{BASE_URL}/auth/token", json={"api_key": API_KEY}).json()
access_token = auth["access_token"]
headers      = {"Authorization": f"Bearer {access_token}"}

# 2. Run skin analysis
with open("face.jpg", "rb") as f:
    response = httpx.post(
        f"{BASE_URL}/analyze",
        headers=headers,
        files={"image": f},
        data={"collect_image": "true"},
        timeout=210,
    )

result = response.json()
print(result["overall_skin_score"])
print(result["conditions"])

const BASE_URL = "https://xidomain.com/rupam/v1";
const API_KEY  = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

// 1. Exchange API key for tokens
const { access_token } = await fetch(`${BASE_URL}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ api_key: API_KEY }),
}).then((r) => r.json());

// 2. Run skin analysis
const form = new FormData();
form.append("image", imageFile);        // File object
form.append("collect_image", "true");

const result = await fetch(`${BASE_URL}/analyze`, {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}` },
  body: form,
}).then((r) => r.json());

console.log(result.overall_skin_score);

SDK Flow Summary

The complete request lifecycle from API key to overlay images.

API Key

Your long-lived credential

→ sk_live_xxx

Exchange for TokensPOST

POST /auth/token

→ access_token + refresh_token

Run AnalysisPOST

POST /analyze (multipart)

→ request_id + conditions + scores

Fetch AssetsGET

GET /analyze/{request_id}/assets

→ overlay image URLs

Ready to integrate?

Get your API key and start analysing skin in minutes.

View Pricing Talk to Sales