{ "swagger": "2.0", "info": { "version": "1.0", "title": "Face API", "description": "An API for face detection, verification, and identification." }, "securityDefinitions": { "apim_key": { "type": "apiKey", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "security": [ { "apim_key": [] } ], "x-ms-parameterized-host": { "hostTemplate": "{AzureRegion}.api.cognitive.microsoft.com", "parameters": [ { "$ref": "../../../Common/ExtendedRegions.json#/parameters/AzureRegion" } ] }, "basePath": "/face/v1.0", "schemes": [ "https" ], "paths": { "/findsimilars": { "post": { "description": "Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.", "operationId": "Face_FindSimilar", "parameters": [ { "name": "body", "in": "body", "description": "Request body for Find Similar.", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/FindSimilarRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an array of the most similar faces represented in faceId if the input parameter is faceIds or persistedFaceId if the input parameter is faceListId.", "schema": { "$ref": "#/definitions/SimilarFaceResults" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Find similar results example": { "$ref": "./examples/FindSimilar.json" } } } }, "/group": { "post": { "description": "Divide candidate faces into groups based on face similarity.", "operationId": "Face_Group", "parameters": [ { "name": "body", "description": "Request body for grouping.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/GroupRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.", "schema": { "$ref": "#/definitions/GroupResponse" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Group example": { "$ref": "./examples/Group.json" } } } }, "/identify": { "post": { "description": "Identify unknown faces from a person group.", "operationId": "Face_Identify", "parameters": [ { "name": "body", "description": "Request body for identify operation.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/IdentifyRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the identified candidate person(s) for each query face.", "schema": { "$ref": "#/definitions/IdentifyResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Identiy example": { "$ref": "./examples/Identify.json" } } } }, "/verify": { "post": { "description": "Verify whether two faces belong to a same person or whether one face belongs to a person.", "operationId": "Face_Verify", "parameters": [ { "name": "body", "description": "Request body for verify operation.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/VerifyRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the verification result.", "schema": { "$ref": "#/definitions/VerifyResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Verify faces example": { "$ref": "./examples/VerifyFaces.json" } } } }, "/persongroups/{personGroupId}/persons": { "post": { "description": "Create a new person in a specified person group.", "operationId": "Person_Create", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the target person group to create the person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "body", "description": "Request body for creating new person.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreatePersonRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns a new personId created.", "schema": { "$ref": "#/definitions/CreatePersonResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Create new person example": { "$ref": "./examples//CreateNewPerson.json" } } }, "get": { "description": "List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).", "operationId": "Person_List", "x-ms-examples": { "List persons in person group": { "$ref": "./examples/ListPersonGroupPersons.json" } }, "parameters": [ { "name": "personGroupId", "in": "path", "description": "personGroupId of the target person group.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "start", "description": "Starting person id to return (used to list a range of persons).", "in": "query", "required": false, "type": "string" }, { "name": "top", "description": "Number of persons to return starting with the person id indicated by the 'start' parameter.", "in": "query", "required": false, "type": "integer", "minimum": 1, "maximum": 1000 } ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an array of person information that belong to the person group.", "schema": { "$ref": "#/definitions/PersonResults" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } } } }, "/persongroups/{personGroupId}/persons/{personId}": { "delete": { "description": "Delete an existing person from a person group. Persisted face images of the person will also be deleted.", "operationId": "Person_Delete", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "The target personId to delete.", "required": true, "type": "string", "format": "uuid" } ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Delete an existing person example": { "$ref": "./examples/DeletePerson.json" } } }, "get": { "description": "Retrieve a person's information, including registered persisted faces, name and userData.", "operationId": "Person_Get", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "Specifying the target person.", "required": true, "type": "string", "format": "uuid" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the person's information.", "schema": { "$ref": "#/definitions/PersonResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Get person example": { "$ref": "./examples/GetPerson.json" } } }, "patch": { "description": "Update name or userData of a person.", "operationId": "Person_Update", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "personId of the target person.", "required": true, "type": "string", "format": "uuid" }, { "name": "body", "description": "Request body for person update operation.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreatePersonRequest" } } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Update person example": { "$ref": "./examples/UpdatePerson.json" } } } }, "/persongroups/{personGroupId}/persons/{personId}/persistedFaces/{persistedFaceId}": { "delete": { "description": "Delete a face from a person. Relative image for the persisted face will also be deleted.", "operationId": "Person_DeleteFace", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "Specifying the person that the target persisted face belong to.", "required": true, "type": "string", "format": "uuid" }, { "name": "persistedFaceId", "in": "path", "description": "The persisted face to remove.", "required": true, "type": "string", "format": "uuid" } ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Delete face from person example": { "$ref": "./examples/DeletePersonFace.json" } } }, "get": { "description": "Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).", "operationId": "Person_GetFace", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "Specifying the target person that the face belongs to.", "required": true, "type": "string", "format": "uuid" }, { "name": "persistedFaceId", "in": "path", "description": "The persistedFaceId of the target persisted face of the person.", "required": true, "type": "string", "format": "uuid" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns target persisted face's information (persistedFaceId and userData).", "schema": { "$ref": "#/definitions/PersonFaceResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Get persisted face example": { "$ref": "./examples/GetPersistedFace.json" } } }, "patch": { "description": "Update a person persisted face's userData field.", "operationId": "Person_UpdateFace", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "personId of the target person.", "required": true, "type": "string", "format": "uuid" }, { "name": "persistedFaceId", "in": "path", "description": "persistedFaceId of target face, which is persisted and will not expire.", "required": true, "type": "string", "format": "uuid" }, { "name": "body", "description": "Request body for updating persisted face.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/UpdatePersonFaceDataRequest" } } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Update person face example": { "$ref": "./examples/UpdatePersonFace.json" } } } }, "/persongroups/{personGroupId}": { "put": { "description": "Create a new person group with specified personGroupId, name and user-provided userData.", "operationId": "PersonGroup_Create", "parameters": [ { "name": "personGroupId", "in": "path", "description": "User-provided personGroupId as a string.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "body", "description": "Request body for creating new person group.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreatePersonGroupRequest" } } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Create new person group example": { "$ref": "./examples/CreateNewPersonGroup.json" } } }, "delete": { "description": "Delete an existing person group. Persisted face images of all people in the person group will also be deleted.", "operationId": "PersonGroup_Delete", "parameters": [ { "name": "personGroupId", "in": "path", "description": "The personGroupId of the person group to be deleted.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Delete a person group example": { "$ref": "./examples/DeletePersonGroup.json" } } }, "get": { "description": "Retrieve the information of a person group, including its name and userData.", "operationId": "PersonGroup_Get", "parameters": [ { "name": "personGroupId", "in": "path", "description": "personGroupId of the target person group.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "responses": { "200": { "description": "A successful call returns the person group's information.", "schema": { "$ref": "#/definitions/PersonGroupResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Get person group example": { "$ref": "./examples/GetPersonGroup.json" } } }, "patch": { "description": "Update an existing person group's display name and userData. The properties which does not appear in request body will not be updated.", "operationId": "PersonGroup_Update", "parameters": [ { "name": "personGroupId", "in": "path", "description": "personGroupId of the person group to be updated.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "body", "description": "Request body for updating person group.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreatePersonGroupRequest" } } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Update person group example": { "$ref": "./examples/UpdatePersonGroup.json" } } } }, "/persongroups/{personGroupId}/training": { "get": { "description": "Retrieve the training status of a person group (completed or ongoing).", "operationId": "PersonGroup_GetTrainingStatus", "parameters": [ { "name": "personGroupId", "in": "path", "description": "personGroupId of target person group.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "responses": { "200": { "description": "A successful call returns the person group's training status.", "schema": { "$ref": "#/definitions/TrainingStatus" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Get training status example": { "$ref": "./examples/GetTrainingStatus.json" } } } }, "/persongroups": { "get": { "description": "List person groups and their information.", "operationId": "PersonGroup_List", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "List person groups from the least personGroupId greater than the \"start\".", "type": "string", "maxLength": 64 }, { "name": "top", "in": "query", "required": false, "description": "The number of person groups to list.", "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an array of person groups and their information.", "schema": { "$ref": "#/definitions/PersonGroupResults" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Get person groups example": { "$ref": "./examples/GetPersonGroups.json" } } } }, "/persongroups/{personGroupId}/train": { "post": { "description": "Queue a person group training task, the training task may not be started immediately.", "operationId": "PersonGroup_Train", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Target person group to be trained.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "produces": [ "application/json" ], "responses": { "202": { "description": "The training task was queued successfully." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Queue person group training": { "$ref": "./examples/QueueTraining.json" } } } }, "/facelists/{faceListId}": { "put": { "description": "Create an empty face list. Up to 64 face lists are allowed to exist in one subscription.", "operationId": "FaceList_Create", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a particular face list.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "body", "description": "Request body for creating a face list.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreateFaceListRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Create new face list example": { "$ref": "./examples/CreateNewFaceList.json" } } }, "get": { "description": "Retrieve a face list's information.", "operationId": "FaceList_Get", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a Face List.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the face list's information.", "schema": { "$ref": "#/definitions/GetFaceListResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Get Face list example": { "$ref": "./examples/GetFaceList.json" } } }, "patch": { "description": "Update information of a face list.", "operationId": "FaceList_Update", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a Face List.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "body", "description": "Request body for updating a face list.", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/CreateFaceListRequest" } } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Update face list example": { "$ref": "./examples/UpdateFaceList.json" } } }, "delete": { "description": "Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.", "operationId": "FaceList_Delete", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a Face List.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Delete face list example": { "$ref": "./examples/DeleteFaceList.json" } } } }, "/facelists": { "get": { "description": "Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.", "operationId": "FaceList_List", "parameters": [], "responses": { "200": { "description": "A successful call returns an array of faceList.", "schema": { "$ref": "#/definitions/FaceListResults" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Get Face lists example": { "$ref": "./examples/GetFaceLists.json" } } } }, "/facelists/{faceListId}/persistedFaces/{persistedFaceId}": { "delete": { "description": "Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted image related to the face will also be deleted.", "operationId": "FaceList_DeleteFace", "parameters": [ { "name": "faceListId", "in": "path", "description": "faceListId of an existing face list.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "persistedFaceId", "in": "path", "description": "persistedFaceId of an existing face.", "required": true, "type": "string", "format": "uuid" } ], "responses": { "200": { "description": "A successful call returns an empty response body." }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Delete face in face list example": { "$ref": "./examples/DeleteFaceListFace.json" } } } }, "/persongroups/{personGroupId}/persons/{personId}/persistedFaces": { "post": { "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.", "operationId": "Person_AddPersonFace", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "Target person that the face is added to.", "required": true, "type": "string", "format": "uuid" }, { "name": "userData", "in": "query", "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB.", "type": "string", "maxLength": 1024 }, { "$ref": "#/parameters/targetFace" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageUrl" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the new persistedFaceId.", "schema": { "$ref": "#/definitions/PersistedFaceResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Add Person face example": { "$ref": "./examples/CreateNewPersonFace.json" } } } }, "/detect": { "post": { "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", "operationId": "Face_Detect", "parameters": [ { "name": "returnFaceId", "in": "query", "description": "A value indicating whether the operation should return faceIds of detected faces.", "type": "boolean", "default": true }, { "name": "returnFaceLandmarks", "in": "query", "description": "A value indicating whether the operation should return landmarks of the detected faces.", "type": "boolean", "default": false }, { "$ref": "#/parameters/returnFaceAttributes" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageUrl" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an array of face entries ranked by face rectangle size in descendingorder. An empty response indicates no faces detected.", "schema": { "$ref": "#/definitions/DetectionResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Detect example": { "$ref": "./examples/Detect.json" } } } }, "/facelists/{faceListId}/persistedFaces": { "post": { "description": "Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire.", "operationId": "FaceList_AddFace", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a Face List.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "userData", "in": "query", "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", "type": "string", "maxLength": 1024 }, { "$ref": "#/parameters/targetFace" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageUrl" } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "responses": { "200": { "description": "A successful call returns a new persistedFaceId.", "schema": { "$ref": "#/definitions/PersistedFaceResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Create face list face example": { "$ref": "./examples/CreateNewFaceListFace.json" } } } } }, "x-ms-paths": { "/verify?overload=persongroup": { "post": { "description": "Verify whether two faces belong to a same person. Compares a face Id with a Person Id", "operationId": "Face_VerifyWithPersonGroup", "parameters": [ { "name": "body", "description": "Request body for verifying two faces in a person group", "in": "body", "required": true, "x-ms-client-flatten": true, "schema": { "$ref": "#/definitions/VerifyPersonGroupRequest" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns the verification result.", "schema": { "$ref": "#/definitions/VerifyResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Verify with person group example": { "$ref": "./examples/VerifyPersonGroup.json" } } } }, "/detect?overload=stream": { "post": { "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", "operationId": "Face_DetectInStream", "parameters": [ { "name": "returnFaceId", "in": "query", "description": "A value indicating whether the operation should return faceIds of detected faces.", "type": "boolean", "default": true }, { "name": "returnFaceLandmarks", "in": "query", "description": "A value indicating whether the operation should return landmarks of the detected faces.", "type": "boolean", "default": false }, { "$ref": "#/parameters/returnFaceAttributes" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageStream" } ], "consumes": [ "application/octet-stream" ], "produces": [ "application/json" ], "responses": { "200": { "description": "A successful call returns an array of face entries ranked by face rectangle size in descendingorder. An empty response indicates no faces detected.", "schema": { "$ref": "#/definitions/DetectionResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Detect with stream example": { "$ref": "./examples/DetectWithStream.json" } } } }, "/persongroups/{personGroupId}/persons/{personId}/persistedFaces?overload=stream": { "post": { "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.", "operationId": "Person_AddPersonFaceFromStream", "parameters": [ { "name": "personGroupId", "in": "path", "description": "Specifying the person group containing the target person.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "personId", "in": "path", "description": "Target person that the face is added to.", "required": true, "type": "string", "format": "uuid" }, { "name": "userData", "in": "query", "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB.", "type": "string", "maxLength": 1024 }, { "$ref": "#/parameters/targetFace" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageStream" } ], "produces": [ "application/json" ], "consumes": [ "application/octet-stream" ], "responses": { "200": { "description": "A successful call returns the new persistedFaceId.", "schema": { "$ref": "#/definitions/PersistedFaceResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "x-ms-examples": { "Add face to person with stream example": { "$ref": "./examples/CreateNewPersonFaceFromStream.json" } } } }, "/facelists/{faceListId}/persistedFaces?overload=stream": { "post": { "description": "Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire.", "operationId": "FaceList_AddFaceFromStream", "parameters": [ { "name": "faceListId", "in": "path", "description": "Id referencing a Face List.", "required": true, "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, { "name": "userData", "in": "query", "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", "type": "string", "maxLength": 1024 }, { "$ref": "#/parameters/targetFace" }, { "$ref": "../../../Common/Parameters.json#/parameters/ImageStream" } ], "consumes": [ "application/octet-stream" ], "responses": { "200": { "description": "A successful call returns a new persistedFaceId.", "schema": { "$ref": "#/definitions/PersistedFaceResult" } }, "default": { "description": "Error response.", "schema": { "$ref": "#/definitions/APIError" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Add face to face list from stream example": { "$ref": "./examples/CreateNewFaceListFaceFromStream.json" } } } } }, "definitions": { "APIError": { "type": "object", "description": "Error information returned by the API", "properties": { "error": { "$ref": "#/definitions/Error" } } }, "Error": { "type": "object", "description": "Error body.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "DetectionResult": { "type": "array", "items": { "$ref": "#/definitions/DetectedFace" } }, "PersistedFaceResult": { "type": "object", "required": [ "persistedFaceId" ], "description": "Persisted face result.", "properties": { "persistedFaceId": { "type": "string", "format": "uuid", "description": "persistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response" } } }, "DetectedFace": { "type": "object", "required": [ "faceRectangle" ], "description": "Detected Face object.", "properties": { "faceId": { "type": "string", "format": "uuid" }, "faceRectangle": { "$ref": "#/definitions/FaceRectangle" }, "faceLandmarks": { "$ref": "#/definitions/FaceLandmarks" }, "faceAttributes": { "$ref": "#/definitions/FaceAttributes" } } }, "FaceRectangle": { "type": "object", "required": [ "width", "height", "left", "top" ], "description": "A rectangle within which a face can be found", "properties": { "width": { "type": "integer", "format": "int32", "description": "The width of the rectangle, in pixels." }, "height": { "type": "integer", "format": "int32", "description": "The height of the rectangle, in pixels." }, "left": { "type": "integer", "format": "int32", "description": "The distance from the left edge if the image to the left edge of the rectangle, in pixels." }, "top": { "type": "integer", "format": "int32", "description": "The distance from the top edge if the image to the top edge of the rectangle, in pixels." } } }, "Position": { "type": "object", "required": [ "x", "y" ], "description": "Coordinates within an image", "properties": { "x": { "type": "number", "description": "The horizontal component, in pixels." }, "y": { "type": "number", "description": "The vertical component, in pixels." } } }, "FaceLandmarks": { "type": "object", "description": "A collection of 27-point face landmarks pointing to the important positions of face components.", "properties": { "pupilLeft": { "$ref": "#/definitions/Position" }, "pupilRight": { "$ref": "#/definitions/Position" }, "noseTip": { "$ref": "#/definitions/Position" }, "mouthLeft": { "$ref": "#/definitions/Position" }, "mouthRight": { "$ref": "#/definitions/Position" }, "eyebrowLeftOuter": { "$ref": "#/definitions/Position" }, "eyebrowLeftInner": { "$ref": "#/definitions/Position" }, "eyeLeftOuter": { "$ref": "#/definitions/Position" }, "eyeLeftTop": { "$ref": "#/definitions/Position" }, "eyeLeftBottom": { "$ref": "#/definitions/Position" }, "eyeLeftInner": { "$ref": "#/definitions/Position" }, "eyebrowRightInner": { "$ref": "#/definitions/Position" }, "eyebrowRightOuter": { "$ref": "#/definitions/Position" }, "eyeRightInner": { "$ref": "#/definitions/Position" }, "eyeRightTop": { "$ref": "#/definitions/Position" }, "eyeRightBottom": { "$ref": "#/definitions/Position" }, "eyeRightOuter": { "$ref": "#/definitions/Position" }, "noseRootLeft": { "$ref": "#/definitions/Position" }, "noseRootRight": { "$ref": "#/definitions/Position" }, "noseLeftAlarTop": { "$ref": "#/definitions/Position" }, "noseRightAlarTop": { "$ref": "#/definitions/Position" }, "noseLeftAlarOutTip": { "$ref": "#/definitions/Position" }, "noseRightAlarOutTip": { "$ref": "#/definitions/Position" }, "upperLipTop": { "$ref": "#/definitions/Position" }, "upperLipBottom": { "$ref": "#/definitions/Position" }, "underLipTop": { "$ref": "#/definitions/Position" }, "underLipBottom": { "$ref": "#/definitions/Position" } } }, "FaceAttributes": { "type": "object", "description": "Face Attributes", "properties": { "age": { "type": "number", "description": "Age in years" }, "gender": { "type": "string", "description": "Possible gender of the face.", "x-ms-enum": { "name": "Gender", "modelAsString": false }, "enum": [ "male", "female", "genderless" ] }, "smile": { "type": "number", "format": "float", "description": "Smile intensity, a number between [0,1] ", "minimum": 0, "maximum": 1 }, "facialHair": { "$ref": "#/definitions/FacialHairProperties" }, "glasses": { "type": "string", "description": "Glasses type if any of the face.", "x-ms-enum": { "name": "GlassesTypes", "modelAsString": false }, "enum": [ "noGlasses", "readingGlasses", "sunglasses", "swimmingGoggles" ] }, "headPose": { "$ref": "#/definitions/HeadPoseProperties" }, "emotion": { "$ref": "#/definitions/EmotionProperties" }, "hair": { "$ref": "#/definitions/HairProperties" }, "makeup": { "$ref": "#/definitions/MakeupProperties" }, "occlusion": { "$ref": "#/definitions/OcclusionProperties" }, "accessories": { "$ref": "#/definitions/AccessoryProperties" }, "blur": { "$ref": "#/definitions/BlurProperties" }, "exposure": { "$ref": "#/definitions/ExposureProperties" }, "noise": { "$ref": "#/definitions/NoiseProperties" } } }, "FacialHairProperties": { "type": "object", "description": "Properties describing facial hair attributes.", "properties": { "moustache": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "beard": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "sideburns": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 } } }, "HeadPoseProperties": { "type": "object", "description": "Properties indicating head pose of the face.", "properties": { "roll": { "type": "number", "x-nullable": false }, "yaw": { "type": "number", "x-nullable": false }, "pitch": { "type": "number", "x-nullable": false } } }, "EmotionProperties": { "type": "object", "description": "Properties describing facial emotion in form of confidence ranging from 0 to 1.", "properties": { "anger": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "contempt": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "disgust": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "fear": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "happiness": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "neutral": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "sadness": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 }, "surprise": { "type": "number", "x-nullable": false, "minimum": 0, "maximum": 1 } } }, "HairProperties": { "type": "object", "description": "Properties describing hair attributes.", "properties": { "bald": { "type": "number", "description": "A number describing confidence level of whether the person is bald.", "x-nullable": false, "minimum": 0, "maximum": 1 }, "invisible": { "type": "boolean", "description": "A boolean value describing whether the hair is visible in the image.", "x-nullable": false }, "hairColor": { "$ref": "#/definitions/HairColors" } } }, "HairColors": { "type": "array", "description": "An array of candidate colors and confidence level in the presence of each.", "items": { "$ref": "#/definitions/ColorProperty" } }, "ColorProperty": { "type": "object", "description": "Hair color and associated confidence", "properties": { "color": { "type": "string", "description": "Name of the color." }, "confidence": { "x-nullable": false, "$ref": "#/definitions/ConfidenceProperty" } } }, "MakeupProperties": { "type": "object", "description": "Properties describing present makeups on a given face.", "properties": { "eyeMakeup": { "type": "boolean", "description": "A boolean value describing whether eye makeup is present on a face.", "x-nullable": false }, "lipMakeup": { "type": "boolean", "description": "A boolean value describing whether lip makeup is present on a face.", "x-nullable": false } } }, "OcclusionProperties": { "type": "object", "description": "Properties describing occulusions on a given face.", "properties": { "foreheadOccluded": { "type": "boolean", "description": "A boolean value indicating whether forehead is occluded.", "x-nullable": false }, "eyeOccluded": { "type": "boolean", "description": "A boolean value indicating whether eyes are occluded.", "x-nullable": false }, "mouthOccluded": { "type": "boolean", "description": "A boolean value indicating whether the mouth is occluded.", "x-nullable": false } } }, "AccessoryProperties": { "type": "array", "description": "Properties describing any accessories on a given face.", "items": { "$ref": "#/definitions/AccessoryItem" } }, "AccessoryItem": { "type": "object", "description": "Accessory item and corresponding confidence level.", "properties": { "type": { "type": "string", "description": "Description of an accessory", "x-nullable": false }, "confidence": { "x-nullable": false, "$ref": "#/definitions/ConfidenceProperty" } } }, "BlurProperties": { "type": "object", "description": "Properties describing any presence of blur within the image.", "properties": { "blurLevel": { "type": "string", "description": "An enum value indicating level of blurriness.", "x-nullable": false, "x-ms-enum": { "name": "BlurLevels", "modelAsString": false }, "enum": [ "Low", "Medium", "High" ] }, "value": { "type": "number", "description": "A number indicating level of blurriness ranging from 0 to 1.", "x-nullable": false, "minimum": 0, "maximum": 1 } } }, "ExposureProperties": { "type": "object", "description": "Properties describing exposure level of the image.", "properties": { "exposureLevel": { "type": "string", "description": "An enum value indicating level of exposure.", "x-nullable": false, "x-ms-enum": { "name": "ExposureLevels", "modelAsString": false }, "enum": [ "UnderExposure", "GoodExposure", "OverExposure" ] }, "value": { "type": "number", "description": "A number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure.", "x-nullable": false, "minimum": 0, "maximum": 1 } } }, "NoiseProperties": { "type": "object", "description": "Properties describing noise level of the image.", "properties": { "noiseLevel": { "type": "string", "description": "An enum value indicating level of noise.", "x-nullable": false, "x-ms-enum": { "name": "NoiseLevels", "modelAsString": false }, "enum": [ "Low", "Medium", "High" ] }, "value": { "type": "number", "description": "A number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level.", "x-nullable": false, "minimum": 0, "maximum": 1 } } }, "FindSimilarRequest": { "type": "object", "required": [ "faceId" ], "description": "Request body for find similar operation.", "properties": { "faceId": { "type": "string", "format": "uuid", "description": "FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call" }, "faceListId": { "type": "string", "description": "An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId and faceIds should not be provided at the same time", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, "faceIds": { "type": "array", "description": "An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call.", "maxItems": 1000, "items": { "type": "string", "format": "uuid" } }, "maxNumOfCandidatesReturned": { "type": "integer", "description": "The number of top similar faces returned. The valid range is [1, 1000].", "default": 20, "minimum": 1, "maximum": 1000 }, "mode": { "type": "string", "description": "Similar face searching mode. It can be \"matchPerson\" or \"matchFace\".", "default": "matchPerson", "x-nullable": false, "x-ms-enum": { "name": "FaceMatchingMode", "modelAsString": false }, "enum": [ "matchPerson", "matchFace" ] } } }, "SimilarFaceResults": { "type": "array", "items": { "$ref": "#/definitions/SimilarFaceResult" } }, "SimilarFaceResult": { "type": "object", "description": "Response body for find similar face operation.", "properties": { "faceId": { "type": "string", "format": "uuid", "description": "faceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call" }, "persistedFaceId": { "type": "string", "format": "uuid", "description": "persistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response" }, "confidence": { "x-nullable": false, "$ref": "#/definitions/ConfidenceProperty" } } }, "GroupRequest": { "type": "object", "required": [ "faceIds" ], "description": "Request body for group request.", "properties": { "faceIds": { "type": "array", "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", "maxItems": 1000, "items": { "type": "string", "format": "uuid" } } } }, "GroupResponse": { "type": "object", "required": [ "groups" ], "description": "An array of face groups based on face similarity.", "properties": { "groups": { "type": "array", "description": "A partition of the original faces based on face similarity. Groups are ranked by number of faces", "items": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "messyGroup": { "type": "array", "description": "Face ids array of faces that cannot find any similar faces from original faces.", "items": { "type": "string", "format": "uuid" } } } }, "IdentifyRequest": { "type": "object", "required": [ "personGroupId", "faceIds" ], "description": "Request body for identify face operation.", "properties": { "personGroupId": { "description": "personGroupId of the target person group, created by PersonGroups.Create", "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, "faceIds": { "type": "array", "description": "Array of candidate faceId created by Face - Detect.", "maxItems": 1000, "items": { "type": "string", "format": "uuid" } }, "maxNumOfCandidatesReturned": { "type": "integer", "description": "The number of top similar faces returned.", "default": 1, "minimum": 1, "maximum": 1000 }, "confidenceThreshold": { "$ref": "#/definitions/ConfidenceProperty" } } }, "IdentifyResult": { "type": "array", "items": { "$ref": "#/definitions/IdentifyResultItem" } }, "IdentifyResultItem": { "type": "object", "required": [ "faceId", "candidates" ], "description": "Response body for identify face operation.", "properties": { "faceId": { "type": "string", "format": "uuid", "description": "faceId of the query face" }, "candidates": { "type": "array", "items": { "$ref": "#/definitions/IdentifyResultCandidate" } } } }, "IdentifyResultCandidate": { "type": "object", "required": [ "personId", "confidence" ], "description": "All possible faces that may qualify.", "properties": { "personId": { "type": "string", "format": "uuid", "description": "Id of candidate" }, "confidence": { "x-nullable": false, "$ref": "#/definitions/ConfidenceProperty" } } }, "VerifyPersonGroupRequest": { "type": "object", "required": [ "faceId", "personId", "personGroupId" ], "description": "Request body for verify operation.", "properties": { "faceId": { "type": "string", "format": "uuid", "description": "faceId the face, comes from Face - Detect" }, "personId": { "type": "string", "format": "uuid", "description": "Specify a certain person in a person group. personId is created in Persons.Create." }, "personGroupId": { "description": "Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create.", "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" } } }, "VerifyRequest": { "type": "object", "required": [ "faceId1", "faceId2" ], "description": "Request body for verify operation.", "properties": { "faceId1": { "type": "string", "format": "uuid", "description": "faceId of the first face, comes from Face - Detect" }, "faceId2": { "type": "string", "format": "uuid", "description": "faceId of the second face, comes from Face - Detect" } } }, "VerifyResult": { "type": "object", "required": [ "isIdentical" ], "description": "Result of the verify operation.", "properties": { "isIdentical": { "type": "boolean", "description": "True if the two faces belong to the same person or the face belongs to the person, otherwise false." }, "confidence": { "x-nullable": false, "$ref": "#/definitions/ConfidenceProperty" } } }, "CreateFaceListRequest": { "type": "object", "description": "Request to create a face list.", "properties": { "name": { "type": "string", "description": "Name of the face list, maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "Optional user defined data for the face list. Length should not exceed 16KB.", "maxLength": 16384 } } }, "GetFaceListResult": { "type": "object", "required": [ "faceListId" ], "description": "Result of the GetFaceList operation.", "properties": { "faceListId": { "type": "string", "description": "faceListId of the target face list.", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, "name": { "type": "string", "description": "Face list's display name, maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "User-provided data attached to this face list. Length should not exceed 16KB.", "maxLength": 16384 }, "persistedFaces": { "type": "array", "description": "Persisted faces within the face list.", "items": { "$ref": "#/definitions/PersonFaceResult" } } } }, "FaceListResults": { "type": "array", "description": "An array of face list results.", "items": { "$ref": "#/definitions/GetFaceListResult" } }, "CreatePersonGroupRequest": { "type": "object", "description": "Request to create a person group.", "properties": { "name": { "type": "string", "description": "Person group display name. The maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "User-provided data attached to the person group. The size limit is 16KB.", "maxLength": 16384 } } }, "PersonGroupResult": { "type": "object", "required": [ "personGroupId" ], "description": "Person group object.", "properties": { "personGroupId": { "description": "personGroupId of the existing person groups.", "type": "string", "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, "name": { "type": "string", "description": "Person group's display name, maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "User-provided data attached to this person group. Length should not exceed 16KB.", "maxLength": 16384 } } }, "PersonGroupResults": { "type": "array", "description": "An array of person groups.", "items": { "$ref": "#/definitions/PersonGroupResult" } }, "CreatePersonRequest": { "type": "object", "description": "Request to create a person object.", "properties": { "name": { "type": "string", "description": "Display name of the target person. The maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "Optional fields for user-provided data attached to a person. Size limit is 16KB.", "maxLength": 16384 } } }, "CreatePersonResult": { "type": "object", "required": [ "personId" ], "description": "Result of creating person.", "properties": { "personId": { "type": "string", "format": "uuid", "description": "personID of the new created person." } } }, "PersonResult": { "type": "object", "required": [ "personId" ], "description": "Person object.", "properties": { "personId": { "type": "string", "format": "uuid", "description": "personId of the target face list." }, "persistedFaceIds": { "type": "array", "description": "persistedFaceIds of registered faces in the person. These persistedFaceIds are returned from Person - Add a Person Face, and will not expire.", "items": { "type": "string", "format": "uuid" } }, "name": { "type": "string", "description": "Person's display name, maximum length is 128.", "maxLength": 128 }, "userData": { "type": "string", "description": "User-provided data attached to this person. Length should not exceed 16KB.", "maxLength": 16384 } } }, "PersonResults": { "type": "array", "description": "An array of PersonResults.", "items": { "$ref": "#/definitions/PersonResult" } }, "PersonFaceResult": { "type": "object", "required": [ "persistedFaceId" ], "description": "PersonFace object.", "properties": { "persistedFaceId": { "type": "string", "format": "uuid", "description": "The persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in 24 hours after the detection call." }, "userData": { "type": "string", "description": "User-provided data attached to the face. The size limit is 1KB.", "maxLength": 1024 } } }, "UpdatePersonFaceDataRequest": { "type": "object", "description": "Request to update person face data.", "properties": { "userData": { "type": "string", "description": "User-provided data attached to the face. The size limit is 1KB.", "maxLength": 1024 } } }, "TrainingStatus": { "type": "object", "required": [ "status" ], "description": "Training status object.", "properties": { "status": { "type": "string", "description": "Training status: notstarted, running, succeeded, failed. If the training process is waiting to perform, the status is notstarted. If the training is ongoing, the status is running. Status succeed means this person group is ready for Face - Identify. Status failed is often caused by no person or no persisted face exist in the person group", "x-nullable": false, "x-ms-enum": { "name": "TrainingStatusType", "modelAsString": false }, "enum": [ "nonstarted", "running", "succeeded", "failed" ] }, "createdDateTime": { "type": "string", "format": "date-time", "description": "A combined UTC date and time string that describes person group created time.", "x-ms-client-name": "created" }, "lastActionDateTime": { "type": "string", "format": "date-time", "description": "Person group last modify time in the UTC, could be null value when the person group is not successfully trained.", "x-ms-client-name": "lastAction" }, "message": { "type": "string", "description": "Show failure message when training failed (omitted when training succeed)." } } }, "ConfidenceProperty": { "description": "A number ranging from 0 to 1 indicating a level of confidence associated with a property.", "type": "number", "minimum": 0, "maximum": 1 } }, "parameters": { "returnFaceAttributes": { "name": "returnFaceAttributes", "in": "query", "description": "Analyze and return the one or more specified face attributes in the comma-separated string like \"returnFaceAttributes=age,gender\". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost.", "type": "array", "x-ms-parameter-location": "method", "required": false, "collectionFormat": "csv", "items": { "type": "string", "x-nullable": false, "x-ms-enum": { "name": "FaceAttributeTypes", "modelAsString": false }, "enum": [ "age", "gender", "headPose", "smile", "facialHair", "glasses", "emotion", "hair", "makeup", "occlusion", "accessories", "blur", "exposure", "noise" ] } }, "targetFace": { "name": "targetFace", "in": "query", "description": "A face rectangle to specify the target face to be added to a person in the format of \"targetFace=left,top,width,height\". E.g. \"targetFace=10,10,100,100\". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image.", "type": "array", "x-ms-parameter-location": "method", "required": false, "collectionFormat": "csv", "items": { "type": "integer", "format": "int32", "x-nullable": false, "maxItems": 4, "minItems": 4 } } } }