Table of contents

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

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

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

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

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.

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

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.

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.