Usage & API Reference

Getting started

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt   # first run is large (pulls PyTorch)
.venv/bin/uvicorn app.server:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 for the UI. The API base URL is the same host.

Accounts & API keys

The masking endpoints (/api/mask and /api/jobs) require an API key. Each key carries a prepaid request balance: every successful call costs one request, and the key stops working once the balance hits zero.

1. Register with an email and password — you get a first API key and a balance of 100 requests.
2. Send the key in the X-API-Key header on every masking call (a Bearer token is also accepted).
3. Manage keys and watch usage on your dashboard — create or revoke keys, and top up a balance.

curl -s -X POST http://127.0.0.1:8000/api/mask \
  -H "X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@aadhaar.jpg"

Web UI options

Drag & drop one or more files onto the dropzone (or click to browse), set the options, and click Mask. One file gives an instant before/after preview; several files run as a batch with a results grid.

Required fields are marked with a red *. Validation runs live (on type, blur, and submit); on a problem a toast says “Please fix the highlighted field before masking” and focus jumps to the first invalid field.

List document types

Returns the document types the masker can detect, plus the default. Use the id values as the document_type field on /api/mask and /api/jobs. Today only Aadhaar is implemented; new types appear here automatically as they are registered.

curl -s http://127.0.0.1:8000/api/documents

{
  "documents": [
    { "id": "aadhaar", "label": "Aadhaar",
      "file_label": "Aadhaar file(s) — PNG / JPG / PDF" }
  ],
  "default": "aadhaar"
}

Mask a single file

Send multipart/form-data with the uploaded file plus any of the optional form fields below.

All requests must include your X-API-Key header — see Accounts & API keys.

Request — JSON response (default)

curl -s -X POST http://127.0.0.1:8000/api/mask \
  -H "X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@aadhaar.jpg" \
  -F "mode=first_8" \
  -F "mask_style=blur" \
  -F "extras=qr,photo"

Request — raw binary file back

curl -s -X POST http://127.0.0.1:8000/api/mask \
  -H "X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@aadhaar.pdf" \
  -F "response=binary" \
  -o masked_aadhaar.pdf -D headers.txt

With response=binary the body is the masked file itself; metadata comes back in headers: X-Masked-Number, X-Aadhaar-Side, X-Page-Count, and Content-Disposition.

Mask response (JSON)

{
  "is_aadhaar": true,
  "document_type": "aadhaar",      // which registered type was masked
  "side": "front",                 // "front" | "back" | "unknown"
  "aadhaar_number_found": true,
  "mask_mode": "first_8",
  "masked_number": "XXXX XXXX 9012",
  "rotation_applied": 0,           // degrees auto-rotated before masking
  "output_mime": "image/png",      // image/png | image/jpeg | application/pdf
  "masked_file_base64": "iVBORw0KGgo...",
  "page_count": 1,
  "pages": [                        // per-page breakdown (PDFs)
    { "index": 0, "is_aadhaar": true, "side": "front",
      "aadhaar_number_found": true, "masked_number": "XXXX XXXX 9012",
      "rotation_applied": 0 }
  ],
  "debug": { }
}

Bulk async jobs

For large lists, submit a job and poll — the submit returns immediately and work runs on a warm worker pool.

JSON body. images is a list of base64 strings (bare or data: URI); the rest mirror the mask options.

curl -s -X POST http://127.0.0.1:8000/api/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["<b64>", "<b64>"],
    "document_type": "aadhaar",
    "mode": "first_8",
    "mask_style": "solid",
    "extras": ["qr", "photo"],
    "on_not_aadhaar": "passthrough"
  }'
# -> { "job_id": "a1b2c3", "status": "running", "total": 2, "done": 0, "errors": 0 }

Poll status. Add ?include_results=false for a lightweight progress check.

curl -s "http://127.0.0.1:8000/api/jobs/a1b2c3?include_results=false"
# -> { "status": "running" | "completed", "done": 2, "total": 2, "errors": 0 }

curl -s "http://127.0.0.1:8000/api/jobs/a1b2c3"   # full per-item results

Each result item carries its own status (ok / error), so one bad image never aborts the batch. When disk output is enabled (AADHAAR_OUTPUT_DIR), masked files are served at:

Python SDK

from aadhaar_masker import mask_aadhaar, MaskConfig, MaskMode, MaskStyle

result = mask_aadhaar(
    image_bytes_or_base64,
    MaskConfig(mode=MaskMode.FIRST_8, mask_style=MaskStyle.BLUR, mask_qr_code=True),
)

if result.is_aadhaar and result.aadhaar_number_found:
    print(result.side)                 # "front" | "back" | "unknown"
    print(result.masked_number)        # "XXXX XXXX 9012"
    masked_b64   = result.masked_file_base64
    masked_bytes = result.masked_file_bytes
    data_uri     = result.masked_file_data_uri

mask_aadhaar accepts a base64 str (bare or data: URI) or raw bytes/bytearray/memoryview. For bulk, use mask_aadhaar_bulk(list, config, workers=4) (multi-process) or mask_aadhaar_batch(...) (sequential). See the project README.md for the full bulk/Redis guide.

All config options (MaskConfig)

Enum values

Errors & status codes

Error responses share the shape { "error": "...", "error_type": "...", "detail": "..." }.

Set on_not_aadhaar=passthrough to receive the original file (HTTP 200) instead of a 422 when the input isn’t a maskable Aadhaar.

Environment variables