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
    • Default: 100
  • direction
    • Possible Values: ASC, DESC
  • sort
    • Default: count
    • Possible Values: count, date, name
  • type
    • Possible Values: known, unknown

Response:

{
	"sort": "count",
	"direction": "ASC",
	"NextPageToken": "",
	"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 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:

{
    "person": {
        "person_id": "84471a6f-bba5-44e0-b60e-d507d49a0d6a",
        "name": "Tim Cook",
        "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

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.

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.