Face API

This API allows users to create a new face, to be used by both user and the face recognition systems. They can also upload sample images for the faces, using the samples API.

{ "swagger": "2.0", "info": { "version": "2.4.0", "title": "Eagle Eye CameraManager API", "description": "RESTful API for the Eagle Eye CameraManager platform." }, "host": "rest.cameramanager.com", "schemes": [ "http", "https" ], "basePath": "/rest/v2.4", "produces": [ "application/json" ], "definitions": { "Error": { "type": "object", "description": "Generic error response, modelled after RFC 7807.", "properties": { "code": { "type": "integer", "description": "Error code within the system." }, "title": { "type": "string", "description": "This title is not meant to be shown to users and is not guaranteed to stay the same. Please use the code to parse the error." }, "detail": { "type": "string", "description": "Error details, to help developers detect what went wrong." } }, "required": [ "code", "title" ] }, "OAuth2Error": { "type": "object", "description": "Generic OAuth2 error response when there is something wrong with the OAuth2 authentication. Defined at RFC 6749.", "properties": { "error": { "type": "string", "description": "A single ASCII error code conforming the pattern." }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred." } }, "required": [ "error" ] }, "State": { "type": "string", "description": "State of the face, default is 'unknown'. A user can update an unknown\\suggested face to a known face while the face recognition system can update an unkown face to suggested. Types of states:\n * `known` - user has added a new face or accepted a suggestion by the face recognition system. A user can also update an 'unknown' face to 'known' by giving it a name.\n * `suggested` - face suggested by recognition system. The system can decide to suggest a face that it has seen before. It is different from an 'unknown' face as here the clients should specifically ask end-users to approve or reject suggested faces, so a good balance should be found between suggesting any newly recognized face to the end-user vs only suggesting a single face out of a thousand. One way to make the suggested faces less likely to overload the end-user would be to count the number of faces that is currently in that state and to only suggest a new face if this count is below a threshold.\n * `unknown` - unrecognized face for which the recognition system has enough details to recognize it again in the future. When a user decides to forget a face, it can update its state to 'unknown' - these are then automatically deleted when the last event containing this face is deleted, and therefore we do not have a an api call to delete a face.", "enum": [ "known", "suggested", "unknown" ] }, "Quality": { "type": "string", "description": "Quality of the sample image uploaded by the user. This is determined by the face recognition system, after trying to learn the face. Default is 'unprocessed'. Types of quality:\n * `unprocessed` - the sample has not been learned yet by any system. This is the starting state for faces that were added by the user.\n * `good` - the face has been learned by a system successfully. This is the starting state for faces that were added/suggested by such a system and not by the user.\n * `bad` - a system has tried learning the face, but decided the samples weren't good enough to correctly learn the face", "enum": [ "unprocessed", "good", "bad" ] }, "FaceCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the person, as given by the user.", "minLength": 1, "maxLength": 128 }, "state": { "$ref": "#/definitions/State" }, "customData": { "$ref": "#/definitions/CustomData" } }, "required": [ "name", "state" ] }, "FaceCreateWithSample": { "allOf": [ { "$ref": "#/definitions/FaceCreate" }, { "type": "object", "properties": { "sample": { "$ref": "#/definitions/FaceSampleCreate" } }, "required": [ "sample" ] } ] }, "FaceUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the person, as given by the user.", "minLength": 1, "maxLength": 128 }, "state": { "$ref": "#/definitions/State" }, "customData": { "$ref": "#/definitions/CustomData" } } }, "FaceWithSamples": { "allOf": [ { "$ref": "#/definitions/Face" }, { "type": "object", "properties": { "samples": { "type": "array", "items": { "$ref": "#/definitions/FaceSample" } } } } ], "required": [ "faceId" ] }, "Face": { "allOf": [ { "$ref": "#/definitions/FaceCreate" }, { "type": "object", "properties": { "faceId": { "type": "string", "format": "uuid", "description": "Unique identifier of face resource" }, "accountId": { "type": "integer", "format": "int32", "description": "Unique identifier of the account the face belongs to" }, "createTime": { "type": "string", "format": "date-time", "description": "Timestamp when the face was created" } } } ], "required": [ "faceId" ] }, "FaceSample": { "type": "object", "properties": { "sampleId": { "type": "string", "format": "uuid", "description": "Unique identifier of the sample image" }, "createTime": { "type": "string", "format": "date-time", "description": "Timestamp when the image was added" }, "quality": { "$ref": "#/definitions/Quality" }, "customData": { "$ref": "#/definitions/CustomData" } } }, "FaceSampleCreate": { "type": "object", "description": "The image to be saved as a sample for the face", "properties": { "imageData": { "type": "string", "description": "Base64 of image data." }, "imageContentType": { "type": "string", "description": "MimeType of the image data, for now we only support 'image/jpeg'" } }, "required": [ "imageData" ] }, "FaceSampleUpdate": { "type": "object", "properties": { "quality": { "$ref": "#/definitions/Quality" }, "customData": { "$ref": "#/definitions/CustomData" } }, "required": [ "quality" ] }, "CustomData": { "type": "object", "description": "The creator of the face/sample can add custom json data to the face/sample for their own use. This data will not be used by Eagle Eye Networks clients. To identify the system that added the data, the field is a key-value map, where the key is the namespace assigned to the application. This can have a maximum size of 1KB.", "additionalProperties": { "$ref": "#/definitions/NameSpace" } }, "NameSpace": { "type": "object", "description": "The namsepace used to identify the system that added the data. See also the namespace field of the events API. Custom data specific to the namespace can be added as a key-value map", "additionalProperties": { "type": "string" } } }, "responses": { "unauthorized": { "description": "You are not authenticated. Please authenticate and try again.", "schema": { "$ref": "#/definitions/OAuth2Error" } }, "forbidden": { "description": "You have no permission to access the specified resource.", "schema": { "$ref": "#/definitions/Error" } }, "validationError": { "description": "The supplied object is invalid. Error detail will contain the validation error.", "schema": { "$ref": "#/definitions/Error" } }, "notAcceptableError": { "description": "The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } }, "conflict": { "description": "There was a conflict while trying to perform your request. See error details for more information." }, "unsupportedMediaType": { "description": "The requested resource does not understand the media type sent in the request.", "schema": { "$ref": "#/definitions/Error" } } }, "parameters": { "faceId": { "name": "faceId", "in": "path", "description": "Unique identifier of face resource", "required": true, "type": "string", "format": "uuid" }, "sampleId": { "name": "sampleId", "in": "path", "description": "Unique identifier of the sample face image.", "required": true, "type": "string", "format": "uuid" } }, "paths": { "/faces": { "get": { "summary": "Get all faces", "description": "Returns the list of all the faces belonging to the account id", "operationId": "getFaces", "responses": { "200": { "description": "OK", "schema": { "title": "faces", "type": "array", "items": { "$ref": "#/definitions/FaceWithSamples" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Faces" ] }, "post": { "summary": "Create a face", "description": "Create a new face, to be used by both user and the face recognition systems. To create one, a sample image of the face has to be provided.", "operationId": "createFace", "parameters": [ { "name": "face", "in": "body", "required": true, "schema": { "$ref": "#/definitions/FaceCreateWithSample" } } ], "consumes": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/FaceWithSamples" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Faces" ] } }, "/faces/{faceId}": { "get": { "summary": "Get a face", "description": "Returns details of a single face", "operationId": "getFace", "parameters": [ { "$ref": "#/parameters/faceId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FaceWithSamples" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Faces" ] }, "patch": { "summary": "Update a face.", "description": "Update a face", "operationId": "updateFace", "parameters": [ { "$ref": "#/parameters/faceId" }, { "name": "faceUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/FaceUpdate" } } ], "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "415": { "$ref": "#/responses/unsupportedMediaType" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Faces" ] } }, "/faces/{faceId}/samples": { "get": { "summary": "Get all face samples", "description": "Returns details of all the samples of a single face", "operationId": "getFaceSamples", "parameters": [ { "$ref": "#/parameters/faceId" } ], "responses": { "200": { "description": "OK", "schema": { "title": "samples", "type": "array", "items": { "$ref": "#/definitions/FaceSample" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSamples" ] }, "post": { "summary": "Upload a face sample", "description": "Upload a new sample image for the face", "operationId": "createFaceSample", "parameters": [ { "$ref": "#/parameters/faceId" }, { "name": "sampleImage", "in": "body", "required": true, "schema": { "$ref": "#/definitions/FaceSampleCreate" } } ], "consumes": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/FaceSample" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSamples" ] } }, "/faces/{faceId}/samples/{sampleId}": { "get": { "summary": "Get a face sample", "description": "Returns details of a single sample face image", "operationId": "getFaceSample", "parameters": [ { "$ref": "#/parameters/faceId" }, { "$ref": "#/parameters/sampleId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FaceSample" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSamples" ] }, "patch": { "summary": "Update a face sample", "description": "Update the details of a sample face image", "operationId": "updateFaceSample", "parameters": [ { "$ref": "#/parameters/faceId" }, { "$ref": "#/parameters/sampleId" }, { "name": "faceUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/FaceSampleUpdate" } } ], "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "415": { "$ref": "#/responses/unsupportedMediaType" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSamples" ] }, "delete": { "summary": "Deletes a face sample", "description": "A user can delete a sample image from the set of samples, for eg. if the Face recognition system has identified it to be of bad quality. Note that at least one sample image has to be available for a face, and hence all the sample images cannot be deleted.", "operationId": "deleteFaceSample", "parameters": [ { "$ref": "#/parameters/faceId" }, { "$ref": "#/parameters/sampleId" } ], "responses": { "204": { "description": "OK" }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSamples" ] } }, "/faces/{faceId}/samples/{sampleId}.jpg": { "get": { "summary": "Get a face sample image", "description": "Retrieve the sample image of the face as jpeg", "operationId": "getFaceSampleImage", "produces": [ "image/jpeg", "application/json" ], "parameters": [ { "$ref": "#/parameters/faceId" }, { "$ref": "#/parameters/sampleId" } ], "responses": { "200": { "description": "A jpeg file", "schema": { "type": "file" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "FaceSampleImages" ] } } } }

swagger-face.yaml