People API

The GrayMeta platform identifies Faces in video and photos which are attached to a Person. The following API endpoints allow for performing operations on a Person within the GrayMeta platform.

Get 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"
	}
}

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

List People

GET /api/data/v3/people

Query Parameters:

limit
- Min: 1
- Max: 1000
- Default: 100
direction
- Possible Values: ASC, DESC
sort
- Default: count
- Possible Values: count, date, name
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"
        },
		...
	]
}

Search 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"
		}
	]
}

NOTE: A non-empty query is required.

Get Person Timeline within an Item

GET /api/data/v3/items/{item-id}/timeline/people/{people-id}

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 their own associated histograms.

For 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 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
                    }
                ]
            }
        ]
    }
}

Successful response will return a 200 (Status OK) while any unexpected error will return a 500 (Status Internal Server Error).

Get Total People and Faces Counts

GET /api/data/v3/people/stats

Response:

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

Create 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",
        ...
    ]
}

Rename 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"
    ]
}

NOTE: - A 202 (Accepted) status will be turned upon success. - A 422 (Unprocessable Entity) status will be returned for any conflicts.

Rename 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"
	}
}

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

List a Person’s Items

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

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

Response:

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

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

List a Person’s Faces

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

Query Parameters:

limit
- Min: 1
- Max: 1000
- Default: 100
item_id (optional) - narrow the list of faces to a particular item - if provided, the faces will be returned in the order in which they appear in the content
trained (optional) - only show 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": ""
}

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

Associate Faces with a Person

A list of faces

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

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

Response:

{
    "ok": true
}

NOTE: A 404 (Not Found) status will be 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
}

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

Set 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",
        },
        ...
    ]
}

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

Upload 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
}

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

Get a List of all People

This endpoint will return a list of all People

GET /api/data/v3/people

Optional Queries

{trained} - (boolean) Only show 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": "",
}

Note: - A 200 (OK) status will be returned upon success. - A 404 (Unknown) will be returned if person is not found

Get a List of Person’s Faces

This endpoint will return a list of all faces for that person.

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

Optional Queries

{trained} - (boolean) Only show 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": ""
}

Note: - A 200 (OK) status will be returned upon success. - A 404 (Unknown) will be returned if person is not found

Create Person

This endpoint will create a new Person.

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

name - (string) New persons name
person_model_type - (string) Person type (known, unknown)

Response:

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

Note: - A 200 (OK) status will be returned upon success.

Upload Image to Train a Person

This endpoint will allow you to upload a jpg or png image and train that image as a Face to 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
}

Note: - A 200 (OK) status will be returned upon success. - A 404 (Unknown) will be returned if person is not found

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

Table of contents

People API

Get a Single Person

Response:

List People

Query Parameters:

Response:

Search for People

Response:

Get Person Timeline within an Item

Response:

Get Total People and Faces Counts

Response:

Create New Person with Faces

Response:

Rename a Person within an item

Response:

Rename a Person

Response:

List a Person’s Items

Response:

List a Person’s Faces

Query Parameters:

Response:

Associate Faces with a Person

A list of faces

Response:

All faces from a different person

Response:

Set a List of Faces to Train a Person

Response:

Upload Image to Train a Person (AI Studio)

Response:

Get a List of all People

Optional Queries

Response:

Get a List of Person’s Faces

Optional Queries

Response:

Create Person

Response:

Upload Image to Train a Person

Response: