Import a Face from an Image as a New Identity

Use the following call to import a face from an image as a new identity.

For Local Host:

curl -v -X POST -H "Content-Type:application/octet-stream" -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userid:pwd" -H "XRPC-PERSON-NAME:First Last" -H "X-RPC-EXTERNAL-ID: 0000001" "http://localhost:8080/people?update=false" --data-binary @IMG_0000001.jpg

For SAFR Cloud:

curl -v -X POST -H "Content-Type:application/octet-stream" -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userid:pwd" -H "XRPC-PERSON-NAME:First Last" -H "X-RPC-EXTERNAL-ID: 0000001" "https://covi.real.com/people?update=false" --data-binary @IMG_0000001.jpg

This call first attempts to match a face already present in the main directory of the account and only imports it as a new identity if the face does not match an already existing one, and only if the new face meets default pose, sharpness, and contrast quality.

If a match is found, information about matched identity is returned (personId). If a new identity is formed, returned information includes the newId property set to true:

Note: Always use https when making requests over the internet.

Complete request with overrides in place:

curl -v -X POST -H "Content-Type:application/octet-stream" -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userid:pwd" -H "X-RPC-PERSON-NAME:0000001" -H "X-RPC-EXTERNAL-ID: 0000001" -H "X-RPC-FACES-GROUPINGTHRESHOLD: 0" "http://localhost:8080/people?min-cpq=0&min-fsq=0&min-fcq=0&update=false" --data-binary @IMG_0000001.jpg

Response

Element Description Notes
accountUpdated Indicates whether COVI has made changes to the account regarding person, face, or metadata about faces Boolean. If value is true, changes have been made to the account.
detectionTime Amount of time it takes to detect a face Integer. Value in milliseconds.
identifiedFaces Array of identifiedFaces data
personid ID indicates a recognized person String.
name Name associated with the recognized person String.
newId Identifies whether this is a new identity Boolean. true signifies a new identity.

Sample Response

{
  "accountUpdated": true,
  "detectionTime": 324,
  "identifiedFaces": [
                {
              "personId": "866e75a6-e22a-4077-97bb- e5dbfe1c513e",
              "name": "First Last",
              "newId": true,
              ...
                }
        ]
}

Headers

Header Name Description Notes
X-RPC-DIRECTORY: main Indicates directory of the identities used. In this example, directory is main. All data in different directories is separate. Use multiple directories when creating multiple identity sets for completely different uses. (Required) Maximum number of directories supported is 10 per account.
X-RPC-AUTHORIZATION:{userid:pwd} Provides credentials required for API access and identifies account used. Data in different accounts is entirely separate, even if the directory names in which data resides is the same. (Required) Substitute the key-value userid:pwd with your credentials required for API access to identify the account being used. Data in different accounts is entirely separate, even if the directory names in which data resides is the same.
X-RPC-PERSON-NAME:{First Last} Person name associated with the inserted identity. (Required)
X-RPC-EXTERNAL-ID: {0000001} External ID associated with the inserted identity. In this case, the test ID of the person is being used. This external ID is included in recognition responses, to allow the identity to be correlated to information maintained externally to the SAFR system. (Required) Identity metadata can be retrieved from the SAFR system by externalId as well as internal personId that are returned in insertion call response.
X-RPC-FACES-GROUPING-THRESHOLD: 0

Example: "identifiedFaces": [ { "personId": "866e75a6-e22a-4077-97bb-e5dbfe1c513e", "personExternalId": "0000001", "name": "0000001", "newId": true, … } ]		 Use to force insertion of the face as new identity even when a match can be normally found. Ensures that a newly detected face is inserted as a new identity, rather than being considered the same as an identity already present. Every insertion call is preceded with the check of the identity being inserted, to see if it is already present in the indicated directory. If present, the insertion is not made; the other already present identity is returned in response. The threshold of 0 makes almost certain the identity being inserted is considered different from any other identity. In case of an identical image already in the directory, the face in the image would not be inserted — even at threshold of 0 — but be considered already matching existing identity. Attribute newId=true in the response indicates if this call inserted the new face and generated a new identifier.

Query Parameters

Element Description Notes
min-cpq Refers to Center Pose Quality. Set to 0 to ensure that image insertion is not rejected due to poor facial image quality. The API normally rejects the insertion of facial images that don't have sufficient quality, according to configurable criteria to be used as solid reference. Storing low-quality references degrades the accuracy of the system and should be avoided if possible.
min-fsq Refers to Face Sharpness Quality. See min-cpq notes.
min-fcq Refers to Face Contrast Quality. See min-cpq notes.
update Disallows or allows information from a new face to update image and metadata for a face that is a match to an identity already inserted in the indicated directory. Set to false to disallow the update from the new face. Set to true if the last face posted is to be used to update the existing matching reference (assuming it meets the insertion quality criteria).

See Also