Face Search API

What you get

• The same search engine the website runs on — no separate index, no reduced tier for API callers.
• Match URLs with a similarity score and a thumbnail for each hit.
• A flat price per call: one credit, whatever the photo and however many matches come back.
• Credits that never expire, bought in packs or any amount from 3 to 50.
• No query logging: we keep the endpoint, the status and the time, never the image or the result.

How does it work?

1. 01Create an account and a key

   Sign up at /developers/register/ with an email and a password — no card is needed to get a key. In the dashboard, open the API keys tab and create one. The secret is shown exactly once, because the database stores only its SHA-256 hash; if it is lost, revoke it and make another.

   

2. 02Buy credits

   On the Billing tab, pick a pack — 3 credits for $3.95, 7 for $6.95, or any amount between 3 and 50 — and pay through Stripe. Credits land on your balance as soon as Stripe confirms, and they do not expire. One credit is one search, whether the photo returns forty matches or none.

   

3. 03POST a photo

   Send the image as multipart/form-data with the field name `image`, and your key as a bearer token. JPEG, PNG and WebP are accepted up to 10 MB, and the file is checked by its contents rather than its name. There is deliberately no image_url parameter — having our servers fetch arbitrary URLs for a caller is a request-forgery hole, so the bytes come from you.

   

4. 04Read the matches

   The response carries an array of matches, each with the page URL, a similarity score and a thumbnail. Typical searches finish in fifteen to thirty seconds; the connection is held open until the search completes, so no polling or webhook is involved. Treat the score as similarity rather than identity — it compares faces, it does not certify who someone is.

   

Code to copy

The same call in three places. A Postman collection is available too, with both endpoints and saved example responses.

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

const body = new FormData();
body.append("image", new Blob([await fs.readFile("face.jpg")]), "face.jpg");

const response = await fetch("https://facefinderlens.com/api/v1/lookup", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FFL_API_KEY}` },
  body,
});

const { success, data, credits_remaining } = await response.json();
if (!success) throw new Error("lookup failed");
console.log(data.items.length, "matches,", credits_remaining, "credits left");

import os, requests

with open("face.jpg", "rb") as photo:
    response = requests.post(
        "https://facefinderlens.com/api/v1/lookup",
        headers={"Authorization": f"Bearer {os.environ['FFL_API_KEY']}"},
        files={"image": photo},
        timeout=180,
    )

payload = response.json()
if payload["success"]:
    for item in payload["data"]["items"]:
        print(item["score"], item["url"])

A failed lookup never costs a credit. If the provider errors, times out or the upload is rejected, the deduction is reversed before the error reaches you — so a 4xx or 5xx leaves your balance where it was.

Limits and guarantees

What people build with it

Questions

How much does the face search API cost?

One credit per search. Credits are $3.95 for three, $6.95 for seven, or any amount from 3 to 50 priced the same way as on the pricing page. There is no subscription, no monthly minimum and no per-seat fee, and credits do not expire.

Is there a free tier?

No. Every API search spends a credit, because every search costs us a provider call. The website's free preview is a synthetic teaser rather than a real search, so exposing it through the API would only return fake data.

What happens if a lookup fails?

The credit is refunded automatically. The deduction happens just before the search runs, and every failure path after that point — provider error, timeout, rejected upload — reverses it before returning the error.

Can I send an image URL instead of a file?

No, and that is deliberate. Fetching a caller-supplied URL server-side is a request-forgery hole pointed at our internal network, so the API takes the bytes from you as multipart/form-data.

How fast is it?

Most searches finish in fifteen to thirty seconds, which is how long the underlying index takes. The request stays open until the search completes — there is no polling or callback to implement — so allow at least 180 seconds of client timeout.

Do you store the photos I send?

No. The image is streamed to the search provider and dropped; the result goes back in the response and nowhere else. Per call we record the endpoint, the status code, the key and the time, which is what billing and rate limiting need, and nothing about the image or the matches.

Can I use it for identity verification or background checks?

No. The score measures visual similarity between faces, not identity, and the results must not drive decisions about employment, credit, housing, tenancy or insurance. It is built for trust-and-safety checks, not for regulated screening.

What do I do if a key leaks?

Revoke it in the dashboard — it stops working immediately — then create a replacement. You can hold up to ten active keys, so rotating one in production need not cause downtime.