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

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

View stats

GET /api/data/people/stats

Response:

{
    "num_people_known": 251,
    "num_people_unknown": 84,
    "num_faces": 435
}

Person timeline in item

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

All people

GET /api/data/people
  • Supported query string parameters: order, direction, page, count, and type.

Response:

{
    "page": 0,
    "count": 50,
    "sort": "count",
    "direction": "ASC",
    "total_people": 2,
    "people": [
        {
            "person_id": "0011e109-b268-4535-811f-6f56d23b64c8",
            "name": "unknown",
            "is_known": false,
            "face_img_path": "92c68108b7965840ac0a2e2099919061/face/fe659d90-5f53-410d-b4f5-aa82a838cbfd.jpg",
            "face_img_width": 79,
            "face_img_height": 69,
            "num_faces": 1,
            "created_at": "2018-09-02T00:47:17.304197Z",
            "updated_at": "2018-09-02T00:47:17.317852Z"
        },
        {
            "person_id": "00135473-b47b-4877-a189-55dece84b44a",
            "name": "unknown",
            "is_known": false,
            "face_img_path": "d24b51ea89f23cc6851425d46db1c552/face/c274bf36-d96b-4302-a062-0ea195d25840.jpg",
            "face_img_width": 75,
            "face_img_height": 55,
            "num_faces": 1,
            "created_at": "2018-09-02T00:48:29.447539Z",
            "updated_at": "2018-09-02T00:48:29.458275Z"
        }
    ]
}

Delete a face

DELETE /api/data/faces/{face_id}

Response:

{
    "ok": true
}

Get face

GET /api/data/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

{
    "error": {
        "message": "face not found"
    }
}

Rename person

PUT /api/data/people/{person_id}
{
    "name": "John Dough"
}

Response:

{
    "person_id": "7c85ab21-cbe3-474d-a436-1a08134804c5",
    "name": "John Dough",
    "is_known": true,
    "face_img_path": "caed806301a61a483588de4bc2ababac/face/928e7b7b-6534-4e7e-ba23-417914b8f44a.jpg",
    "face_img_width": 231,
    "face_img_height": 277,
    "num_faces": 1,
    "created_at": "2018-09-05T18:37:58.765648Z",
    "updated_at": "2018-09-05T18:39:50.630914Z"
}

Get person

GET /api/data/people/{person_id}

Response:

{
    "person_id": "7c85ab21-cbe3-474d-a436-1a08134804c5",
    "name": "John Dough",
    "is_known": true,
    "face_img_path": "caed806301a61a483588de4bc2ababac/face/928e7b7b-6534-4e7e-ba23-417914b8f44a.jpg",
    "face_img_width": 231,
    "face_img_height": 277,
    "num_faces": 1,
    "created_at": "2018-09-05T18:37:58.765648Z",
    "updated_at": "2018-09-05T18:39:50.630914Z"
}

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 /api/data/people/search?q={string}

Response:

{
    "query": "bo",
    "people": [
        {
            "person_id": "b2b8a8d1-37ff-4c3d-9df4-a34fa8c55273",
            "name": "Bob Hope",
            "is_known": true,
            "face_img_path": "35780ba430480c9f8bee79fc6869843a/face/bd4ff9ef-cfce-47c6-a068-b52fc9e9b462.jpg",
            "face_img_width": 116,
            "face_img_height": 148,
            "num_faces": 7,
            "created_at": "2018-09-06T20:22:30.877747Z",
            "updated_at": "2018-09-06T20:22:30.877747Z"
        },
        {
            "person_id": "80c2c7c4-7889-410a-a316-94665d901d11",
            "name": "Mariacarla Boscono",
            "is_known": true,
            "face_img_path": "e5eb057babad97c25f1327bc8b4a397b/face/d808a939-63b0-4196-988e-3cf82978dcbe.jpg",
            "face_img_width": 145,
            "face_img_height": 179,
            "num_faces": 5,
            "created_at": "2018-09-06T00:40:20.41108Z",
            "updated_at": "2018-09-06T00:40:20.418431Z"
        }
    ]
}

Get faces for person

GET /api/data/people/{person_id}/faces
  • Supported query string parameters: count, page

Response:

{
    "person": {
        "person_id": "5353b9ed-d21e-44ce-83f2-b9ade2b4318a",
        "name": "Beetlejuice",
        "is_known": true,
        "face_img_path": "3915930e281c1947fa4a096567102749/face/94e6fb27-4e7a-4ed5-a35f-56b5aa79214b.jpg",
        "face_img_width": 47,
        "face_img_height": 56,
        "num_faces": 6,
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "2018-09-06T17:51:33.24814Z"
    },
    "person_id": "5353b9ed-d21e-44ce-83f2-b9ade2b4318a",
    "page": 0,
    "count": 2,
    "faces": [
        {
            "face_id": "806dbf28-5538-4027-953d-d2aa11b64150",
            "face_img_path": "7d23ac3f90cd6ddb7c85ddadfc48ef12/face/c38ec44b-acf4-4ebf-bd14-1b419634f967.jpg",
            "face_img_width": 194,
            "face_img_height": 266,
            "person_id": "5353b9ed-d21e-44ce-83f2-b9ade2b4318a",
            "item_id": "7d23ac3f90cd6ddb7c85ddadfc48ef12",
            "segment_index": 28.028,
            "face_detection_source": "gm_faces",
            "face_detection_confidence": 1,
            "face_detection_blurriness": 0.25,
            "face_rectangle": {
                "top": 72,
                "left": 104,
                "width": 194,
                "height": 266
            },
            "used_for_training": false,
            "recognition_source": "gm_faces",
            "recognition_confidence": 0.66,
            "recognition_match": true,
            "source_img_path": "video_main_frames/frame-0000000014.jpg",
            "source_img_width": 640,
            "source_img_height": 427,
            "gender": "",
            "age": 0,
            "emotion": "",
            "hat": false,
            "glasses": false,
            "facial_hair": false,
            "created_at": "2018-09-06T00:41:25.379095Z",
            "updated_at": "2018-09-07T16:40:24.968658Z",
            "deleted": false
        },
        {
            "face_id": "0f7fdb1e-07b2-416d-a789-f6fb3c128c7f",
            "face_img_path": "3915930e281c1947fa4a096567102749/face/8b3be53b-d81f-4ab4-829a-6bca75f43f3c.jpg",
            "face_img_width": 49,
            "face_img_height": 59,
            "person_id": "5353b9ed-d21e-44ce-83f2-b9ade2b4318a",
            "item_id": "3915930e281c1947fa4a096567102749",
            "segment_index": 156.156,
            "face_detection_source": "gm_faces",
            "face_detection_confidence": 0.9845,
            "face_detection_blurriness": 0.2,
            "face_rectangle": {
                "top": 110,
                "left": 291,
                "width": 49,
                "height": 59
            },
            "used_for_training": false,
            "recognition_source": "gm_faces",
            "recognition_confidence": 0.63,
            "recognition_match": false,
            "source_img_path": "video_main_frames/frame-0000000039.jpg",
            "source_img_width": 640,
            "source_img_height": 360,
            "gender": "",
            "age": 0,
            "emotion": "",
            "hat": false,
            "glasses": false,
            "facial_hair": false,
            "created_at": "2018-09-06T06:12:18.110169Z",
            "updated_at": "2018-09-06T20:23:16.903281Z",
            "deleted": false
        }
    ]
}

Get items for person

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

Response:

{
    "person_id": "5353b9ed-d21e-44ce-83f2-b9ade2b4318a",
    "item_ids": [
        "3915930e281c1947fa4a096567102749",
        "7d23ac3f90cd6ddb7c85ddadfc48ef12"
    ]
}

Get deleted faces

GET /api/data/faces/deleted

Response:

{
    "page": 0,
    "count": 50,
    "total_deleted_faces": 1,
    "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
}

Items for face ID’s

POST /api/data/faces/items

{
    "face_ids": [
        "8871a22b-de86-4639-a4eb-324cd5e94316",
        "52b04f94-9b1d-4ea2-b53e-f0758a6b5ef8",
        "b90aa361-0cd6-49a7-b05c-1040be78e3af"
        ]
}

Response:

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

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.