Rekognition Class

Analyzes faces on images and videos using machine learning.

Instance Methods

Name Description
public constructor() Constructs a rekognition client object.
Parameters:
  • options.region: string
    The region to send service requests to.
  • options.accessKeyId: string
    AWS access key ID.
  • options.secretAccessKey: string
    AWS secret access key.
  • options.timeout: number
    Timeout period (milliseconds). Default is 5000.
import * as sweet from 'express-sweet';
            
const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});
public detectFaces() Detects faces within an image that is provided as input.
For each face detected, the operation returns a bounding box of the face.
Parameters:
  • img: string
    Image path or Data Url or image buffer.
  • minConfidence: number
    The minimum confidence of the detected face. Faces with a confidence lower than this value will not be returned as a result.
  • withDetails: boolean
    If false, returns only the face bounding box. When true, returns the age group, gender, and emotion in addition to the face bounding box.
Return:
import * as sweet from 'express-sweet';
import fs from 'fs';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Detects bounding boxes on faces.
// results in:  [
//            {
//              width: 0.3099822998046875,
//              height: 0.661512017250061,
//              left: 0.5449195504188538,
//              top: 0.11531734466552734
//            }
//          ]
let res = await client.detectFaces('img/face2.jpg');
console.log(res);

// Detect facial details.
// results in:  [
//            {
//              boundingBox: {
//                width: 0.3099822998046875,
//                height: 0.661512017250061,
//                left: 0.5449195504188538,
//                top: 0.11531734466552734
//              },
//              ageRange: { high: 14, low: 6 },
//              gender: 'female',
//              emotions: {
//                happy: 99.78905487060547,
//                surprised: 6.306276321411133,
//                fear: 5.880091190338135,
//                sad: 2.152125835418701,
//                confused: 0.023256277665495872,
//                angry: 0.018351631239056587,
//                calm: 0.015775982290506363,
//                disgusted: 0.013914424926042557
//              }
//            }
//          ]
const minConfidence = 90;
const withDetails = true;
res = await client.detectFaces('img/face2.jpg', minConfidence, withDetails);
console.log(res);

// Detect faces from data URL.
await client.detectFaces('data:image/png;base64,/9j/4...');

// Detect faces from buffer.
await client.detectFaces(fs.readFileSync('img.jpg'));
const sweet = require('express-sweet');
const fs = require('fs');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Detects bounding boxes on faces.
// results in:  [
//            {
//              width: 0.3099822998046875,
//              height: 0.661512017250061,
//              left: 0.5449195504188538,
//              top: 0.11531734466552734
//            }
//          ]
let res = await client.detectFaces('img/face2.jpg');
console.log(res);

// Detect facial details.
// results in:  [
//            {
//              boundingBox: {
//                width: 0.3099822998046875,
//                height: 0.661512017250061,
//                left: 0.5449195504188538,
//                top: 0.11531734466552734
//              },
//              ageRange: { high: 14, low: 6 },
//              gender: 'female',
//              emotions: {
//                happy: 99.78905487060547,
//                surprised: 6.306276321411133,
//                fear: 5.880091190338135,
//                sad: 2.152125835418701,
//                confused: 0.023256277665495872,
//                angry: 0.018351631239056587,
//                calm: 0.015775982290506363,
//                disgusted: 0.013914424926042557
//              }
//            }
//          ]
const minConfidence = 90;
const withDetails = true;
res = await client.detectFaces('img/face2.jpg', minConfidence, withDetails);
console.log(res);

// Detect faces from data URL.
await client.detectFaces('data:image/png;base64,/9j/4...');

// Detect faces from buffer.
await client.detectFaces(fs.readFileSync('img.jpg'));
public compareFaces() Compare the similarity of two faces.
Parameters:
  • img1: string
    Image path or Data Url or image buffer.
  • img2: string
    Image path or Data Url or image buffer.
Return:
  • Promise<number> Level of confidence that the faces match.
import * as sweet from 'express-sweet';
import fs from 'fs';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Compare faces from path.
await client.compareFaces('img1.jpg', 'img2.jpg');

// Compare faces from data URL.
await client.compareFaces('data:image/png;base64,/9j/4...', 'data:image/png;base64,/9j/4...');

// Compare faces from buffer.
await client.compareFaces(fs.readFileSync('img1.jpg'), fs.readFileSync('img1.jpg'));
const sweet = require('express-sweet');
const fs = require('fs');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Compare faces from path.
await client.compareFaces('img1.jpg', 'img2.jpg');

// Compare faces from data URL.
await client.compareFaces('data:image/png;base64,/9j/4...', 'data:image/png;base64,/9j/4...');

// Compare faces from buffer.
await client.compareFaces(fs.readFileSync('img1.jpg'), fs.readFileSync('img1.jpg'));
public createCollection() Add faces to the collection using the IndexFaces operation.
For example, you might create collections, one for each of your application users.
A user can then index faces using the IndexFaces operation and persist results in a specific collection.
Then, a user can search the collection for faces in the user-specific container.
Note that Collection names are case-sensitive.
Parameters:
  • collectionId: string
    ID for the collection that you are creating. The maximum length is 255, and the characters that can be used are [a-zA-Z0-9_.\-]+.
import * as sweet from 'express-sweet';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Creates a collection.
await client.createCollection('MyCollection');
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Creates a collection.
await client.createCollection('MyCollection');
public listCollections() Returns list of collection IDs.
Return:
  • Promise<string[]> An array of collection IDs.
import * as sweet from 'express-sweet';
        
const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Find the collection IDs.
// results in: [
//           'MyCollection',
//           'AnotherCollection'
//         ]
await client.listCollections();
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Find the collection IDs.
// results in: [
//           'MyCollection',
//           'AnotherCollection'
//         ]
await client.listCollections();
public deleteCollection() Deletes the specified collection.
Note that this operation removes all faces in the collection.
Parameters:
  • collectionId: string
    ID of the collection to delete.
Return:
  • Promise<boolean> True on success.
import * as sweet from 'express-sweet';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Delete collection.
await client.deleteCollection('MyCollection');
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Delete collection.
await client.deleteCollection('MyCollection');
public indexFace() Detects one face in the input image and adds it to the specified collection.
Note that this method is used to index one face.
Throws an exception if no face is found in the input image or multiple faces are found.
Parameters:
  • collectionId: string
    The ID of an existing collection to which you want to add the faces that are detected in the input images.
  • img: string
    Image path or Data Url or image buffer.
  • options.externalImageId: string|undefined
    The ID you want to assign to the faces detected in the image.
    When you call the listFaces operation, the response returns the external ID.
    You can use this external image ID to create a client-side index to associate the faces with each image.
    You can then use the index to find all faces in an image.
    The maximum length is 255, and the characters that can be used are [a-zA-Z0-9_.\-:]+.
  • options.returnDetails: boolean
    If false, only the face ID of the created face is returned.
    If true, returns the face ID of the created face, plus age range, gender, and emotion.
Return:
  • Promise<string|IndexFaceDetails>
    If options.returnDetails is false, the face identifier is returned.
    If options.returnDetails is true, returns the gender, age group, and emotion in addition to the face identifier. 
import * as sweet from 'express-sweet';
import fs from 'fs';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Create a face and get the ID of the created face.
// results in: e65d66cb-e7bc-4bbf-966c-b1b49ddf29f8
const faceId = await client.indexFace(collectionId, 'img.jpg');
console.log(faceId);

// Create a face and get the details of the created face.
// results in:  {
//            faceId: '7f2dd321-f047-44ff-8856-864637e1d286',
//            ageRange: { high: 29, low: 21 },
//            gender: 'female',
//            emotions: {
//              angry: 77.1907958984375,
//              surprised: 9.944050788879395,
//              fear: 7.514361381530762,
//              confused: 4.780297756195068,
//              sad: 2.91914963722229,
//              happy: 2.5718722343444824,
//              disgusted: 1.933768391609192,
//              calm: 1.5354809761047363
//            }
//          }
const faceDetails = await client.indexFace(collectionId, 'img.jpg', {returnDetails: true});
console.log(faceDetails);

// You can also index face images in DataURL format.
await client.indexFace('MyCollection', 'data:image/png;base64,/9j/4...');

// Buffer face images can also be indexed.
await client.indexFace('MyCollection', fs.readFileSync('img.jpg'));
const sweet = require('express-sweet');
const fs = require('fs');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Create a face and get the ID of the created face.
// results in: e65d66cb-e7bc-4bbf-966c-b1b49ddf29f8
const faceId = await client.indexFace(collectionId, 'img.jpg');
console.log(faceId);

// Create a face and get the details of the created face.
// results in:  {
//            faceId: '7f2dd321-f047-44ff-8856-864637e1d286',
//            ageRange: { high: 29, low: 21 },
//            gender: 'female',
//            emotions: {
//              angry: 77.1907958984375,
//              surprised: 9.944050788879395,
//              fear: 7.514361381530762,
//              confused: 4.780297756195068,
//              sad: 2.91914963722229,
//              happy: 2.5718722343444824,
//              disgusted: 1.933768391609192,
//              calm: 1.5354809761047363
//            }
//          }
const faceDetails = await client.indexFace(collectionId, 'img.jpg', {returnDetails: true});
console.log(faceDetails);

// You can also index face images in DataURL format.
await client.indexFace('MyCollection', 'data:image/png;base64,/9j/4...');

// Buffer face images can also be indexed.
await client.indexFace('MyCollection', fs.readFileSync('img.jpg'));
public searchFaces() For a given input image, first detects the largest face in the image, and then searches the specified collection for matching faces.
The operation compares the features of the input face with faces in the specified collection.
Parameters:
  • collectionId: string
    ID of the collection to search.
  • img: string
    Image path or Data Url or image buffer.
  • options.minConfidence: number
    Specifies the minimum confidence in the face match to return.
    The default value is 80%.
  • options.maxFaces: number
    Maximum number of faces to return.
    The operation returns the maximum number of faces with the highest confidence in the match.
    The default value is 5.
  • options.throwNotFoundFaceException: boolean
    If true, throws a FaceMissingInPhoto exception when a face is not found in the image; if false, returns null. Default is false.
  • options.throwTooManyFaceException: booleanr
    If true, throws a FacesMultipleInPhoto exception when more than one face is found in the image. Default is false.
Return:
  • Promise<FaceMatch[]|FaceMatch|null>
    If options.maxFaces is 1, the face information found is returned.
    If options.maxFaces is 2 or more, the list of face information found is returned.
    Returns null if no face is found. 
import * as sweet from 'express-sweet';
import fs from 'fs';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// If you want to search for one face, specify 1 for the maxFaces option.
// In that case, the search result will return the face data for one person.
// results in: {
//           faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//           boundingBox: {
//             width: 0.500495970249176,
//             height: 0.6926820278167725,
//             left: 0.2928670048713684,
//             top: 0.09095799922943115
//           },
//           externalImageId: 'img.jpg',
//           similarity: 99.98941802978516
//         }
const match = await client.searchFaces('MyCollection', 'img.jpg', {minConfidence: 99, maxFaces: 1});
console.log(match);

// If you want to search for multiple faces, specify 2 or more for the maxFaces option.
// In that case, the search results will return a list of the face data of multiple people found.
// results in: [
//           {
//             faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//             boundingBox: {
//               width: 0.500495970249176,
//               height: 0.6926820278167725,
//               left: 0.2928670048713684,
//               top: 0.09095799922943115
//             },
//             externalImageId: 'img.jpg',
//             similarity: 99.98941802978516
//           }
//         ]
const matches = await client.searchFaces('MyCollection', 'img.jpg', {minConfidence: 99, maxFaces: 5});
console.log(matches);

// The input image can specify a buffer or DataURL in addition to the image path.
await client.searchFaces('MyCollection', 'data:image/png;base64,/9j/4...');
await client.searchFaces('MyCollection', fs.readFileSync('img.jpg'));
const sweet = require('express-sweet');
const fs = require('fs');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// If you want to search for one face, specify 1 for the maxFaces option.
// In that case, the search result will return the face data for one person.
// results in: {
//           faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//           boundingBox: {
//             width: 0.500495970249176,
//             height: 0.6926820278167725,
//             left: 0.2928670048713684,
//             top: 0.09095799922943115
//           },
//           externalImageId: 'img.jpg',
//           similarity: 99.98941802978516
//         }
const match = await client.searchFaces('MyCollection', 'img.jpg', {minConfidence: 99, maxFaces: 1});
console.log(match);

// If you want to search for multiple faces, specify 2 or more for the maxFaces option.
// In that case, the search results will return a list of the face data of multiple people found.
// results in: [
//           {
//             faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//             boundingBox: {
//               width: 0.500495970249176,
//               height: 0.6926820278167725,
//               left: 0.2928670048713684,
//               top: 0.09095799922943115
//             },
//             externalImageId: 'img.jpg',
//             similarity: 99.98941802978516
//           }
//         ]
const matches = await client.searchFaces('MyCollection', 'img.jpg', {minConfidence: 99, maxFaces: 5});
console.log(matches);

// The input image can specify a buffer or DataURL in addition to the image path.
await client.searchFaces('MyCollection', 'data:image/png;base64,/9j/4...');
await client.searchFaces('MyCollection', fs.readFileSync('img.jpg'));
public listFaces() Returns metadata for faces in the specified collection.
This metadata includes information such as the bounding box coordinates, and face ID.
Parameters:
  • collectionId: string
    ID of the collection from which to list the faces.
  • maxResults: number
    Maximum number of faces to return.The default value is 1000.
Return:
  • Promise<FaceMatch[]> Returns all face metadata in the collection.
import * as sweet from 'express-sweet';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Find all face metadata in the collection.
// results in: [
//           {
//             faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//             boundingBox: {
//               width: 0.500495970249176,
//               height: 0.6926820278167725,
//               left: 0.2928670048713684,
//               top: 0.09095799922943115
//             },
//             externalImageId: 'img.jpg'
//           }
//         ]
const result = await client.listFaces('MyCollection');
console.log(result);
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Find all face metadata in the collection.
// results in: [
//           {
//             faceId: '2ce7f471-9c4b-4f27-b5a4-bbd02a5e134d',
//             boundingBox: {
//               width: 0.500495970249176,
//               height: 0.6926820278167725,
//               left: 0.2928670048713684,
//               top: 0.09095799922943115
//             },
//             externalImageId: 'img.jpg'
//           }
//         ]
const result = await client.listFaces('MyCollection');
console.log(result);
public deleteFaces() Deletes faces from a collection.
You specify a collection ID and an array of face IDs to remove from the collection.
Parameters:
  • collectionId: string
    Collection from which to remove the specific faces.
  • faceIds: string[]
    An array of face IDs to delete.
Return:
  • Promise<boolean> True on success.
import * as sweet from 'express-sweet';

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Delete a face from the collection.
await client.deleteFaces('MyCollection', ['f7befa24-3b83-43cc-b21f-7fac4b91f51d']);
const sweet = require('express-sweet');

const client = new sweet.services.AWSRekognitionClient({
  region: 'the region to send service requests to',
  accessKeyId: 'your AWS access key ID',
  secretAccessKey: 'your AWS secret access key',
});

// Delete a face from the collection.
await client.deleteFaces('MyCollection', ['f7befa24-3b83-43cc-b21f-7fac4b91f51d']);