REST API · v1

API documentation

Submit portraits through an asynchronous API, share your existing credit wallet, and track every job and charge.

Billing

API: 1 credit per successful test. Website: 10 credits per test. Both use the same wallet. API creation reserves 1 credit; a final failure refunds it once.

Send Authorization: Bearer with the required scope. Use the same Idempotency-Key for retries of identical image bytes. Reusing it with different input returns HTTP 409. Queries do not consume credits.

Endpoints

HTTP	Permissions
POST /api/v1/face-age/jobs	face-age:write
GET /api/v1/face-age/jobs/{id}	face-age:read
GET /api/v1/credits	credits:read
GET /api/v1/usage?page=1&pageSize=20	usage:read

Create a job

Use multipart/form-data with one image file (JPEG, PNG or WebP, up to 5 MB) and the consent field below. Only adults submitting their own photo with consent may use this endpoint. Remote URLs and extra parameters are rejected. Generate a new idempotency key only for a new logical test.

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

Poll for results

Creation returns HTTP 202 and a job ID. Poll every 10–15 seconds. queued, processing and retrying are nonterminal; succeeded and failed are terminal. HF wake-up may take several minutes. Jobs have a 20-minute deadline; a live worker lease may delay final recovery by up to four more minutes.

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

Errors and limits

Responses use code/message/data. HTTP 400: invalid request or consent; 401: invalid/expired key; 403: missing scope; 402: insufficient credits; 404: missing or unowned job; 409: changed input; 413/415: invalid image size/type; 429: request, concurrency or budget limit; 503: unavailable. Follow Retry-After, reuse the same idempotency key, and inspect message before retrying.

Keys expire within one year. Budgets include reserved and successful credits; refunds restore budget. The account allows 60 requests/minute and at most two active API jobs.

Portraits are stored temporarily in a private bucket and deleted after terminal processing, with a 24-hour lifecycle fallback. HF processes the photo; estimates are not medical advice, identity verification or proof of age.