Table of contents

Faces API

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:

  • Face - A single face detected in an image, or frame of video - belongs to a person.
  • Person - A group of faces, known or unknown.

Get people in an item DEPRECATED

GET /api/data/items/{item_id}/people
  • Supported query string parameters: 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"
        }
    ]
}

Person timeline in item DEPRECATED

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 a face

DELETE /api/data/v3/faces/{face_id}

Response: Empty Response Status Code: 204

Get face

Non Deleted Faces

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

Deleted Faces

Non Deleted Faces

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

Rename faces

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 Faces

Get Non-deleted faces

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 deleted faces

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 faces in item

DELETE /api/data/items/{item_id}/faces

Response:

{
    "ok": true
}

Response:

{
    "item_ids": [
        "ba229159863b1be217421c92c4975b4b",
        "c0a0f36e17bfb0e16e7b87ca6a7d4ca2",
        "da238962366168016bc3d7348c18c2a3"
    ]
}

Train Face

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

UnTrain Face

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 Face

DELETE /api/data/v3/faces/{face_id}

Response: NONE

Status Code: 204

Delete Faces in Batch

By FaceIDS

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

Face Stats

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.