FacePing API

An API for face recognition and vector comparison services

BASE URL
https://api.faceping.ai

Authentication

Sign into view and manage your API credentials

Face

FacePing's API provides a comprehensive set of endpoints for face recognition and vector management. Key functionalities include face comparisons (both image-to-image and vector-to-vector) and generating face vectors from uploaded images.

You can also efficiently manage face vector data with group-level operations, such as creating, deleting, and listing groups, as well as retrieving or removing specific vectors.

Advanced search capabilities

Compares two face images for similarity.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Request Body

Face1

required, string

First face to compare

Face2

required, string

Second face to compare

POST
/faces/compare
1

Compares two face vectors for similarity.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Request Body

embedding1

required, string, minimum length of 1

First face embedding vector as comma-separated float values

embedding2

required, string, minimum length of 1

Second face embedding vector as comma-separated float values

POST
/vectors/compare
1
EXAMPLE BODY
{
  "embedding1": "0.021,0.345,0.567,...",
  "embedding2": "0.019,0.341,0.569,..."
}

Generates a face vector from an image.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Request Body

image

required, string
POST
/vector/generate
1

Deletes a face group and all its associated face data.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string
DELETE
/groups/:groupName
1

Creates a new face group.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string
POST
/groups/:groupName
1

Lists all face groups.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

GET
/groups
1

Gets all vector IDs in a specified group.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string
GET
/groups/:groupName/vectors
1

Deletes specified faces (vectors) from a group.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

Unnamed Property

array of strings
DELETE
/groups/:groupName/vectors
1
EXAMPLE BODY
[
  "a7b2526a-05ec-4e44-9c7c-c6e3f6a8adca",
  "6ba03120-651f-4bb8-a1b1-6fd5ad0a00ab",
  "a60b23c0-25ac-4815-a46b-f5e15f6e19a6"
]

Gets a specific vector by its ID.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

vectorId

required, string
GET
/vectors/:vectorId
1

Searches for vectors using metadata filters.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

groupName

string

Request Body

metadata

optional, object, nullable

Dictionary of metadata key-value pairs to search for. Each pair acts as a filter condition where all conditions must match.

POST
/vectors/search
1
EXAMPLE BODY
{
  "metadata": {
    "department": "Important Department"
  }
}

Stores a face image in the specified group after converting it to a vector.

Request: This endpoint expects a multipart/form-data request.

Example cURL:

curl -X POST "/groups/my-face-group/face?metadata[key1]=value1&metadata[key2]=value2" 
     -H "Content-Type: multipart/form-data" 
     -F "image=@path/to/your-image.jpg"

Here:

  • Replace my-face-group with the desired group name.
  • metadata parameters are added as query parameters. For example ?metadata[role]=admin.
  • image is the file form field containing the face image (JPEG, PNG, etc.).

Example Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "groupName": "my-face-group"
}
Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

metadata

object

Path Parameters

groupName

required, string

Request Body

image

optional, string
POST
/groups/:groupName/face
1

Stores a raw vector in the specified group.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

vectorString

optional, string, nullable

Vector embedding as comma-separated float values

metadata

optional, object, nullable

Optional metadata associated with the vector Example: {"name": "John", "timestamp": "2024-03-21"}

POST
/groups/:groupName/vector
1
EXAMPLE BODY
{
  "vectorString": "0.1,0.2,0.3,0.4",
  "metadata": {
    "description": "Some sample metadata"
  }
}

Stores a base64 encoded face image in the specified group after converting it to a vector.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

base64Image

optional, string, nullable

Base64 encoded image string. Can include data URL prefix (e.g., "data:image/jpeg;base64,"). Maximum decoded size: 1MB.

metadata

optional, object, nullable

Optional metadata to store with the face vector. These key-value pairs will be combined with system metadata (source, createdAt).

POST
/groups/:groupName/face/base64
1
EXAMPLE BODY
{
  "base64Image": "iVBORw0KGgoAAAANSUhEUgAAAQAA....",
  "metadata": {
    "description": "Some sample metadata"
  }
}

Searches for similar faces within a group from an image.

Request:

This endpoint expects a multipart/form-data request containing an image file.

Example cURL:

curl -X POST "/groups/my-face-group/faces/search?topK=5" \
     -H "Content-Type: multipart/form-data" \
     -F "queryImage=@path/to/query-image.jpg"

Response Example:

The response is a list of scored vectors:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "score": 0.95,
    "metadata": {
      "fileName": "face1.jpg",
      "tag": "personA"
    }
  },
  {
    "id": "223e4567-e89b-12d3-a456-426614174000",
    "score": 0.90,
    "metadata": {
      "fileName": "face2.jpg",
      "tag": "personB"
    }
  }
]
Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Query Parameters

topK

integer, default: 10

Path Parameters

groupName

required, string

Request Body

queryImage

optional, string
POST
/groups/:groupName/faces/search
1

Searches for similar vectors within a group using a vector to search by.

Request (JSON):

{
  "vectorString": "0.1,0.2,0.3,0.4",
  "topK": 5
}

Example Response:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "score": 0.95,
    "metadata": {
      "fileName": "face1.jpg",
      "tag": "personA"
    }
  }
]
Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

vectorString

required, string, minimum length of 1

Query vector as comma-separated float values to search against

topK

optional, integer, maximum value of 40, minimum value of 1

Maximum number of similar vectors to return Default: 10

POST
/groups/:groupName/vectors/search
1
EXAMPLE BODY
{
  "vectorString": "0.1,0.2,0.3,0.4",
  "topK": 5
}

Bulk upserts multiple vectors into the specified group.

Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

vectors

optional, array, nullable, maximum of 100 items, minimum of 1 items

Collection of vector embeddings to store, each with (optional) metadata.

POST
/groups/:groupName/vectors/upsert
1
EXAMPLE BODY
{
  "vectors": [
    {
      "vectorString": "0.11,0.22,0.33,0.44",
      "metadata": {
        "tag": "personA"
      }
    },
    {
      "vectorString": "0.15,0.25,0.35,0.45"
    }
  ]
}

Processes all images in a Google Drive folder, generates face vectors, and stores them in the specified group.

After Processing Completion:

This operation processes images from a specified Google Drive folder. Once completed:

  • Callback URL (if provided):
    A POST request will be sent to the provided callback URL with a JSON payload summarizing the process result.
    Example:

    {
      "totalFiles": 50,
      "successCount": 48,
      "failed": [
        {
          "fileName": "corrupted_image.jpg",
          "fileId": "abc123",
          "error": "Invalid image format."
        }
      ]
    }
    
  • Email Notification (if email is provided):
    An email summarizing the results (total files processed, how many succeeded, how many failed) will be sent to the specified email address.
    This email contains the same information as the callback payload, presented in a readable format.

What to Expect:

  • A structured JSON summary of all images processed.
  • For successful images, their embeddings are stored in the specified group.
  • For failed images, error details are included in the summary.
Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

folderId

required, string, minimum length of 1

Google Drive folder ID to process images from

serviceAccountKey

required, string, minimum length of 1

JSON string containing Google service account credentials

notificationEmailAddress

optional, string, nullable

Email address to receive processing status notifications and results. If provided, notifications will be sent upon completion or failure.

callbackUrl

optional, string, nullable

Webhook URL for receiving real-time processing status updates. When specified, the system will send HTTP POST requests with processing status and results.

POST
/groups/:groupName/process-drive-folder
1
EXAMPLE BODY
{
  "folderId": "1A2B3C_DemoFolderId",
  "serviceAccountKey": "{ \"type\": \"service_account\", ... }",
  "notificationEmailAddress": "[email protected]",
  "callbackUrl": ""
}

Processes all images in an FTP folder, generates face vectors, and stores them in the specified group.

After Processing Completion:

This operation processes images from a specified FTP folder. Once completed:

  • Callback URL (if provided):
    A POST request will be sent to your callback URL with a JSON summary of the process:

    {
      "totalFiles": 30,
      "successCount": 28,
      "failed": [
        {
          "fileName": "bad_image.png",
          "fileId": "/ftp/path/bad_image.png",
          "error": "Unable to generate embedding."
        }
      ]
    }
    
  • Email Notification (if email is provided):
    An email will be sent to the provided email address summarizing the result of the FTP image processing.
    It includes the total number of files processed, how many succeeded, and the details of any failures.

What to Expect:

  • A JSON payload (via callback) or an email summarizing processing results.
  • Embedded vectors for successfully processed images stored in the specified group.
  • Detailed error information for any failed images.
Protected by API Key

Headers

Authorization

required, string

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

groupName

required, string

Request Body

host

required, string, minimum length of 1

FTP server hostname or IP address

username

required, string, minimum length of 1

FTP account username. Special characters should be URL encoded (e.g., $ as %24)

password

required, string, minimum length of 1

FTP account password

folderPath

required, string, minimum length of 1

Path to the folder containing images on the FTP server

port

optional, integer, nullable

Optional port number, defaults to 21 if not specified

notificationEmailAddress

optional, string, nullable

Email address to receive processing status notifications and results. If provided, notifications will be sent upon completion or failure.

callbackUrl

optional, string, nullable

Webhook URL for receiving real-time processing status updates. When specified, the system will send HTTP POST requests with processing status and results.

POST
/groups/:groupName/process-ftp-folder
1
EXAMPLE BODY
{
  "host": "ftp://example.com",
  "username": "ftpuser",
  "password": "ftppass",
  "folderPath": "/images/",
  "port": 21,
  "notificationEmailAddress": "[email protected]",
  "callbackUrl": ""
}