The GrayMeta Platform detects faces within video frames and images, then assigns each one a unique ID. When it is confident, the Platform will group matching faces together. Groups of faces can be named to create a ‘Known Person’.
Exiting data sets can be uploaded to train the Platform to identify known people (e.g. celebrities). This is useful to “pre-train” the system prior to harvesting.
Concepts:
GET /api/data/items/{item_id}/people
count
, page
, sort
and direction
.sort
works for count, name and type. Type is either known or unknown; default is blank, which returns both types.Response:
{
"item_id": "1695b728425c6412e2f138c2b18221f4",
"page": 0,
"count": 50,
"sort": "count",
"direction": "ASC",
"total_people": 2,
"people": [
{
"person_id": "0ecf9ff2-0170-475d-8fe4-dbb4bd56d839",
"name": "Julia Roberts",
"is_known": true,
"face_img_path": "1695b728425c6412e2f138c2b18221f4/face/a56850aa-4254-41ac-8b2f-4df7b8c05b4f.jpg",
"face_img_width": 206,
"face_img_height": 274,
"num_faces": 1,
"created_at": "2018-08-24T13:50:07.60808Z",
"updated_at": "2018-09-02T00:46:55.670315Z"
},
{
"person_id": "1a8e46a3-1c8a-40bf-aa43-04998e39b05e",
"name": "unknown",
"is_known": false,
"face_img_path": "1695b728425c6412e2f138c2b18221f4/face/c0a46f89-646e-40db-aa49-bdd9038be2ba.jpg",
"face_img_width": 178,
"face_img_height": 221,
"num_faces": 1,
"created_at": "2018-08-24T04:53:17.635451Z",
"updated_at": "2018-09-05T07:04:42.94174Z"
}
]
}
GET /api/data/items/{item_id}/people/{person_id}/timeline
Response:
{
"person_id": "360be92c-3ff7-41fe-8f13-724423a54486",
"item_id": "fad0540e306e24e3e7d0ae49879b3c63",
"timeline": [
{
"start_at": 26.026,
"end_at": 26.026,
"count": 1,
"face_id": "170effc7-ae7e-46c0-b4ce-5c52d44259aa"
},
{
"start_at": 28.028,
"end_at": 28.028,
"count": 1,
"face_id": "98400979-dd73-41e1-9375-2ebd51ca8b21"
}
]
}
DELETE /api/data/v3/faces/{face_id}
Response: Empty Response Status Code: 204
GET /api/data/v3/faces/{face_id}
Response:
{
"face_id": "15f8c5e0-8bb0-455a-9939-0786ee5cf1e9",
"face_img_path": "fad0540e306e24e3e7d0ae49879b3c63/face/0e70c02c-6ec3-4909-a4d5-df7d6b1c3076.jpg",
"face_img_width": 53,
"face_img_height": 58,
"person_id": "151616bb-fa61-4dfe-bb7f-7a6580164f42",
"item_id": "fad0540e306e24e3e7d0ae49879b3c63",
"segment_index": 170.17,
"face_detection_source": "gm_faces",
"face_detection_confidence": 0.927,
"face_detection_blurriness": 0.27,
"face_rectangle": {
"top": 142,
"left": 386,
"width": 53,
"height": 58
},
"used_for_training": false,
"recognition_source": "gm_faces",
"recognition_confidence": 0.61,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000085.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-05T16:16:35.620057Z",
"updated_at": "2018-09-05T16:16:36.023721Z",
"deleted": false
}
or
Status Code: 404
Response
{
"error": {
"message": STRING,
"request_id": STRING
}
}
GET /api/data/v3/faces/{face_id}
Response:
{
"face_id": "15f8c5e0-8bb0-455a-9939-0786ee5cf1e9",
"face_img_path": "fad0540e306e24e3e7d0ae49879b3c63/face/0e70c02c-6ec3-4909-a4d5-df7d6b1c3076.jpg",
"face_img_width": 53,
"face_img_height": 58,
"person_id": "151616bb-fa61-4dfe-bb7f-7a6580164f42",
"item_id": "fad0540e306e24e3e7d0ae49879b3c63",
"segment_index": 170.17,
"face_detection_source": "gm_faces",
"face_detection_confidence": 0.927,
"face_detection_blurriness": 0.27,
"face_rectangle": {
"top": 142,
"left": 386,
"width": 53,
"height": 58
},
"used_for_training": false,
"recognition_source": "gm_faces",
"recognition_confidence": 0.61,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000085.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-05T16:16:35.620057Z",
"updated_at": "2018-09-05T16:16:36.023721Z",
"deleted": true
}
or
Status Code: 404
Response
{
"error": {
"message": STRING,
"request_id": STRING
}
}
POST /api/data/faces/rename
{
"person_id": "713e3c68-ebc1-46eb-a0db-b46e8f3424e4",
"face_ids": [
"7de40548-49c7-4977-9eca-f6cadd4a8b32",
"fe103ef9-f37c-4182-81ef-3f87161c3ae2",
"1a21322d-5851-4d46-b9e0-8817d10110f7",
"7bdf3aac-e63e-491f-b193-1708835a4ea6"
]
}
Response:
{
"ok": true
}
GET /api/data/v3/faces?limit=10
Note: Default size for limit if not provided is 5000 Response:
{
"next_page_token": "MTAtMTA=",
"faces": [
{
"face_id": "7fe3bd43-1dee-4373-9af4-b33d5ffb11d5",
"face_img_path": "ea6e20e0c20483773ec8594b3eca43c3/face/c9124867-4b57-4f70-84ee-83e29a00844d.jpg",
"face_img_width": 144,
"face_img_height": 183,
"person_id": "",
"item_id": "ea6e20e0c20483773ec8594b3eca43c3",
"segment_index": 292.305458,
"face_detection_source": "gm_faces",
"face_detection_confidence": 1,
"face_detection_blurriness": 0.25,
"face_rectangle": {
"top": 17,
"left": 312,
"width": 144,
"height": 183
},
"used_for_training": false,
"recognition_source": "gm_faces",
"recognition_confidence": 0.63,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000146.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-06T23:02:47.364337Z",
"updated_at": "2018-09-07T05:11:01.779312Z",
"deleted": false
}
]
}
GET /api/data/v3/faces?deleted=true
Response:
{
"next_page_token": "MTAtMTA=",
"faces": [
{
"face_id": "7fe3bd43-1dee-4373-9af4-b33d5ffb11d5",
"face_img_path": "ea6e20e0c20483773ec8594b3eca43c3/face/c9124867-4b57-4f70-84ee-83e29a00844d.jpg",
"face_img_width": 144,
"face_img_height": 183,
"person_id": "",
"item_id": "ea6e20e0c20483773ec8594b3eca43c3",
"segment_index": 292.305458,
"face_detection_source": "gm_faces",
"face_detection_confidence": 1,
"face_detection_blurriness": 0.25,
"face_rectangle": {
"top": 17,
"left": 312,
"width": 144,
"height": 183
},
"used_for_training": false,
"recognition_source": "gm_faces",
"recognition_confidence": 0.63,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000146.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-06T23:02:47.364337Z",
"updated_at": "2018-09-07T05:11:01.779312Z",
"deleted": true
}
]
}
DELETE /api/data/items/{item_id}/faces
Response:
{
"ok": true
}
Response:
{
"item_ids": [
"ba229159863b1be217421c92c4975b4b",
"c0a0f36e17bfb0e16e7b87ca6a7d4ca2",
"da238962366168016bc3d7348c18c2a3"
]
}
PATCH /api/data/v3/faces/{face_id}/train
{
"trained": true
}
Response:
{
"face": {
"face_id": "7fe3bd43-1dee-4373-9af4-b33d5ffb11d5",
"face_img_path": "ea6e20e0c20483773ec8594b3eca43c3/face/c9124867-4b57-4f70-84ee-83e29a00844d.jpg",
"face_img_width": 144,
"face_img_height": 183,
"person_id": "",
"item_id": "ea6e20e0c20483773ec8594b3eca43c3",
"segment_index": 292.305458,
"face_detection_source": "gm_faces",
"face_detection_confidence": 1,
"face_detection_blurriness": 0.25,
"face_rectangle": {
"top": 17,
"left": 312,
"width": 144,
"height": 183
},
"used_for_training": true,
"recognition_source": "gm_faces",
"recognition_confidence": 0.63,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000146.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-06T23:02:47.364337Z",
"updated_at": "2018-09-07T05:11:01.779312Z",
"deleted": false
}
}
PATCH /api/data/v3/faces/{face_id}/train
{
"trained": false
}
Response:
{
"face": {
"face_id": "7fe3bd43-1dee-4373-9af4-b33d5ffb11d5",
"face_img_path": "ea6e20e0c20483773ec8594b3eca43c3/face/c9124867-4b57-4f70-84ee-83e29a00844d.jpg",
"face_img_width": 144,
"face_img_height": 183,
"person_id": "",
"item_id": "ea6e20e0c20483773ec8594b3eca43c3",
"segment_index": 292.305458,
"face_detection_source": "gm_faces",
"face_detection_confidence": 1,
"face_detection_blurriness": 0.25,
"face_rectangle": {
"top": 17,
"left": 312,
"width": 144,
"height": 183
},
"used_for_training": false,
"recognition_source": "gm_faces",
"recognition_confidence": 0.63,
"recognition_match": false,
"source_img_path": "video_main_frames/frame-0000000146.jpg",
"source_img_width": 640,
"source_img_height": 360,
"gender": "",
"age": 0,
"emotion": "",
"hat": false,
"glasses": false,
"facial_hair": false,
"created_at": "2018-09-06T23:02:47.364337Z",
"updated_at": "2018-09-07T05:11:01.779312Z",
"deleted": false
}
"replaced_faces": [
{
"face_id": "5e2739cc5c383fed942204e6be77750a",
"old_face_id": "5187feb5044ef4485e7bc0e2e72f79d1",
"old_person_model_id": "21",
"old_person_type": "known",
},
...
]
}
DELETE /api/data/v3/faces/{face_id}
Response: NONE
Status Code: 204
DELETE /api/data/v3/faces?ids=1fe3bd43-1dee-4373-9af4-b33d5ffb11d5,2fe3bd43-1dee-4373-9af4-b33d5ffb11d5,3fe3bd43-1dee-4373-9af4-b33d5ffb11d5
Response: NONE
Status Code: 204
GET /api/data/v3/faces/stats
Response:
{
"total": 100000
}
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.
© 2021 GrayMeta, Inc.