The easiest way to retrieve face images of a stored identity is by doing the following:
GET /person/<personId>/face
API and personId
returned by GET /people or GET /rootpeople
requests.This method works for cloud and locally hosted systems for images with and without application-level encryption applied to them. It is not, however, as efficient as other methods. For more information, see the Efficient method section.
curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"http://localhost:8086/person/<personId>/face"'
curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"https://cvos.real.com/person/<personId>/face"
Example:
curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd"
"https://cvos.real.com/person/60046fb9-5b5d-4d2b-a3aa-6345e43da53d/face"
For a highly efficient and the most direct method of retrieval of images stored for identities, use the identity image URL. The stored identity image URL is returned by GET /people
and GET /rootpeople
requests in the imageURI
property. The image referenced is used to represent the identity.
Note: Use unmergedImageURIis
if the image that is different from the one referenced by imageURI
exists for the identity and can be used to retrieve the image of the specific face modality (for example, a facial image with sunglasses) associated with a matching personId
.
For a locally hosted system
For a locally hosted system, the provided URI will be of the following form: cvos://obj/<image-guid>
Retrieve the image by issuing the following http://
request to the Object Server (CVOS) API endpoint:
curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION: userid:pwd"
"http://localhost:8086/obj/<imageguid>"
For a cloud hosted system
For images not requiring application-level decryption (applicable to some early and demo accounts), the provided UI will be of the following form: https://<path>
For application-level encrypted images, the provided URI will be of the following form: ehttps://<path>
Images referenced via the ehttps:// scheme will have to be decrypted after being downloaded before they can be viewed. The encrypted image data can be downloaded by using https:// protocol scheme with the same path: https://<path>
The decryption is described in the next section.
Images referenced via the https://
scheme (applicable to cloud accounts only when efficient image retrieval method is used) must be decrypted after being downloaded before they can be viewed. The encrypted image data can be downloaded by using the https://
protocol scheme with the same path provided in the https:// URL
: https://<path>
To decrypt the downloaded image:
Retrieve the account-specific decryption key using the following API request:
curl -X GET -H "X-RPC-DIRECTORY: main" -H "X-RPC-AUTHORIZATION:userid:pwd""https://covi.real.com/obj/imagekey"
The response contains a JSON formatted base64 form of the key: { "key": "<base64_encoded_key>"}
Example:
{ "key": "yJgLFSH/Ypsb1wycx2TzZnvTwCob4KZHrcIYgqZxrz0=" }
To decrypt the image, extract the 16-byte IV prefix from the encrypted image data and the rest of the data decrypted using the IV and the decryption key.
IV = first_16_bytes_of_encrypted_image_data
Key = base64Decode(base64_encoded_key)
EncryptedImageBody = encrypted_image_data_starting_with_byte_17
DecryptedImage = getCipher(AES/CBC/PKCSPadding).decode(IV, Key, EncryptedImageBody)
Example:
openssl dec -aes-256-cbc -in EncryptedImageBody.enc -out ImageBody.jpg -K $Key -iv $IV