The search4faces API is a web based API and is shipped as part of the web frontend. It uses the JSON-RPC 2.0 protocol over HTTPS.
You must include the following headers in requests sent to the API:
Content-Type: application/json
x-authorization-token: your_API_key
The basic API endpoint is:
https://search4faces.com/api/json-rpc/v1
If you want to try our API and see how it works without purchasing our plans first, just contact our team and we will make the API accessible to you free of charge. Client libraries are available for PHP and Python.
Retrieve the details about your API key limits.
Example request:
{ "jsonrpc": "2.0", "method": "rateLimit", "id": "some-id", "params": {} }
The method takes no parameters.
Example of successful response:
{ "jsonrpc": "2.0", "result": { "apikey": "5c40b9-b246ab-648561-435157-2c3f8b", "limit": 10000, "remaining": 9954, "enddate": 2022-03-05 00:00:00, "speed": 8, "allowed": [ "rateLimit", "detectFaces", "searchFace" ], "disabled": "no" }, "id": "some-id" }
Returns:
apikey (str) - your API key limit (int) - total number of requests remaining (int) - number of requests remaining enddate (datetime) - end date for your API key validity speed (int) - requests per minute allowed (array[str]) - list of allowed methods disabled (bool) - API key status
Detects faces within an image that is provided as input.
Example request:
{ "jsonrpc": "2.0", "method": "detectFaces", "id": "some-id", "params": { "image": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP/wgALCAABAAEBAREA/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPxA=" } }
Parameters:
image (str) - input jpeg or png image as base64-encoded bytes
Example of successful response:
{ "jsonrpc": "2.0", "result": { "image": "5eb16c3421dd32.08349177.jpg", "faces": [ { "x": 25, "y": 37, "width": 55, "height": 67, "lm1_x": 39, "lm1_y": 68, "lm2_x": 62, "lm2_y": 62, "lm3_x": 53, "lm3_y": 80, "lm4_x": 47, "lm4_y": 90, "lm5_x": 67, "lm5_y": 84 }, {...} ] }, "id": "some-id" }
Returns:
image (str) - unique image identifier to pass it to the searchFace method faces (array[obj]) - details of each face found in the image x (int) - left coordinate of the bounding box y (int) - top coordinate of the bounding box width (int) - width of the bounding box height (int) - height of the bounding box lm1_x (int) - x-coordinate of the left eye lm1_y (int) - y-coordinate of the left eye lm2_x (int) - x-coordinate of the right eye lm2_y (int) - y-coordinate of the right eye lm3_x (int) - x-coordinate of the nose lm3_y (int) - y-coordinate of the nose lm4_x (int) - x-coordinate of left corner of the mouth lm4_y (int) - y-coordinate of left corner of the mouth lm5_x (int) - x-coordinate of right corner of the mouth lm5_y (int) - y-coordinate of right corner of the mouth
Search for similar faces in a database that contains billions of images.
Example request:
{ "jsonrpc": "2.0", "method": "searchFace", "id": "some-id", "params": { "image": "5eb16c3421dd32.08349177.jpg", "face": { "x": 25, "y": 37, "width": 55, "height": 67, "lm1_x": 39, "lm1_y": 68, "lm2_x": 62, "lm2_y": 62, "lm3_x": 53, "lm3_y": 80, "lm4_x": 47, "lm4_y": 90, "lm5_x": 67, "lm5_y": 84 }, "source": "vk_wall", "hidden": true, "results": "10" "lang": "en" } }
Parameters:
image (str) - unique image identifier received when calling the detectFaces method face (obj) - details of the face found, for example, when calling detectFaces method x (int) - left coordinate of the bounding box y (int) - top coordinate of the bounding box width (int) - width of the bounding box height (int) - height of the bounding box lm1_x (int) - x-coordinate of the left eye lm1_y (int) - y-coordinate of the left eye lm2_x (int) - x-coordinate of the right eye lm2_y (int) - y-coordinate of the right eye lm3_x (int) - x-coordinate of the nose lm3_y (int) - y-coordinate of the nose lm4_x (int) - x-coordinate of left corner of the mouth lm4_y (int) - y-coordinate of left corner of the mouth lm5_x (int) - x-coordinate of right corner of the mouth lm5_y (int) - y-coordinate of right corner of the mouth source (str) - vkok_avatar or vk_wall or tt_avatar or ch_avatar or vkokn_avatar or sb_photo (unique identifier for the face search database) hidden (bool) - show hidden profiles in addition to the visible ones results (int) - limit the number of search results, max 500 lang (str) - language of choice, default is "ru"
Example of successful response:
{ "jsonrpc": "2.0", "result": { "profiles": [ { "score": "94.70", "face": "https://search4faces.com/faces/vk01/00/00/00/7/0.jpg", "profile": "https://vk.com/id1", "photo": "https://vk.com/id1?z=photo1_288668576%2Fphotos1", "photo_x": 368, "photo_y": 265, "photo_width": 146, "photo_height": 174, "source": "https://sun9-3.userapi.com/c7003/v7003978/1ed9/yoeGXOWmW-M.jpg", "age": 35, "first_name": "Павел", "last_name": "Дуров", "maiden_name": "", "city": "Санкт-Петербург", "country": "Россия" }, {...} ] }, "id": "some-id" }
Returns:
profiles (array[obj]) - details of each user profile found score (float) - similarity score face (str) - link to the image of the face profile (str) - public profile url photo (str) - url of the source image preview photo_x (int) - left coordinate of the bounding box photo_y (int) - top coordinate of the bounding box photo_width (int) - width of the bounding box photo_height (int) - height of the bounding box source (str) - url of the source image age (int) - user's age first_name (str) - user's first name last_name (str) - user's last name maiden_name (str) - user's middle name city (str) - user's city country (str) - user's country