Developer API

FaceFinderLens API

Reverse face search: give it a photo, get back where that face appears online.

New here? Start with how it works — the walkthrough, code samples and pricing in one page.

Pricing

Exactly what the website charges: one credit is one face search. Credits do not expire, there is no monthly fee, and nothing renews.

Standard

3 credits

$3.95

Premium

7 credits

$6.95

Or any amount from 3 to 50 credits, priced the same way as on the pricing page.

Authentication

Create a key in the dashboard and send it as a bearer token. The secret is shown once, at creation — we store only a hash of it, so a lost key is replaced rather than recovered.

Authorization: Bearer sk_live_…

Run a lookup

Download Postman collection

multipart/form-data with an image file. There is no image_url parameter on purpose — fetching arbitrary URLs server-side is a request-forgery risk.

curl -X POST https://facefinderlens.com/api/v1/lookup \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "image=@/path/to/face.jpg"

Parameters

image file · required
JPEG, PNG or WebP, up to 10 MB. Checked by content, not by filename.

Response

{
  "success": true,
  "lookup_id": "9f2c…",
  "type": "image",
  "credits_remaining": 42,
  "data": {
    "items": [
      { "guid": "cdb7…", "score": 88, "url": "https://…", "base64": "data:image/webp;base64,…" }
    ]
  }
}

Check your balance

curl https://facefinderlens.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_your_key"

Errors

Status	Meaning
400	The request was malformed — the message says which field.
401	Missing, unknown or revoked API key.
402	No credits left. Top up in the dashboard.
403	Account suspended.
429	More than 60 requests in a minute.
502 / 503	The upstream provider failed. Your credit is refunded automatically.

A credit is spent only when a lookup actually runs. Every failure after the deduction — provider error, timeout, anything — refunds it.

What we store

The same as for the website: nothing about the lookup itself. No queries, no uploaded images, no results — the response is the only copy. Per call we keep the endpoint, the status code and the time, which is what billing and rate limiting need.