FaceFinderAi Public API

AI face recognition & reverse image search API.

FaceFinderAi provides AI technology to search images by face. Use a simple HTTP API to upload a face photo, run a reverse image search across our index or your own, and retrieve face matches directly in your apps and investigation tools.

HTTP JSON API

Search images of anyone by face — from your backend.

The FaceFinderAi API exposes two core endpoints: one to upload a face image and get an id_search, and one to poll the search and retrieve normalized results. You can use it for AI‑powered face recognition, people lookup, and reverse image search workflows.

Each request is authenticated with an API key, so you can safely let your own products, OSINT tools, and internal dashboards search for visually similar faces while you keep full control over usage and credits.

Authentication

API key in Authorization header.

Every request must include a valid FaceFinderAi API key using the Authorization: Bearer <API_KEY> header.

Authorization: Bearer YOUR_FACEFINDER_API_KEY

Invalid or missing keys return 401 unauthorized with a short JSON error. Keys are tied to a FaceFinderAi user and their face search history and usage.

AI‑powered people search

Use face recognition to search images for anyone whose face you have a lawful right to process. Build tools to investigate impersonation, fake profiles, and brand misuse.

OSINT & investigations

Combine reverse image face search with other OSINT signals. Automate searches and review matches inside your own investigation platforms.

Product & API integrations

Add “search by face” to your own products. Call the API from Node, Python, PHP, or Go using standard HTTP and JSON.

Typical search flow

A full reverse image face search is two steps: upload the image, then poll for results using the returned id_search.

Upload a face image with POST /api/public/upload_pic.php (multipart/form-data).
Poll for status & matches with POST /api/public/search.php (JSON), passing the same id_search until status is "done".

1. Upload image & start a face search

POST /api/public/upload_pic.php

Upload a face image using multipart/form-data. The server:

Stores the image (or embedding) locally under your account.
Forwards it to the FaceFinderAi search provider.
Creates a new searches row for your user.
Returns an id_search handle to poll later.

Request

Headers

Authorization: Bearer YOUR_FACEFINDER_API_KEY
Content-Type: multipart/form-data; boundary=...

Body (multipart/form-data)

Field	Type	Required	Description
`images`	file	Yes	Face image to search by. If multiple files are sent, the first is used.

Successful response

{
  "id_search": "R4RU7A3o5gg",
  "search_db_id": 1234,
  "provider": {
    "id_search": "R4RU7A3o5gg",
    "message": "Image uploaded successfully.",
    "error": null,
    "code": null,
    "output": null,
    "input": null
  }
}

Most integrations store id_search (and optionally search_db_id) and then move on to polling. The nested provider object is useful for debugging or advanced monitoring of the underlying AI provider.

2. Poll search status & face matches

POST /api/public/search.php

Poll the status of a search and retrieve face matches using the id_search from the upload step.

Request

Headers

Authorization: Bearer YOUR_FACEFINDER_API_KEY
Content-Type: application/json

Body (JSON)

Field	Type	Required	Default	Description
`id_search`	string	Yes	—	The `id_search` returned by the upload endpoint.
`with_progress`	boolean	No	`true`	Ask the provider to include a `progress` field (0–100).
`status_only`	boolean	No	`false`	When `true`, prioritize status/progress over full results for polling.
`demo`	boolean	No	`false`	Demo/test flag forwarded to the provider. Does not change public API behavior.

The shady_only flag is internal‑only and ignored by the public API.

Example request

{
  "id_search": "R4RU7A3o5gg",
  "with_progress": true,
  "status_only": true,
  "demo": false
}

Successful response (in progress)

{
  "id_search": "R4RU7A3o5gg",
  "search_db_id": 1234,
  "status": "queued",
  "result_count": 0,
  "message": "Waiting in queue. 2nd place",
  "progress": 0,
  "error": null,
  "code": null,
  "output": {
    "items": []
  }
}

Successful response (completed with matches)

{
  "id_search": "R4RU7A3o5gg",
  "search_db_id": 1234,
  "status": "done",
  "result_count": 3,
  "message": "Search Completed",
  "progress": 100,
  "error": null,
  "code": null,
  "output": {
    "items": [
      {
        "guid": "975b557ce2ec2dcea244e0e43b701286",
        "score": 93,
        "group": 0,
        "base64": "data:image/webp;base64,...",
        "url": "https://example.com/matching-page-1",
        "indexDB": 842434382,
        "seen": null
      }
      // ...
    ]
  }
}

Items are ordered by descending score, with a small shuffle inside equal‑score groups via ffai_order_results_by_score_with_shuffle() so ties don’t always appear in the same order.

Errors & limitations

Both endpoints return short JSON error responses with an error code and human‑readable message.

401 unauthorized — invalid or missing API key.
400 no_file or not_an_image — bad upload.
400 missing_id_search — id_search not provided.
403 forbidden — id_search belongs to another user.
502 provider_error — provider upload/search failed.

Error and status messages are normalized for consistency, so your integration receives clear, stable wording across provider updates.

Need help integrating the FaceFinderAi API?

If you’d like sample code in a specific language, guidance on rate limits, or to discuss higher‑volume access to the reverse image search API, reach out and we’ll help you get set up.

Email us at [email protected] or message us on Telegram at @vccdinu.