People API in Wasabi AiR

20 May 2024
7 Minutes to read

People API in Wasabi AiR

Updated on 20 May 2024
7 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

Wasabi AiR identifies faces in videos and photos that are attached to a person. The following API endpoints allow performing operations on a person within Wasabi AiR.

Getting a Single Person

GET /api/data/v3/people/{person_id}

Response

{
	"person": {
		"person_id": "39d2a59c-2a79-4dec-8e01-3c862d846820",
		"name": "unknown",
		"is_known": false,
		"face_img_path": "d8402f6d8949e19010db80aebd45be2c/face/9a325483-4ae5-45c1-b2ec-bbb327a1f1fd.jpg",
		"face_img_width": 292,
		"face_img_height": 379,
		"face_img_small_path": "",
		"face_img_small_width": 0,
		"face_img_small_height": 0,
		"num_faces": 1,
		"created_at": "2018-12-19T15:22:10.788526Z",
		"updated_at": "2018-12-19T15:22:10.788526Z"
	}
}

A 404 (Not Found) status is returned if the {person_id} is not found.

Listing People

GET /api/data/v3/people

Query Parameters

limit - (default:100, min: 1, max: 1000)
direction - Possible values: ASC, DESC
sort - Possible values: count, date, name (default: count)
type - Possible values: known, unknown
itemIDs - Comma-separated list of item IDs
trained - Only show trained people (true or false)

Response

{
	"next_page_token": "",
	"people": [
		{
			"person_id": "39d2a59c-2a79-4dec-8e01-3c862d846820",
			"name": "unknown",
			"is_known": false,
			"face_img_path": "d8402f6d8949e19010db80aebd45be2c/face/9a325483-4ae5-45c1-b2ec-bbb327a1f1fd.jpg",
			"face_img_width": 292,
			"face_img_height": 379,
			"face_img_small_path": "",
			"face_img_small_width": 0,
			"face_img_small_height": 0,
			"num_faces": 1,
			"created_at": "2018-12-19T15:22:10.788526Z",
			"updated_at": "2018-12-19T15:22:10.788526Z"
        },
		...
	]
}

Searching for People

GET /api/data/v3/people/search?q={query}

Response

{
	"query": "Cook",
	"people": [
		{
			"person_id": "dc50e388-6e78-4ec3-a0ba-b7f5d086c423",
			"name": "Tim Cook",
			"is_known": true,
			"face_img_path": "75e7b81a98a4d5f96c71479eec5b3079/face/5ad67fc0-9d30-4e16-8802-2bef0eaec050.jpg",
			"face_img_width": 579,
			"face_img_height": 843,
			"face_img_small_path": "",
			"face_img_small_width": 0,
			"face_img_small_height": 0,
			"num_faces": 56,
			"created_at": "2018-12-19T15:24:52.572816Z",
			"updated_at": "2018-12-19T15:24:52.572816Z"
		}
	]
}

A non-empty query is required.

Getting a Person Timeline Within an Item

GET /api/data/v3/people/search?q={query}

Response

The response provides the highest quality identification face and its image paths alongside a histogram of all face appearances and a list of emotions that each have associated histograms.

For a video:

{
    "person": {
        "face_id": "5cddf4bb91bd23615d4747d0b09bce67",
        "face_img_path": "339e5c9bd8e2703d6585c4c8a41c1138/face/5cddf4bb91bd23615d4747d0b09bce67.jpg",
        "face_img_sm_path": "339e5c9bd8e2703d6585c4c8a41c1138/face/5cddf4bb91bd23615d4747d0b09bce67_sm.jpg",
        "histogram": [
            {
                "start": 45.5,
                "end": 49
            },
            {
                "start": 67.5,
                "end": 71
            },
            {
                "start": 79,
                "end": 86.5
            },
            {
                "start": 374,
                "end": 380.5
            },
            {
                "start": 381.5,
                "end": 385
            },
            {
                "start": 552,
                "end": 552.5
            },
            {
                "start": 649,
                "end": 650
            }
        ],
        "emotions": [
            {
                "emotion": "angry",
                "histogram": [
                    {
                        "start": 45.5,
                        "end": 46
                    },
                    {
                        "start": 48,
                        "end": 48.5
                    },
                    {
                        "start": 67.5,
                        "end": 68.5
                    },
                    {
                        "start": 379.5,
                        "end": 380
                    },
                    {
                        "start": 383.5,
                        "end": 384
                    },
                    {
                        "start": 384.5,
                        "end": 385
                    }
                ]
            },
            {
                "emotion": "fear",
                "histogram": [
                    {
                        "start": 46,
                        "end": 46.5
                    }
                ]
            },
            {
                "emotion": "neutral",
                "histogram": [
                    {
                        "start": 46.5,
                        "end": 48
                    },
                    {
                        "start": 48.5,
                        "end": 49
                    },
                    {
                        "start": 68.5,
                        "end": 71
                    },
                    {
                        "start": 79,
                        "end": 81
                    },
                    {
                        "start": 82,
                        "end": 86.5
                    },
                    {
                        "start": 374,
                        "end": 379
                    },
                    {
                        "start": 381.5,
                        "end": 382
                    },
                    {
                        "start": 382.5,
                        "end": 383
                    },
                    {
                        "start": 384,
                        "end": 384.5
                    },
                    {
                        "start": 649,
                        "end": 650
                    }
                ]
            },
            {
                "emotion": "sad",
                "histogram": [
                    {
                        "start": 81,
                        "end": 82
                    },
                    {
                        "start": 379,
                        "end": 379.5
                    },
                    {
                        "start": 380,
                        "end": 380.5
                    },
                    {
                        "start": 382,
                        "end": 382.5
                    },
                    {
                        "start": 383,
                        "end": 383.5
                    },
                    {
                        "start": 552,
                        "end": 552.5
                    }
                ]
            }
        ]
    }
}

For a document:

{
    "person": {
        "face_id": "5cd4878d5e234f1b564d0ceb8bf1e5d2",
        "face_img_path": "07754b406b6ebf4ea9c74cd416f7f38e/face/5cd4878d5e234f1b564d0ceb8bf1e5d2.jpg",
        "face_img_sm_path": "07754b406b6ebf4ea9c74cd416f7f38e/face/5cd4878d5e234f1b564d0ceb8bf1e5d2_sm.jpg",
        "histogram": [
            {
                "start": 2,
                "end": 2
            },
            {
                "start": 6,
                "end": 6
            },
            {
                "start": 41,
                "end": 43
            }
        ],
        "emotions": [
            {
                "emotion": "happy",
                "histogram": [
                    {
                        "start": 2,
                        "end": 2
                    },
                    {
                        "start": 6,
                        "end": 6
                    },
                    {
                        "start": 41,
                        "end": 43
                    }
                ]
            }
        ]
    }
}

Response

A successful response returns a 200 (Status OK) while any unexpected error returns a 500 (Status Internal Server Error).

Getting Total People and Faces Counts

GET /api/data/v3/people/stats

Response

{
	"num_known": 1,
	"num_unknown": 18
}

Creating a New Person With Faces

POST /api/data/v3/people

{
	"name": "Tim Cook",
	"face_ids": ["080f3382-97cf-4655-a9c4-f6bf003ee903"]
}

Response

When PersonType is known:

{
    "person": {
        "person_id": "84471a6f-bba5-44e0-b60e-d507d49a0d6a",
        "name": "Tim ",
        "is_known": true,
        "face_img_path": "",
        "face_img_width": 0,
        "face_img_height": 0,
        "face_img_small_path": "",
        "face_img_small_width": 0,
        "face_img_small_height": 0,
        "num_faces": 0,
        "created_at": "2019-01-07T20:43:03.881199Z",
        "updated_at": "2019-01-07T20:43:03.881199Z"
    },
    "face_ids": [
        "080f3382-97cf-4655-a9c4-f6bf003ee903"
    ]
}

When PersonType is unknown:

{
    "person": [
        {
            "person_id": "84471a6f-bba5-44e0-b60e-d507d49a0d6a",
            "name": "unknown",
            "is_known": false,
            "face_img_path": "",
            "face_img_width": 0,
            "face_img_height": 0,
            "face_img_small_path": "",
            "face_img_small_width": 0,
            "face_img_small_height": 0,
            "num_faces": 0,
            "created_at": "2019-01-07T20:43:03.881199Z",
            "updated_at": "2019-01-07T20:43:03.881199Z"
        },
        {
            "person_id": "82461a6f-abb5-73e0-b667-d507d02a0d5b",
            "name": "unknown",
            "is_known": false,
            "face_img_path": "",
            "face_img_width": 0,
            "face_img_height": 0,
            "face_img_small_path": "",
            "face_img_small_width": 0,
            "face_img_small_height": 0,
            "num_faces": 0,
            "created_at": "2019-04-08T20:43:03.881199Z",
            "updated_at": "2019-04-08T20:43:03.881199Z"
        },
        ...
    ],
    "face_ids": [
        "080f3382-97cf-4655-a9c4-f6bf003ee903",
        "dc50e388-6e78-4ec3-a0ba-b7f5d086c423",
        ...
    ]
}

Renaming a Person Within an Item

POST /api/data/v3/people

{
    "name": "Tim Cook",
    "prev_person_id": "84471a6f-bba5-44e0-b60e-d507d49a0d6a",
    "item_id": "92236ca71f29d3a3e90e115206450195"
}

Response

{
    "person": {
        "person_id": "84471a6f-bba5-44e0-b60e-d507d49a0d6a",
        "name": "Tim ",
        "is_known": true,
        "face_img_path": "",
        "face_img_width": 0,
        "face_img_height": 0,
        "face_img_small_path": "",
        "face_img_small_width": 0,
        "face_img_small_height": 0,
        "num_faces": 0,
        "created_at": "2019-01-07T20:43:03.881199Z",
        "updated_at": "2019-01-07T20:43:03.881199Z"
    },
    "face_ids": [
        "080f3382-97cf-4655-a9c4-f6bf003ee903"
    ]
}

A 202 (Accepted) status is returned upon success. A 422 (Unprocessable Entity) status is returned for any conflicts.

Renaming a Person

PUT /api/data/v3/people/{person_id}

{
	"name": "Some Other User"
}

Response

{
	"person": {
		"person_id": "95324750-2ea7-4629-9f53-a730f825ae82",
		"name": "Some Other User",
		"is_known": true,
		"face_img_path": "",
		"face_img_width": 0,
		"face_img_height": 0,
		"face_img_small_path": "",
		"face_img_small_width": 0,
		"face_img_small_height": 0,
		"num_faces": 0,
		"created_at": "2019-01-07T20:12:39.094341Z",
		"updated_at": "2019-01-07T20:18:21.345036Z"
	}
}

A 404 (Not Found) status is returned if the {person_id} is not found. A 422 (Unprocessable Entity) status is returned if a constraint is violated.

Listing a Person’s Items

GET /api/data/v3/people/{person_id}/items

A 404 (Not Found) status is returned if the {person_id} is not found.

Response

{
	"person_id": "95324750-2ea7-4629-9f53-a730f825ae82",
	"item_ids": []
}

A 404 (Not Found) status is returned if the {person_id} is not found.

Listing a Person’s Faces

GET /api/data/v3/people/{person_id}/faces

Query Parameters

limit (default: 100, min: 1, max: 1000)
item_id (optional) - Narrow the list of faces to a particular item. If provided, the faces are returned in the order in which they appear in the content.
trained (optional) - Show only trained faces (true/false).

Response

{
	"person_id": "95324750-2ea7-4629-9f53-a730f825ae82",
	"person": {
		"person_id": "95324750-2ea7-4629-9f53-a730f825ae82",
		"name": "Some Other User",
		"is_known": true,
		"face_img_path": "",
		"face_img_width": 0,
		"face_img_height": 0,
		"face_img_small_path": "",
		"face_img_small_width": 0,
		"face_img_small_height": 0,
		"num_faces": 0,
		"created_at": "2019-01-07T20:12:39.094341Z",
		"updated_at": "2019-01-07T20:18:21.345036Z"
	},
	"faces": [
		{
			"face_id": "080f3382-97cf-4655-a9c4-f6bf003ee903",
			"face_img_path": "92236ca71f29d3a3e90e115206450195/face/b0007440-c6d1-4880-a397-c280baed567e.jpg",
			"face_img_width": 754,
			"face_img_height": 948,
			"face_img_small_path": "",
			"face_img_small_width": 0,
			"face_img_small_height": 0,
			"person_id": "95324750-2ea7-4629-9f53-a730f825ae82",
			"item_id": "92236ca71f29d3a3e90e115206450195",
			"segment_index": -1,
			"face_detection_source": "gm_faces",
			"face_detection_confidence": 0.9997,
			"face_detection_blurriness": 0.19,
			"face_rectangle": {
				"top": 105,
				"left": 609,
				"width": 754,
				"height": 948
			},
			"used_for_training": false,
			"recognition_source": "gm_faces",
			"recognition_confidence": 0.61,
			"recognition_match": false,
			"source_img_path": "thumbnailer/thumb.jpg",
			"source_img_width": 1600,
			"source_img_height": 1200,
			"gender": "",
			"age": 0,
			"emotion": "neutral",
			"hat": false,
			"glasses": false,
			"facial_hair": false,
			"created_at": "2018-12-19T15:21:05.517292Z",
			"updated_at": "2018-12-19T20:03:11.478449Z",
			"deleted": false
		},
		...
	],
	"next_page_token": ""
}

A 404 (Not Found) status is returned if the {person_id} is not found.

Associating Faces With a Person

List of Faces

PATCH /api/data/v3/people/{person_id}/faces

{
	"face_ids": ["080f3382-97cf-4655-a9c4-f6bf003ee903"]
}

Response

{
    "ok": true
}

A 404 (Not Found) status is returned if the {person_id} is not found.

All Faces From a Different Person

PATCH /api/data/v3/people/{person_id}/faces

{
	"all": true,
	"previous_person_id": "dc50e388-6e78-4ec3-a0ba-b7f5d086c423"
}

Response

{
    "ok": true
}

A 404 (Not Found) status is returned if the {person_id} is not found.

Setting a List of Faces to Train a Person

POST /api/data/v3/people/{person_id}/train

{
	"face_ids": ["080f3382-97cf-4655-a9c4-f6bf003ee903"]
}

Response

{
    "trained": true,
    "person_id": "dc50e388-6e78-4ec3-a0ba-b7f5d086c423",
    "name": "Tim Cook",
    "face_ids": [
        "080f3382-97cf-4655-a9c4-f6bf003ee903"
    ],
    "replaced_faces": [
        {
            "face_id": "5e2739cc5c383fed942204e6be77750a",
            "old_face_id": "5187feb5044ef4485e7bc0e2e72f79d1",
            "old_person_model_id": "21",
            "old_person_type": "known",
        },
        ...
    ]
}

A 202 (Accepted) status is turned upon success. A 404 (Not Found) status is returned if the {person_id} is not found.

Uploading an Image to Train a Person (AI Studio)

POST /api/data/train/people/{person_id}

content-type: multipart/form-data

face=@/path/to/image.jpg

Response

{
    "face_id": "40d8a1e0-5425-4c85-9676-33ad9826fe0f",
    "face_img_path": "21f3a8f6-f4fd-4f4c-9669-b41d425972bb/faces/d76c124d-2222-4d2b-89b3-80553b79e673.jpg",
    "face_img_width": 188,
    "face_img_height": 238,
    "face_img_small_path": "21f3a8f6-f4fd-4f4c-9669-b41d425972bb/faces/d76c124d-2222-4d2b-89b3-80553b79e673_sm.jpg",
    "face_img_small_width": 100,
    "face_img_small_height": 127,
    "person_id": "21f3a8f6-f4fd-4f4c-9669-b41d425972bb",
    "item_id": "",
    "segment_index": 0,
    "face_detection_source": "gm_faces",
    "face_detection_confidence": 0.9997,
    "face_detection_blurriness": 0.08,
    "face_rectangle": {
        "top": 110,
        "left": 199,
        "width": 188,
        "height": 238
    },
    "used_for_training": true,
    "recognition_source": "user",
    "recognition_confidence": 100,
    "recognition_match": true,
    "source_img_path": "21f3a8f6-f4fd-4f4c-9669-b41d425972bb/face-training-uploads/d76c124d-2222-4d2b-89b3-80553b79e673.jpg",
    "source_img_width": 600,
    "source_img_height": 600,
    "gender": "",
    "age": 0,
    "emotion": "",
    "hat": false,
    "glasses": false,
    "facial_hair": false,
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "deleted": false
}

A 200 (OK) status is returned upon success. A 400 (Bad Request) is returned with an error message if there is a problem with the image.

Getting a List of All People

This endpoint returns a list of all people.

GET /api/data/v3/people

Optional Queries

{trained} - (boolean) Show only trained or untrained people.

Response

{
    "people": [
        {
            "person_id": "9fa5065c-e766-4790-82e3-51e452d2eafe",
            "name": "New Person",
            "is_known": true,
            "used_for_training": true,
            "face_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
            "face_img_width": 136,
            "face_img_height": 178,
            "face_img_small_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388_sm.jpg",
            "face_img_small_width": 100,
            "face_img_small_height": 131,
            "num_faces": 1,
            "created_at": "2020-01-09T20:46:54.031468Z",
            "updated_at": "2020-01-09T20:46:54.031468Z"
        }
    ]
    "next_page_token": "",
}

A 200 (OK) status is returned upon success. A 404 (Unknown) is returned if the person is not found.

Getting a List of Person’s Faces

This endpoint returns a list of all faces for a person.

GET /api/data/v3/people/{person_id}/faces

Optional Queries

{trained} - (boolean) Show only trained or untrained faces.

Response

{
    "person_id": "9fa5065c-e766-4790-82e3-51e452d2eafe",
    "person": {
        "person_id": "9fa5065c-e766-4790-82e3-51e452d2eafe",
        "name": "New Person",
        "is_known": true,
        "used_for_training": true,
        "face_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
        "face_img_width": 136,
        "face_img_height": 178,
        "face_img_small_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388_sm.jpg",
        "face_img_small_width": 100,
        "face_img_small_height": 131,
        "num_faces": 1,
        "created_at": "2020-01-09T20:46:54.031468Z",
        "updated_at": "2020-01-09T20:46:54.031468Z"
    },
    "faces": [
        {
            "face_id": "5e1799b05d741cde0ee5d54263ad1b9a",
            "face_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
            "face_img_width": 136,
            "face_img_height": 178,
            "face_img_small_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388_sm.jpg",
            "face_img_small_width": 100,
            "face_img_small_height": 131,
            "person_id": "9fa5065c-e766-4790-82e3-51e452d2eafe",
            "item_id": "",
            "segment_index": 0,
            "face_detection_source": "gm_faces",
            "face_detection_confidence": 0.9995,
            "face_detection_blurriness": 0.15,
            "face_rectangle": {
                "top": 55,
                "left": 162,
                "width": 136,
                "height": 178
            },
            "used_for_training": true,
            "recognition_source": "user",
            "recognition_confidence": 100,
            "recognition_match": true,
            "source_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/face-training-uploads/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
            "source_img_width": 480,
            "source_img_height": 480,
            "gender": "",
            "age": 0,
            "emotion": "",
            "hat": false,
            "glasses": false,
            "facial_hair": false,
            "created_at": "2020-01-09T21:22:56.289263Z",
            "updated_at": "2020-01-09T21:22:56.289263Z",
            "deleted": false
        }
    ],
    "next_page_token": ""
}

A 200 (OK) status is returned upon success. A 404 (Unknown) is returned if the person is not found.

Creating a Person

This endpoint creates a new person.

POST /api/data/v3/people/create
{
	"name": "Person Name",
	"person_model_type": "known"
}

name - (string) A new person's name.
person_model_type - (string) Person type (known, unknown).

Response

{
	"name": "Person Name",
	"person_model_id": "5e0a963cbd2c38fe4b96c36db865a890",
	"person_model_type": "known"
}

A 200 (OK) status is returned upon success.

Uploading an Image to Train a Person

This endpoint enables you to upload a JPG or PNG image and train that image as a face for a specific person.

POST /api/data/v3/people/{person_id}/train/faces

file - (file) Form data for a JPG or PNG image.

Response

{
    "face_id": "5e1799b05d741cde0ee5d54263ad1b9a",
    "face_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
    "face_img_width": 136,
    "face_img_height": 178,
    "face_img_small_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/faces/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388_sm.jpg",
    "face_img_small_width": 100,
    "face_img_small_height": 131,
    "person_id": "9fa5065c-e766-4790-82e3-51e452d2eafe",
    "item_id": "",
    "segment_index": 0,
    "face_detection_source": "gm_faces",
    "face_detection_confidence": 0.9995,
    "face_detection_blurriness": 0.15,
    "face_rectangle": {
        "top": 55,
        "left": 162,
        "width": 136,
        "height": 178
    },
    "used_for_training": true,
    "recognition_source": "user",
    "recognition_confidence": 100,
    "recognition_match": true,
    "source_img_path": "9fa5065c-e766-4790-82e3-51e452d2eafe/face-training-uploads/a1b6b09d-d5bf-4dfb-af6f-ff8b6251a388.jpg",
    "source_img_width": 480,
    "source_img_height": 480,
    "gender": "",
    "age": 0,
    "emotion": "",
    "hat": false,
    "glasses": false,
    "facial_hair": false,
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "deleted": false
}

A 200 (OK) status is returned upon success. A 404 (Unknown) is returned if the person is not found.

What's Next

Roles API in Wasabi AiR

Table of contents

Getting a Single Person
Listing People
Searching for People
Getting a Person Timeline Within an Item
Getting Total People and Faces Counts
Creating a New Person With Faces
Renaming a Person Within an Item
Renaming a Person
Listing a Person’s Items
Listing a Person’s Faces
Associating Faces With a Person
Setting a List of Faces to Train a Person
Uploading an Image to Train a Person (AI Studio)
Getting a List of All People
Getting a List of Person’s Faces
Creating a Person
Uploading an Image to Train a Person