Contents x
      Faces API in Wasabi AiR
      • 20 May 2024
      • 2 Minutes to read
      • Print
      • PDF
      Contents

      Faces API in Wasabi AiR

      • Updated on 20 May 2024
      • 2 Minutes to read
      • Print
      • PDF
      Article summary

      Wasabi AiR detects faces within video frames and images, then assigns each one a unique ID. When it is confident, Wasabi AiR groups matching faces together. Groups of faces can be named to create a known person.

      Existing data sets can be uploaded to train the platform to identify known people (for example, 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. This belongs to a person.
      • Person - A group of faces, whether they are known or unknown.

      Deleting a Face

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

      Response

      Empty Response. 

      Status Code: 204.

      Getting a Face

      A Non-Deleted Face

      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, a Status Code 404.

      Response

      {
   "error": {
       "message": STRING,
      "request_id": STRING
   }
}

      A Deleted Face

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

      Response

      Empty Response Status Code: 204

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

      Getting Faces

      Non-Deleted Faces

      GET /api/data/v3/faces?limit=10
      If not provided, the default size for limit is 5000 responses.
      {
    "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
        }
    ]
}

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

      Deleting Faces in an Item

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

      Response

      {
    "ok": true
}

      Response

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

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

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

      Deleting a Face

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

      Response

      NONE

      Status Code: 204

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


      What's Next
      Copyright © 2024 by Wasabi Technologies LLC
      75 Arlington Street, Suite 810, Boston, MA 02116 USA
      All Rights Reserved
      Visit us at https://wasabi.com.
      WASABI and the WASABI logo are trademarks of Wasabi Technologies LLC and may not be used without permission of Wasabi Technologies. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies.

      Information presented herein is subject to change without notice. Companies, names, and data used in examples are fictitious unless otherwise noted. No part of this information may be reproduced or transmitted in any form by means electronic or mechanical, for any purpose, without express written permission of Wasabi Technologies.