From 5e734a0053e6a3f5b1304abdd51892bd51559409 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Tue, 25 Jul 2017 23:17:50 -0700 Subject: [PATCH 01/13] Adding data plane spec starting with Face --- .../cognitiveservices/Face/v1.0/Face.json | 2611 +++++++++++++++++ 1 file changed, 2611 insertions(+) create mode 100644 specification/cognitiveservices/Face/v1.0/Face.json diff --git a/specification/cognitiveservices/Face/v1.0/Face.json b/specification/cognitiveservices/Face/v1.0/Face.json new file mode 100644 index 000000000000..8cca31c55ce3 --- /dev/null +++ b/specification/cognitiveservices/Face/v1.0/Face.json @@ -0,0 +1,2611 @@ +{ + "swagger": "2.0", + "info": { + "title": "Face API", + "version": "1.0", + "description": "An API for face detection, verification, and identification." + }, + "securityDefinitions": { + "apim_key": { + "type": "apiKey", + "name": "Ocp-Apim-Subscription-Key", + "in": "header" + } + }, + "x-ms-parameterized-host": { + "hostTemplate": "{azureRegion}.api.cognitive.microsoft.com", + "parameters": [ + { + "$ref": "#/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": "Faces_FindSimilar", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/FindSimilarRequest" + } + } + ], + "consumes": [ + "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/FindSimilarResponse" + }, + "examples": { + "application/json": [ + { + "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "confidence": 0.82 + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/group": { + "post": { + "description": "Divide candidate faces into groups based on face similarity.", + "operationId": "Faces_Group", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/GroupRequest" + } + } + ], + "consumes": [ + "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" + }, + "examples": { + "application/json": { + "groups": [ + [ + "c5c24a82-6845-4031-9d5d-978df9175426", + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ], + [ + "65d083d4-9447-47d1-af30-b626144bf0fb", + "30ea1073-cc9e-4652-b1e3-d08fb7b95315" + ] + ], + "messyGroup": [ + "be386ab3-af91-4104-9e6d-4dae4c9fddb7" + ] + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/identify": { + "post": { + "description": "Identify unknown faces from a person group.", + "operationId": "Faces_Identify", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/IdentifyRequest" + } + } + ], + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns the identified candidate person(s) for each query face.", + "schema": { + "$ref": "#/definitions/IdentifyResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "candidates": [ + { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "confidence": 0.92 + } + ] + }, + { + "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb", + "candidates": [ + { + "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", + "confidence": 0.89 + } + ] + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/verify": { + "post": { + "description": "Verify whether two faces belong to a same person or whether one face belongs to a person.", + "operationId": "Faces_Verify", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/VerifyRequest" + } + } + ], + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns the verification result.", + "schema": { + "$ref": "#/definitions/VerifyResponse" + }, + "examples": { + "application/json": { + "isIdentical": true, + "confidence": 0.9 + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/persons": { + "post": { + "description": "Create a new person in a specified person group.", + "operationId": "Persons_Create", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the target person group to create the person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/CreatePersonRequest" + } + } + ], + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns a new personId created.", + "schema": { + "$ref": "#/definitions/CreatePersonResponse" + }, + "examples": { + "application/json": { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "Persons_List", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of person information that belong to the person group.", + "schema": { + "$ref": "#/definitions/ListPersonsResponse" + }, + "examples": { + "application/json": [ + { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "name": "Ryan", + "userData": "User-provided data attached to the person", + "persistedFaceIds": [ + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ] + }, + { + "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", + "name": "David", + "userData": "User-provided data attached to the person", + "persistedFaceIds": [ + "30ea1073-cc9e-4652-b1e3-d08fb7b95315", + "fbd2a038-dbff-452c-8e79-2ee81b1aa84e" + ] + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/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": "Persons_Delete", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "The target personId to delete.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve a person's information, including registered persisted faces, name and userData.", + "operationId": "Persons_Get", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the target person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person's information.", + "schema": { + "$ref": "#/definitions/GetPersonResponse" + }, + "examples": { + "application/json": { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "persistedFaceIds": [ + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ], + "name": "Ryan", + "userData": "User-provided data attached to the person" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update name or userData of a person.", + "operationId": "Persons_Update", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "personId of the target person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "Persons_DeleteFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the person that the target persisted face belong to.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "The persisted face to remove.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).", + "operationId": "Persons_GetFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the target person that the face belongs to.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "The persistedFaceId of the target persisted face of the person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns target persisted face's information (persistedFaceId and userData).", + "schema": { + "$ref": "#/definitions/GetPersonFaceResponse" + }, + "examples": { + "application/json": { + "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "userData": "User-provided data attached to the person" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update a person persisted face's userData field.", + "operationId": "Persons_UpdateFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "personId of the target person.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "persistedFaceId of target face, which is persisted and will not expire.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}": { + "put": { + "description": "Create a new person group with specified personGroupId, name and user-provided userData.", + "operationId": "PersonGroups_Create", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "User-provided personGroupId as a string. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.\n ", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "delete": { + "description": "Delete an existing person group. Persisted face images of all people in the person group will also be deleted.", + "operationId": "PersonGroups_Delete", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "The personGroupId of the person group to be deleted.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve the information of a person group, including its name and userData.", + "operationId": "PersonGroups_Get", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person group's information.", + "schema": { + "$ref": "#/definitions/GetPersonGroupResponse" + }, + "examples": { + "application/json": { + "personGroupId": "sample_group", + "name": "group1", + "userData": "User-provided data attached to the person group" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "PersonGroups_Update", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the person group to be updated.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/training": { + "get": { + "description": "Retrieve the training status of a person group (completed or ongoing).", + "operationId": "PersonGroups_GetTrainingStatus", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person group's training status.", + "schema": { + "$ref": "#/definitions/TrainingStatus" + }, + "examples": { + "application/json": { + "status": "succeeded", + "createdDateTime": "1/3/2017 4:11:35 AM", + "lastActionDateTime": null, + "message": null + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups": { + "get": { + "description": "List person groups and their information.", + "operationId": "PersonGroups_List", + "parameters": [ + { + "name": "start", + "in": "query", + "description": "List person groups from the least personGroupId greater than the \"start\". It contains no more than 64 characters. Default is empty. ", + "type": "string", + "enum": [ + "" + ] + }, + { + "name": "top", + "in": "query", + "description": "The number of person groups to list, ranging in [1, 1000]. Default is 1000. ", + "type": "integer", + "default": "1000", + "enum": [ + "1000" + ] + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of person groups and their information (personGroupId, name and userData).", + "schema": { + "$ref": "#/definitions/ListPersonGroupResponse" + }, + "examples": { + "application/json": [ + { + "personGroupId": "sample_group", + "name": "group1", + "userData": "User-provideddataattachedtothepersongroup" + }, + { + "personGroupId": "sample_group2", + "name": "group2", + "userData": "User-provideddataattachedtothepersongroup" + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/train": { + "post": { + "description": "Queue a person group training task, the training task may not be started immediately.", + "operationId": "PersonGroups_Train", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Target person group to be trained.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "202": { + "description": "A successful call returns an empty JSON body. " + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists/{faceListId}": { + "put": { + "description": "Create an empty face list with user-specified faceListId, name and an optional userData. Up to 64 face lists are allowed to exist in one subscription.", + "operationId": "FaceLists_Create", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve a face list's information, including faceListId, name, userData and faces in the face list. ", + "operationId": "FaceLists_Get", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the face list's information.", + "schema": { + "$ref": "#/definitions/GetFaceListResponse" + }, + "examples": { + "application/json": { + "faceListId": "sample_list", + "name": "list1", + "userData": "User-provideddataattachedtothefacelist", + "persistedFaces": [ + { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBD", + "userData": "User-provideddataattachedtotheface" + } + ] + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update information of a face list, including name and userData. ", + "operationId": "FaceLists_Update", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "delete": { + "description": "Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.", + "operationId": "FaceLists_Delete", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists": { + "get": { + "description": "Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.", + "operationId": "FaceLists_List", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of faceList.", + "schema": { + "$ref": "#/definitions/ListFaceListResponse" + }, + "examples": { + "application/json": [ + { + "faceListId": "sample_list", + "name": "list1", + "userData": "User-provideddataattachedtothefacelist" + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "FaceLists_DeleteFace", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "faceListId of an existing face list. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "persistedFaceId of an existing face. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + } + }, + "x-ms-paths": { + "/detect?overload=url": { + "post": { + "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", + "operationId": "Faces_Detect", + "parameters": [ + { + "name": "returnFaceId", + "in": "query", + "description": "Return faceIds of the detected faces or not. The default value is true. ", + "type": "boolean", + "default": "true", + "enum": [ + "false", + "true" + ] + }, + { + "name": "returnFaceLandmarks", + "in": "query", + "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "type": "boolean", + "default": "false", + "enum": [ + "false", + "true" + ] + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "consumes": [ + "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/DetectResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "faceRectangle": { + "width": 78, + "height": 78, + "left": 394, + "top": 54 + }, + "faceLandmarks": { + "pupilLeft": { + "x": 412.7, + "y": 78.4 + }, + "pupilRight": { + "x": 446.8, + "y": 74.2 + }, + "noseTip": { + "x": 437.7, + "y": 92.4 + }, + "mouthLeft": { + "x": 417.8, + "y": 114.4 + }, + "mouthRight": { + "x": 451.3, + "y": 109.3 + }, + "eyebrowLeftOuter": { + "x": 397.9, + "y": 78.5 + }, + "eyebrowLeftInner": { + "x": 425.4, + "y": 70.5 + }, + "eyeLeftOuter": { + "x": 406.7, + "y": 80.6 + }, + "eyeLeftTop": { + "x": 412.2, + "y": 76.2 + }, + "eyeLeftBottom": { + "x": 413, + "y": 80.1 + }, + "eyeLeftInner": { + "x": 418.9, + "y": 78 + }, + "eyebrowRightInner": { + "x": 4.8, + "y": 69.7 + }, + "eyebrowRightOuter": { + "x": 5.5, + "y": 68.5 + }, + "eyeRightInner": { + "x": 441.5, + "y": 75 + }, + "eyeRightTop": { + "x": 446.4, + "y": 71.7 + }, + "eyeRightBottom": { + "x": 447, + "y": 75.3 + }, + "eyeRightOuter": { + "x": 451.7, + "y": 73.4 + }, + "noseRootLeft": { + "x": 428, + "y": 77.1 + }, + "noseRootRight": { + "x": 435.8, + "y": 75.6 + }, + "noseLeftAlarTop": { + "x": 428.3, + "y": 89.7 + }, + "noseRightAlarTop": { + "x": 442.2, + "y": 87 + }, + "noseLeftAlarOutTip": { + "x": 424.3, + "y": 96.4 + }, + "noseRightAlarOutTip": { + "x": 446.6, + "y": 92.5 + }, + "upperLipTop": { + "x": 437.6, + "y": 105.9 + }, + "upperLipBottom": { + "x": 437.6, + "y": 108.2 + }, + "underLipTop": { + "x": 436.8, + "y": 111.4 + }, + "underLipBottom": { + "x": 437.3, + "y": 114.5 + } + }, + "faceAttributes": { + "age": 71, + "gender": "male", + "smile": 0.88, + "facialHair": { + "mustache": 0.8, + "beard": 0.1, + "sideburns": 0.02 + } + }, + "glasses": "sunglasses", + "headPose": { + "roll": 2.1, + "yaw": 3, + "pitch": 0 + }, + "emotion": { + "anger": 0.575, + "contempt": 0, + "disgust": 0.006, + "fear": 0.008, + "happiness": 0.394, + "neutral": 0.013, + "sadness": 0, + "surprise": 0.004 + } + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/detect?overload=stream": { + "post": { + "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", + "operationId": "Faces_DetectInStream", + "parameters": [ + { + "name": "returnFaceId", + "in": "query", + "description": "Return faceIds of the detected faces or not. The default value is true. ", + "type": "boolean", + "default": "true", + "enum": [ + "false", + "true" + ] + }, + { + "name": "returnFaceLandmarks", + "in": "query", + "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "type": "boolean", + "default": "false", + "enum": [ + "false", + "true" + ] + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "consumes": [ + "application/octet-stream" + ], + "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/DetectResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "faceRectangle": { + "width": 78, + "height": 78, + "left": 394, + "top": 54 + }, + "faceLandmarks": { + "pupilLeft": { + "x": 412.7, + "y": 78.4 + }, + "pupilRight": { + "x": 446.8, + "y": 74.2 + }, + "noseTip": { + "x": 437.7, + "y": 92.4 + }, + "mouthLeft": { + "x": 417.8, + "y": 114.4 + }, + "mouthRight": { + "x": 451.3, + "y": 109.3 + }, + "eyebrowLeftOuter": { + "x": 397.9, + "y": 78.5 + }, + "eyebrowLeftInner": { + "x": 425.4, + "y": 70.5 + }, + "eyeLeftOuter": { + "x": 406.7, + "y": 80.6 + }, + "eyeLeftTop": { + "x": 412.2, + "y": 76.2 + }, + "eyeLeftBottom": { + "x": 413, + "y": 80.1 + }, + "eyeLeftInner": { + "x": 418.9, + "y": 78 + }, + "eyebrowRightInner": { + "x": 4.8, + "y": 69.7 + }, + "eyebrowRightOuter": { + "x": 5.5, + "y": 68.5 + }, + "eyeRightInner": { + "x": 441.5, + "y": 75 + }, + "eyeRightTop": { + "x": 446.4, + "y": 71.7 + }, + "eyeRightBottom": { + "x": 447, + "y": 75.3 + }, + "eyeRightOuter": { + "x": 451.7, + "y": 73.4 + }, + "noseRootLeft": { + "x": 428, + "y": 77.1 + }, + "noseRootRight": { + "x": 435.8, + "y": 75.6 + }, + "noseLeftAlarTop": { + "x": 428.3, + "y": 89.7 + }, + "noseRightAlarTop": { + "x": 442.2, + "y": 87 + }, + "noseLeftAlarOutTip": { + "x": 424.3, + "y": 96.4 + }, + "noseRightAlarOutTip": { + "x": 446.6, + "y": 92.5 + }, + "upperLipTop": { + "x": 437.6, + "y": 105.9 + }, + "upperLipBottom": { + "x": 437.6, + "y": 108.2 + }, + "underLipTop": { + "x": 436.8, + "y": 111.4 + }, + "underLipBottom": { + "x": 437.3, + "y": 114.5 + } + }, + "faceAttributes": { + "age": 71, + "gender": "male", + "smile": 0.88, + "facialHair": { + "mustache": 0.8, + "beard": 0.1, + "sideburns": 0.02 + } + }, + "glasses": "sunglasses", + "headPose": { + "roll": 2.1, + "yaw": 3, + "pitch": 0 + }, + "emotion": { + "anger": 0.575, + "contempt": 0, + "disgust": 0.006, + "fear": 0.008, + "happiness": 0.394, + "neutral": 0.013, + "sadness": 0, + "surprise": 0.004 + } + } + ] + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/persons/{personId}/persistedFaces?overload=url": { + "post": { + "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.It returns a persistedFaceId representing the added face and this persistedFaceId will not expire. ", + "operationId": "Persons_AddFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Target person that the face is added to.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", + "type": "string" + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns the new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "Persons_AddFaceFromStream", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Target person that the face is added to.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", + "type": "string" + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns the new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists/{faceListId}/persistedFaces?overload=url": { + "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": "FaceLists_AddFace", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", + "type": "string" + }, + { + "name": "targetFace", + "in": "query", + "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns a new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "FaceLists_AddFaceFromStream", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", + "type": "string" + }, + { + "name": "targetFace", + "in": "query", + "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns a new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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" + } + } + }, + "ImageUrl": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + } + } + }, + "DetectResponse": { + "type": "array", + "items": { + "$ref": "#/definitions/DetectResponseElement" + } + }, + "DetectResponseElement": { + "type": "object", + "required": [ + "faceRectangle" + ], + "description": "", + "properties": { + "faceId": { + "type": "string" + }, + "faceRectangle": { + "$ref": "#/definitions/FaceRectangle" + }, + "faceLandmarks": { + "$ref": "#/definitions/FaceLandmarks" + } + } + }, + "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": "integer", + "format": "int32", + "description": "The horizontal component, in pixels." + }, + "y": { + "type": "integer", + "format": "int32", + "description": "The vertical component, in pixels." + } + } + }, + "FaceLandmarks": { + "type": "object", + "required": [], + "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", + "required": [], + "description": "Face Attributes", + "properties": { + "age": { + "type": "number", + "description": "Age in years" + }, + "gender": { + "type": "string", + "description": "Gender: male or female", + "enum": [ + "male", + "female" + ] + }, + "smile": { + "type": "number", + "description": "Smile intensity, a number between [0,1] ", + "minimum": 0, + "maximum": 1 + }, + "glasses": { + "type": "string", + "description": "Glasses type. Possible values are 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'. ", + "enum": [ + "noGlasses", + "readingGlasses", + "sunglasses", + "swimmingGoggles" + ] + }, + "facialHair": { + "$ref": "#/definitions/FacialHairProperties" + }, + "headPose": { + "$ref": "#/definitions/HeadPoseProperties" + }, + "emotion": { + "$ref": "#/definitions/EmotionProperties" + } + } + }, + "FacialHairProperties": { + "type": "object", + "required": [], + "description": "", + "properties": { + "mustache": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "beard": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "sideburns": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "HeadPoseProperties": { + "type": "object", + "required": [], + "description": "", + "properties": { + "roll": { + "type": "number" + }, + "yaw": { + "type": "number" + }, + "pitch": { + "type": "number" + } + } + }, + "EmotionProperties": { + "type": "object", + "required": [], + "description": "", + "properties": { + "anger": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "contempt": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "disgust": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "fear": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "happiness": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "neutral": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "sadness": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "surprise": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "FindSimilarRequest": { + "type": "object", + "required": [ + "faceId" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "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" + }, + "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. The number of faceIds is limited to 1000. Parameter faceListId and faceIds should not be provided at the same time.", + "maxLength": 1000, + "items": { + "type": "string" + } + }, + "maxNumOfCandidatesReturned": { + "type": "integer", + "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "default": 20, + "minimum": 1, + "maximum": 1000 + }, + "mode": { + "type": "string", + "description": "Similar face searching mode. It can be \"matchPerson\" or \"matchFace\". It defaults to \"matchPerson\".", + "default": "matchPerson", + "enum": [ + "matchPerson", + "matchFace" + ] + } + } + }, + "FindSimilarResponse": { + "type": "array", + "items": { + "$ref": "#/definitions/FindSimilarResponseElement" + } + }, + "FindSimilarResponseElement": { + "type": "object", + "required": [], + "description": "", + "properties": { + "faceId": { + "type": "string", + "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", + "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": { + "type": "number", + "description": "Similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1" + } + } + }, + "GroupRequest": { + "type": "object", + "required": [], + "description": "", + "properties": { + "faceIds": { + "type": "array", + "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", + "maxLength": 1000, + "items": { + "type": "string" + } + } + } + }, + "GroupResponse": { + "type": "object", + "required": [], + "description": "", + "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" + } + } + }, + "messyGroup": { + "type": "array", + "description": "Face ids array of faces that cannot find any similar faces from original faces.", + "items": { + "type": "string" + } + } + } + }, + "IdentifyRequest": { + "type": "object", + "required": [], + "description": "", + "properties": { + "personGroupId": { + "type": "string", + "description": "personGroupId of the target person group, created by PersonGroups.Create" + }, + "faceIds": { + "type": "array", + "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", + "maxLength": 10, + "items": { + "type": "string" + } + }, + "maxNumOfCandidatesReturned": { + "type": "integer", + "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "default": 1, + "minimum": 1, + "maximum": 5 + }, + "confidenceThreshold": { + "type": "number", + "description": "Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).", + "minimum": 0, + "maximum": 1 + } + } + }, + "IdentifyResponse": { + "type": "array", + "items": {} + }, + "IdentifyResponseElement": { + "type": "object", + "required": [], + "description": "", + "properties": { + "faceId": { + "type": "string", + "description": "faceId of the query face" + }, + "candidates": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/IdentifyResponseCandidatesElement" + } + } + } + }, + "IdentifyResponseCandidatesElement": { + "type": "object", + "required": [], + "description": "", + "properties": { + "personId": { + "type": "string", + "description": "Id of candidate" + }, + "confidence": { + "type": "number", + "description": "Confidence level in the candidate person: a float number between 0.0 and 1.0.", + "minimum": 0, + "maximum": 1 + } + } + }, + "VerifyRequest": { + "type": "object", + "required": [ + "faceId", + "personId", + "personGroupId" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "description": "faceId the face, comes from Face - Detect" + }, + "personId": { + "type": "string", + "description": "Specify a certain person in a person group. personId is created in Persons.Create." + }, + "personGroupId": { + "type": "string", + "description": "Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create." + } + } + }, + "VerifyResponse": { + "type": "object", + "required": [], + "description": "", + "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": { + "type": "number", + "description": "\"A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. By default, isIdentical is set to True if similarity confidence is greater than or equal to 0.5. This is useful for advanced users to override \"isIdentical\" and fine-tune the result on their own data\"", + "minimum": 0, + "maximum": 1 + } + } + }, + "CreateFaceListRequest": { + "type": "object", + "required": [ + "name" + ], + "description": "", + "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 + } + } + }, + "GetFaceListResponse": { + "type": "object", + "required": [], + "description": "", + "properties": { + "faceListId": { + "type": "string", + "description": "faceListId of the target face list.", + "maxLength": 128 + }, + "name": { + "type": "string", + "description": "Face list's display name.", + "maxLength": 128 + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this face list.", + "maxLength": 16384 + } + } + }, + "ListFaceListResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetFaceListResponse" + } + }, + "CreatePersonGroupRequest": { + "type": "object", + "required": [ + "name" + ], + "description": "", + "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 + } + } + }, + "GetPersonGroupResponse": { + "type": "object", + "required": [], + "description": "", + "properties": { + "personGroupId": { + "type": "string", + "description": "faceListId of the target face list.", + "maxLength": 128 + }, + "name": { + "type": "string", + "description": "Face list's display name.", + "maxLength": 128 + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this face list.", + "maxLength": 16384 + } + } + }, + "ListPersonGroupResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetPersonGroupResponse" + } + }, + "CreatePersonRequest": { + "type": "object", + "required": [ + "name" + ], + "description": "", + "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 + } + } + }, + "CreatePersonResponse": { + "type": "object", + "required": [ + "name" + ], + "description": "", + "properties": { + "personId": { + "type": "string", + "description": "personID of the new created person." + } + } + }, + "GetPersonResponse": { + "type": "object", + "required": [], + "description": "", + "properties": { + "personId": { + "type": "string", + "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" + } + }, + "name": { + "type": "string", + "description": "Person's display name." + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this person." + } + } + }, + "ListPersonsResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetPersonResponse" + } + }, + "GetPersonFaceResponse": { + "type": "object", + "required": [], + "description": "", + "properties": { + "persistedFaceId": { + "type": "string", + "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." + } + } + }, + "UpdatePersonFaceDataRequest": { + "type": "object", + "required": [], + "description": "", + "properties": { + "userData": { + "type": "string", + "description": "User-provided data attached to the face. The size limit is 1KB", + "maxLength": 1024 + } + } + }, + "TrainingStatus": { + "type": "object", + "required": [], + "description": "", + "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", + "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)." + } + } + } + }, + "parameters": { + "AzureRegion": { + "name": "azureRegion", + "description": "Supported Azure regions for Face Detection endpoints", + "x-ms-parameter-location": "client", + "required": true, + "type": "string", + "in": "path", + "x-ms-skip-url-encoding": true, + "x-ms-enum": { + "name": "AzureRegion", + "modelAsString": true + }, + "enum": [ + "westus", + "westeurope", + "southeastasia", + "eastus2", + "westcentralus" + ] + }, + "SubscriptionKey": { + "name": "Ocp-Apim-Subscription-Key", + "x-ms-client-name": "SubscriptionKey", + "in": "header", + "required": true, + "description": "Subscription key in header", + "type": "string" + }, + "ImageStream": { + "name": "Image", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "description": "An image stream.", + "schema": { + "type": "file" + } + }, + "ImageUrl": { + "name": "ImageUrl", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "x-ms-client-flatten": true, + "description": "A JSON document with a URL pointing to the image that is to be analyzed.", + "schema": { + "$ref": "#/definitions/ImageUrl" + } + } + } +} \ No newline at end of file From e8f1ee2933834060ad1992ae57b875106bee1211 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Tue, 25 Jul 2017 23:19:32 -0700 Subject: [PATCH 02/13] Move Spec to right folder --- .../cognitiveservices/{ => data-plane}/Face/v1.0/Face.json | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specification/cognitiveservices/{ => data-plane}/Face/v1.0/Face.json (100%) diff --git a/specification/cognitiveservices/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json similarity index 100% rename from specification/cognitiveservices/Face/v1.0/Face.json rename to specification/cognitiveservices/data-plane/Face/v1.0/Face.json From c56cc0e3a4735aeb48556dd22eeddcf9956658d6 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Wed, 26 Jul 2017 20:18:30 -0700 Subject: [PATCH 03/13] Fixing validation issues. --- .../data-plane/Face/v1.0/Face.json | 5230 +++++++++-------- 1 file changed, 2637 insertions(+), 2593 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json index 8cca31c55ce3..63ea7be72e79 100644 --- a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json @@ -1,2611 +1,2655 @@ { - "swagger": "2.0", - "info": { - "title": "Face API", - "version": "1.0", - "description": "An API for face detection, verification, and identification." - }, - "securityDefinitions": { - "apim_key": { - "type": "apiKey", - "name": "Ocp-Apim-Subscription-Key", - "in": "header" + "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" + } + }, + "x-ms-parameterized-host": { + "hostTemplate": "{azureRegion}.api.cognitive.microsoft.com", + "parameters": [ + { + "$ref": "#/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": "Faces_FindSimilar", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/FindSimilarRequest" + } + } + ], + "consumes": [ + "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/FindSimilarResponse" + }, + "examples": { + "application/json": [ + { + "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "confidence": 0.82 } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } }, - "x-ms-parameterized-host": { - "hostTemplate": "{azureRegion}.api.cognitive.microsoft.com", - "parameters": [ - { - "$ref": "#/parameters/AzureRegion" - } + "produces": [ + "application/json" + ] + } + }, + "/group": { + "post": { + "description": "Divide candidate faces into groups based on face similarity.", + "operationId": "Faces_Group", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/GroupRequest" + } + } + ], + "consumes": [ + "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" + }, + "examples": { + "application/json": { + "groups": [ + [ + "c5c24a82-6845-4031-9d5d-978df9175426", + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ], + [ + "65d083d4-9447-47d1-af30-b626144bf0fb", + "30ea1073-cc9e-4652-b1e3-d08fb7b95315" + ] + ], + "messyGroup": [ + "be386ab3-af91-4104-9e6d-4dae4c9fddb7" ] + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } }, - "basePath": "/face/v1.0", - "schemes": [ - "https" + "produces": [ + "application/json" + ] + } + }, + "/identify": { + "post": { + "description": "Identify unknown faces from a person group.", + "operationId": "Faces_Identify", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/IdentifyRequest" + } + } ], - "paths": { - "/findsimilars": { - "post": { - "description": "Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.", - "operationId": "Faces_FindSimilar", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "in": "body", - "required": true, - "x-ms-client-flatten": true, - "schema": { - "$ref": "#/definitions/FindSimilarRequest" - } - } - ], - "consumes": [ - "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/FindSimilarResponse" - }, - "examples": { - "application/json": [ - { - "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", - "confidence": 0.82 - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/group": { - "post": { - "description": "Divide candidate faces into groups based on face similarity.", - "operationId": "Faces_Group", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "in": "body", - "required": true, - "x-ms-client-flatten": true, - "schema": { - "$ref": "#/definitions/GroupRequest" - } - } - ], - "consumes": [ - "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" - }, - "examples": { - "application/json": { - "groups": [ - [ - "c5c24a82-6845-4031-9d5d-978df9175426", - "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", - "fce92aed-d578-4d2e-8114-068f8af4492e", - "b64d5e15-8257-4af2-b20a-5a750f8940e7" - ], - [ - "65d083d4-9447-47d1-af30-b626144bf0fb", - "30ea1073-cc9e-4652-b1e3-d08fb7b95315" - ] - ], - "messyGroup": [ - "be386ab3-af91-4104-9e6d-4dae4c9fddb7" - ] - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/identify": { - "post": { - "description": "Identify unknown faces from a person group.", - "operationId": "Faces_Identify", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "in": "body", - "required": true, - "x-ms-client-flatten": true, - "schema": { - "$ref": "#/definitions/IdentifyRequest" - } - } - ], - "consumes": [ - "application/json" - ], - "responses": { - "200": { - "description": "A successful call returns the identified candidate person(s) for each query face.", - "schema": { - "$ref": "#/definitions/IdentifyResponse" - }, - "examples": { - "application/json": [ - { - "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", - "candidates": [ - { - "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", - "confidence": 0.92 - } - ] - }, - { - "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb", - "candidates": [ - { - "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", - "confidence": 0.89 - } - ] - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/verify": { - "post": { - "description": "Verify whether two faces belong to a same person or whether one face belongs to a person.", - "operationId": "Faces_Verify", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "in": "body", - "required": true, - "x-ms-client-flatten": true, - "schema": { - "$ref": "#/definitions/VerifyRequest" - } - } - ], - "consumes": [ - "application/json" - ], - "responses": { - "200": { - "description": "A successful call returns the verification result.", - "schema": { - "$ref": "#/definitions/VerifyResponse" - }, - "examples": { - "application/json": { - "isIdentical": true, - "confidence": 0.9 - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups/{personGroupId}/persons": { - "post": { - "description": "Create a new person in a specified person group.", - "operationId": "Persons_Create", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the target person group to create the person.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "in": "body", - "required": true, - "x-ms-client-flatten": true, - "schema": { - "$ref": "#/definitions/CreatePersonRequest" - } - } - ], - "consumes": [ - "application/json" - ], - "responses": { - "200": { - "description": "A successful call returns a new personId created.", - "schema": { - "$ref": "#/definitions/CreatePersonResponse" - }, - "examples": { - "application/json": { - "personId": "25985303-c537-4467-b41d-bdb45cd95ca1" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/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": "Persons_List", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "personGroupId of the target person group.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an array of person information that belong to the person group.", - "schema": { - "$ref": "#/definitions/ListPersonsResponse" - }, - "examples": { - "application/json": [ - { - "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", - "name": "Ryan", - "userData": "User-provided data attached to the person", - "persistedFaceIds": [ - "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", - "fce92aed-d578-4d2e-8114-068f8af4492e", - "b64d5e15-8257-4af2-b20a-5a750f8940e7" - ] - }, - { - "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", - "name": "David", - "userData": "User-provided data attached to the person", - "persistedFaceIds": [ - "30ea1073-cc9e-4652-b1e3-d08fb7b95315", - "fbd2a038-dbff-452c-8e79-2ee81b1aa84e" - ] - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/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": "Persons_Delete", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "The target personId to delete.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an empty response body." - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "get": { - "description": "Retrieve a person's information, including registered persisted faces, name and userData.", - "operationId": "Persons_Get", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "Specifying the target person.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns the person's information.", - "schema": { - "$ref": "#/definitions/GetPersonResponse" - }, - "examples": { - "application/json": { - "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", - "persistedFaceIds": [ - "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", - "fce92aed-d578-4d2e-8114-068f8af4492e", - "b64d5e15-8257-4af2-b20a-5a750f8940e7" - ], - "name": "Ryan", - "userData": "User-provided data attached to the person" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "patch": { - "description": "Update name or userData of a person.", - "operationId": "Persons_Update", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "personId of the target person.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/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": "Persons_DeleteFace", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "Specifying the person that the target persisted face belong to.", - "required": true, - "type": "string" - }, - { - "name": "persistedFaceId", - "in": "path", - "description": "The persisted face to remove.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an empty response body." - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "get": { - "description": "Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).", - "operationId": "Persons_GetFace", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "Specifying the target person that the face belongs to.", - "required": true, - "type": "string" - }, - { - "name": "persistedFaceId", - "in": "path", - "description": "The persistedFaceId of the target persisted face of the person.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns target persisted face's information (persistedFaceId and userData).", - "schema": { - "$ref": "#/definitions/GetPersonFaceResponse" - }, - "examples": { - "application/json": { - "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", - "userData": "User-provided data attached to the person" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "patch": { - "description": "Update a person persisted face's userData field.", - "operationId": "Persons_UpdateFace", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "personId of the target person.", - "required": true, - "type": "string" - }, - { - "name": "persistedFaceId", - "in": "path", - "description": "persistedFaceId of target face, which is persisted and will not expire.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups/{personGroupId}": { - "put": { - "description": "Create a new person group with specified personGroupId, name and user-provided userData.", - "operationId": "PersonGroups_Create", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "User-provided personGroupId as a string. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.\n ", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "delete": { - "description": "Delete an existing person group. Persisted face images of all people in the person group will also be deleted.", - "operationId": "PersonGroups_Delete", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "The personGroupId of the person group to be deleted.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an empty response body." - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "get": { - "description": "Retrieve the information of a person group, including its name and userData.", - "operationId": "PersonGroups_Get", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "personGroupId of the target person group.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns the person group's information.", - "schema": { - "$ref": "#/definitions/GetPersonGroupResponse" - }, - "examples": { - "application/json": { - "personGroupId": "sample_group", - "name": "group1", - "userData": "User-provided data attached to the person group" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/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": "PersonGroups_Update", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "personGroupId of the person group to be updated.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups/{personGroupId}/training": { - "get": { - "description": "Retrieve the training status of a person group (completed or ongoing).", - "operationId": "PersonGroups_GetTrainingStatus", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "personGroupId of target person group.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns the person group's training status.", - "schema": { - "$ref": "#/definitions/TrainingStatus" - }, - "examples": { - "application/json": { - "status": "succeeded", - "createdDateTime": "1/3/2017 4:11:35 AM", - "lastActionDateTime": null, - "message": null - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups": { - "get": { - "description": "List person groups and their information.", - "operationId": "PersonGroups_List", - "parameters": [ - { - "name": "start", - "in": "query", - "description": "List person groups from the least personGroupId greater than the \"start\". It contains no more than 64 characters. Default is empty. ", - "type": "string", - "enum": [ - "" - ] - }, - { - "name": "top", - "in": "query", - "description": "The number of person groups to list, ranging in [1, 1000]. Default is 1000. ", - "type": "integer", - "default": "1000", - "enum": [ - "1000" - ] - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an array of person groups and their information (personGroupId, name and userData).", - "schema": { - "$ref": "#/definitions/ListPersonGroupResponse" - }, - "examples": { - "application/json": [ - { - "personGroupId": "sample_group", - "name": "group1", - "userData": "User-provideddataattachedtothepersongroup" - }, - { - "personGroupId": "sample_group2", - "name": "group2", - "userData": "User-provideddataattachedtothepersongroup" - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups/{personGroupId}/train": { - "post": { - "description": "Queue a person group training task, the training task may not be started immediately.", - "operationId": "PersonGroups_Train", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Target person group to be trained.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "202": { - "description": "A successful call returns an empty JSON body. " - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/facelists/{faceListId}": { - "put": { - "description": "Create an empty face list with user-specified faceListId, name and an optional userData. Up to 64 face lists are allowed to exist in one subscription.", - "operationId": "FaceLists_Create", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "get": { - "description": "Retrieve a face list's information, including faceListId, name, userData and faces in the face list. ", - "operationId": "FaceLists_Get", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns the face list's information.", - "schema": { - "$ref": "#/definitions/GetFaceListResponse" - }, - "examples": { - "application/json": { - "faceListId": "sample_list", - "name": "list1", - "userData": "User-provideddataattachedtothefacelist", - "persistedFaces": [ - { - "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBD", - "userData": "User-provideddataattachedtotheface" - } - ] - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "patch": { - "description": "Update information of a face list, including name and userData. ", - "operationId": "FaceLists_Update", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "body", - "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": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - }, - "delete": { - "description": "Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.", - "operationId": "FaceLists_Delete", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an empty response body." - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/facelists": { - "get": { - "description": "Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.", - "operationId": "FaceLists_List", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an array of faceList.", - "schema": { - "$ref": "#/definitions/ListFaceListResponse" - }, - "examples": { - "application/json": [ - { - "faceListId": "sample_list", - "name": "list1", - "userData": "User-provideddataattachedtothefacelist" - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns the identified candidate person(s) for each query face.", + "schema": { + "$ref": "#/definitions/IdentifyResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "candidates": [ + { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "confidence": 0.92 + } + ] }, - "/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": "FaceLists_DeleteFace", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "faceListId of an existing face list. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "name": "persistedFaceId", - "in": "path", - "description": "persistedFaceId of an existing face. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "description": "A successful call returns an empty response body." - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } + { + "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb", + "candidates": [ + { + "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", + "confidence": 0.89 + } + ] } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } }, - "x-ms-paths": { - "/detect?overload=url": { - "post": { - "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", - "operationId": "Faces_Detect", - "parameters": [ - { - "name": "returnFaceId", - "in": "query", - "description": "Return faceIds of the detected faces or not. The default value is true. ", - "type": "boolean", - "default": "true", - "enum": [ - "false", - "true" - ] - }, - { - "name": "returnFaceLandmarks", - "in": "query", - "description": "Return face landmarks of the detected faces or not. The default value is false. ", - "type": "boolean", - "default": "false", - "enum": [ - "false", - "true" - ] - }, - { - "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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageUrl" - } - ], - "consumes": [ - "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/DetectResponse" - }, - "examples": { - "application/json": [ - { - "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", - "faceRectangle": { - "width": 78, - "height": 78, - "left": 394, - "top": 54 - }, - "faceLandmarks": { - "pupilLeft": { - "x": 412.7, - "y": 78.4 - }, - "pupilRight": { - "x": 446.8, - "y": 74.2 - }, - "noseTip": { - "x": 437.7, - "y": 92.4 - }, - "mouthLeft": { - "x": 417.8, - "y": 114.4 - }, - "mouthRight": { - "x": 451.3, - "y": 109.3 - }, - "eyebrowLeftOuter": { - "x": 397.9, - "y": 78.5 - }, - "eyebrowLeftInner": { - "x": 425.4, - "y": 70.5 - }, - "eyeLeftOuter": { - "x": 406.7, - "y": 80.6 - }, - "eyeLeftTop": { - "x": 412.2, - "y": 76.2 - }, - "eyeLeftBottom": { - "x": 413, - "y": 80.1 - }, - "eyeLeftInner": { - "x": 418.9, - "y": 78 - }, - "eyebrowRightInner": { - "x": 4.8, - "y": 69.7 - }, - "eyebrowRightOuter": { - "x": 5.5, - "y": 68.5 - }, - "eyeRightInner": { - "x": 441.5, - "y": 75 - }, - "eyeRightTop": { - "x": 446.4, - "y": 71.7 - }, - "eyeRightBottom": { - "x": 447, - "y": 75.3 - }, - "eyeRightOuter": { - "x": 451.7, - "y": 73.4 - }, - "noseRootLeft": { - "x": 428, - "y": 77.1 - }, - "noseRootRight": { - "x": 435.8, - "y": 75.6 - }, - "noseLeftAlarTop": { - "x": 428.3, - "y": 89.7 - }, - "noseRightAlarTop": { - "x": 442.2, - "y": 87 - }, - "noseLeftAlarOutTip": { - "x": 424.3, - "y": 96.4 - }, - "noseRightAlarOutTip": { - "x": 446.6, - "y": 92.5 - }, - "upperLipTop": { - "x": 437.6, - "y": 105.9 - }, - "upperLipBottom": { - "x": 437.6, - "y": 108.2 - }, - "underLipTop": { - "x": 436.8, - "y": 111.4 - }, - "underLipBottom": { - "x": 437.3, - "y": 114.5 - } - }, - "faceAttributes": { - "age": 71, - "gender": "male", - "smile": 0.88, - "facialHair": { - "mustache": 0.8, - "beard": 0.1, - "sideburns": 0.02 - } - }, - "glasses": "sunglasses", - "headPose": { - "roll": 2.1, - "yaw": 3, - "pitch": 0 - }, - "emotion": { - "anger": 0.575, - "contempt": 0, - "disgust": 0.006, - "fear": 0.008, - "happiness": 0.394, - "neutral": 0.013, - "sadness": 0, - "surprise": 0.004 - } - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/detect?overload=stream": { - "post": { - "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", - "operationId": "Faces_DetectInStream", - "parameters": [ - { - "name": "returnFaceId", - "in": "query", - "description": "Return faceIds of the detected faces or not. The default value is true. ", - "type": "boolean", - "default": "true", - "enum": [ - "false", - "true" - ] - }, - { - "name": "returnFaceLandmarks", - "in": "query", - "description": "Return face landmarks of the detected faces or not. The default value is false. ", - "type": "boolean", - "default": "false", - "enum": [ - "false", - "true" - ] - }, - { - "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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "consumes": [ - "application/octet-stream" - ], - "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/DetectResponse" - }, - "examples": { - "application/json": [ - { - "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", - "faceRectangle": { - "width": 78, - "height": 78, - "left": 394, - "top": 54 - }, - "faceLandmarks": { - "pupilLeft": { - "x": 412.7, - "y": 78.4 - }, - "pupilRight": { - "x": 446.8, - "y": 74.2 - }, - "noseTip": { - "x": 437.7, - "y": 92.4 - }, - "mouthLeft": { - "x": 417.8, - "y": 114.4 - }, - "mouthRight": { - "x": 451.3, - "y": 109.3 - }, - "eyebrowLeftOuter": { - "x": 397.9, - "y": 78.5 - }, - "eyebrowLeftInner": { - "x": 425.4, - "y": 70.5 - }, - "eyeLeftOuter": { - "x": 406.7, - "y": 80.6 - }, - "eyeLeftTop": { - "x": 412.2, - "y": 76.2 - }, - "eyeLeftBottom": { - "x": 413, - "y": 80.1 - }, - "eyeLeftInner": { - "x": 418.9, - "y": 78 - }, - "eyebrowRightInner": { - "x": 4.8, - "y": 69.7 - }, - "eyebrowRightOuter": { - "x": 5.5, - "y": 68.5 - }, - "eyeRightInner": { - "x": 441.5, - "y": 75 - }, - "eyeRightTop": { - "x": 446.4, - "y": 71.7 - }, - "eyeRightBottom": { - "x": 447, - "y": 75.3 - }, - "eyeRightOuter": { - "x": 451.7, - "y": 73.4 - }, - "noseRootLeft": { - "x": 428, - "y": 77.1 - }, - "noseRootRight": { - "x": 435.8, - "y": 75.6 - }, - "noseLeftAlarTop": { - "x": 428.3, - "y": 89.7 - }, - "noseRightAlarTop": { - "x": 442.2, - "y": 87 - }, - "noseLeftAlarOutTip": { - "x": 424.3, - "y": 96.4 - }, - "noseRightAlarOutTip": { - "x": 446.6, - "y": 92.5 - }, - "upperLipTop": { - "x": 437.6, - "y": 105.9 - }, - "upperLipBottom": { - "x": 437.6, - "y": 108.2 - }, - "underLipTop": { - "x": 436.8, - "y": 111.4 - }, - "underLipBottom": { - "x": 437.3, - "y": 114.5 - } - }, - "faceAttributes": { - "age": 71, - "gender": "male", - "smile": 0.88, - "facialHair": { - "mustache": 0.8, - "beard": 0.1, - "sideburns": 0.02 - } - }, - "glasses": "sunglasses", - "headPose": { - "roll": 2.1, - "yaw": 3, - "pitch": 0 - }, - "emotion": { - "anger": 0.575, - "contempt": 0, - "disgust": 0.006, - "fear": 0.008, - "happiness": 0.394, - "neutral": 0.013, - "sadness": 0, - "surprise": 0.004 - } - } - ] - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/persongroups/{personGroupId}/persons/{personId}/persistedFaces?overload=url": { - "post": { - "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.It returns a persistedFaceId representing the added face and this persistedFaceId will not expire. ", - "operationId": "Persons_AddFace", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "Target person that the face is added to.", - "required": true, - "type": "string" - }, - { - "name": "userData", - "in": "query", - "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", - "type": "string" - }, - { - "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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "consumes": [ - "application/json", - "application/octet-stream" - ], - "responses": { - "200": { - "description": "A successful call returns the new persistedFaceId.", - "examples": { - "application/json": { - "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/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": "Persons_AddFaceFromStream", - "parameters": [ - { - "name": "personGroupId", - "in": "path", - "description": "Specifying the person group containing the target person.", - "required": true, - "type": "string" - }, - { - "name": "personId", - "in": "path", - "description": "Target person that the face is added to.", - "required": true, - "type": "string" - }, - { - "name": "userData", - "in": "query", - "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", - "type": "string" - }, - { - "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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "consumes": [ - "application/json", - "application/octet-stream" - ], - "responses": { - "200": { - "description": "A successful call returns the new persistedFaceId.", - "examples": { - "application/json": { - "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } - }, - "/facelists/{faceListId}/persistedFaces?overload=url": { - "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": "FaceLists_AddFace", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "name": "userData", - "in": "query", - "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", - "type": "string" - }, - { - "name": "targetFace", - "in": "query", - "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "consumes": [ - "application/json", - "application/octet-stream" - ], - "responses": { - "200": { - "description": "A successful call returns a new persistedFaceId.", - "examples": { - "application/json": { - "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } + "produces": [ + "application/json" + ] + } + }, + "/verify": { + "post": { + "description": "Verify whether two faces belong to a same person or whether one face belongs to a person.", + "operationId": "Faces_Verify", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/VerifyRequest" + } + } + ], + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns the verification result.", + "schema": { + "$ref": "#/definitions/VerifyResponse" + }, + "examples": { + "application/json": { + "isIdentical": true, + "confidence": 0.9 + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/persons": { + "post": { + "description": "Create a new person in a specified person group.", + "operationId": "Persons_Create", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the target person group to create the person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "in": "body", + "required": true, + "x-ms-client-flatten": true, + "schema": { + "$ref": "#/definitions/CreatePersonRequest" + } + } + ], + "consumes": [ + "application/json" + ], + "responses": { + "200": { + "description": "A successful call returns a new personId created.", + "schema": { + "$ref": "#/definitions/CreatePersonResponse" + }, + "examples": { + "application/json": { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "Persons_List", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of person information that belong to the person group.", + "schema": { + "$ref": "#/definitions/ListPersonsResponse" + }, + "examples": { + "application/json": [ + { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "name": "Ryan", + "userData": "User-provided data attached to the person", + "persistedFaceIds": [ + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ] }, - "/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": "FaceLists_AddFaceFromStream", - "parameters": [ - { - "name": "faceListId", - "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", - "required": true, - "type": "string" - }, - { - "name": "userData", - "in": "query", - "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", - "type": "string" - }, - { - "name": "targetFace", - "in": "query", - "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "consumes": [ - "application/json", - "application/octet-stream" - ], - "responses": { - "200": { - "description": "A successful call returns a new persistedFaceId.", - "examples": { - "application/json": { - "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/APIError" - } - } - }, - "produces": [ - "application/json" - ] - } + { + "personId": "2ae4935b-9659-44c3-977f-61fac20d0538", + "name": "David", + "userData": "User-provided data attached to the person", + "persistedFaceIds": [ + "30ea1073-cc9e-4652-b1e3-d08fb7b95315", + "fbd2a038-dbff-452c-8e79-2ee81b1aa84e" + ] } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } }, - "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" - } - } - }, - "ImageUrl": { - "type": "object", - "required": [ - "url" - ], - "properties": { - "url": { - "type": "string" - } - } - }, - "DetectResponse": { - "type": "array", - "items": { - "$ref": "#/definitions/DetectResponseElement" - } - }, - "DetectResponseElement": { - "type": "object", - "required": [ - "faceRectangle" - ], - "description": "", - "properties": { - "faceId": { - "type": "string" - }, - "faceRectangle": { - "$ref": "#/definitions/FaceRectangle" - }, - "faceLandmarks": { - "$ref": "#/definitions/FaceLandmarks" - } - } - }, - "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": "integer", - "format": "int32", - "description": "The horizontal component, in pixels." - }, - "y": { - "type": "integer", - "format": "int32", - "description": "The vertical component, in pixels." - } - } - }, - "FaceLandmarks": { - "type": "object", - "required": [], - "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", - "required": [], - "description": "Face Attributes", - "properties": { - "age": { - "type": "number", - "description": "Age in years" - }, - "gender": { - "type": "string", - "description": "Gender: male or female", - "enum": [ - "male", - "female" - ] - }, - "smile": { - "type": "number", - "description": "Smile intensity, a number between [0,1] ", - "minimum": 0, - "maximum": 1 - }, - "glasses": { - "type": "string", - "description": "Glasses type. Possible values are 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'. ", - "enum": [ - "noGlasses", - "readingGlasses", - "sunglasses", - "swimmingGoggles" - ] - }, - "facialHair": { - "$ref": "#/definitions/FacialHairProperties" - }, - "headPose": { - "$ref": "#/definitions/HeadPoseProperties" - }, - "emotion": { - "$ref": "#/definitions/EmotionProperties" - } - } - }, - "FacialHairProperties": { - "type": "object", - "required": [], - "description": "", - "properties": { - "mustache": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "beard": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "sideburns": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "HeadPoseProperties": { - "type": "object", - "required": [], - "description": "", - "properties": { - "roll": { - "type": "number" - }, - "yaw": { - "type": "number" - }, - "pitch": { - "type": "number" - } - } - }, - "EmotionProperties": { - "type": "object", - "required": [], - "description": "", - "properties": { - "anger": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "contempt": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "disgust": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "fear": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "happiness": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "neutral": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "sadness": { - "type": "number", - "minimum": 0, - "maximum": 1 - }, - "surprise": { - "type": "number", - "minimum": 0, - "maximum": 1 - } - } - }, - "FindSimilarRequest": { - "type": "object", - "required": [ - "faceId" - ], - "description": "", - "properties": { - "faceId": { - "type": "string", - "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" - }, - "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. The number of faceIds is limited to 1000. Parameter faceListId and faceIds should not be provided at the same time.", - "maxLength": 1000, - "items": { - "type": "string" - } - }, - "maxNumOfCandidatesReturned": { - "type": "integer", - "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", - "default": 20, - "minimum": 1, - "maximum": 1000 - }, - "mode": { - "type": "string", - "description": "Similar face searching mode. It can be \"matchPerson\" or \"matchFace\". It defaults to \"matchPerson\".", - "default": "matchPerson", - "enum": [ - "matchPerson", - "matchFace" - ] - } - } - }, - "FindSimilarResponse": { - "type": "array", - "items": { - "$ref": "#/definitions/FindSimilarResponseElement" - } - }, - "FindSimilarResponseElement": { - "type": "object", - "required": [], - "description": "", - "properties": { - "faceId": { - "type": "string", - "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", - "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": { - "type": "number", - "description": "Similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1" - } - } - }, - "GroupRequest": { - "type": "object", - "required": [], - "description": "", - "properties": { - "faceIds": { - "type": "array", - "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", - "maxLength": 1000, - "items": { - "type": "string" - } - } - } - }, - "GroupResponse": { - "type": "object", - "required": [], - "description": "", - "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" - } - } - }, - "messyGroup": { - "type": "array", - "description": "Face ids array of faces that cannot find any similar faces from original faces.", - "items": { - "type": "string" - } - } - } - }, - "IdentifyRequest": { - "type": "object", - "required": [], - "description": "", - "properties": { - "personGroupId": { - "type": "string", - "description": "personGroupId of the target person group, created by PersonGroups.Create" - }, - "faceIds": { - "type": "array", - "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", - "maxLength": 10, - "items": { - "type": "string" - } - }, - "maxNumOfCandidatesReturned": { - "type": "integer", - "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", - "default": 1, - "minimum": 1, - "maximum": 5 - }, - "confidenceThreshold": { - "type": "number", - "description": "Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).", - "minimum": 0, - "maximum": 1 - } - } - }, - "IdentifyResponse": { - "type": "array", - "items": {} - }, - "IdentifyResponseElement": { - "type": "object", - "required": [], - "description": "", - "properties": { - "faceId": { - "type": "string", - "description": "faceId of the query face" - }, - "candidates": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/IdentifyResponseCandidatesElement" - } - } - } - }, - "IdentifyResponseCandidatesElement": { - "type": "object", - "required": [], - "description": "", - "properties": { - "personId": { - "type": "string", - "description": "Id of candidate" - }, - "confidence": { - "type": "number", - "description": "Confidence level in the candidate person: a float number between 0.0 and 1.0.", - "minimum": 0, - "maximum": 1 - } - } - }, - "VerifyRequest": { - "type": "object", - "required": [ - "faceId", - "personId", - "personGroupId" - ], - "description": "", - "properties": { - "faceId": { - "type": "string", - "description": "faceId the face, comes from Face - Detect" - }, - "personId": { - "type": "string", - "description": "Specify a certain person in a person group. personId is created in Persons.Create." - }, - "personGroupId": { - "type": "string", - "description": "Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create." - } - } - }, - "VerifyResponse": { - "type": "object", - "required": [], - "description": "", - "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": { - "type": "number", - "description": "\"A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. By default, isIdentical is set to True if similarity confidence is greater than or equal to 0.5. This is useful for advanced users to override \"isIdentical\" and fine-tune the result on their own data\"", - "minimum": 0, - "maximum": 1 - } - } - }, - "CreateFaceListRequest": { - "type": "object", - "required": [ - "name" - ], - "description": "", - "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 - } - } - }, - "GetFaceListResponse": { - "type": "object", - "required": [], - "description": "", - "properties": { - "faceListId": { - "type": "string", - "description": "faceListId of the target face list.", - "maxLength": 128 - }, - "name": { - "type": "string", - "description": "Face list's display name.", - "maxLength": 128 - }, - "userData": { - "type": "string", - "description": "User-provided data attached to this face list.", - "maxLength": 16384 - } - } - }, - "ListFaceListResponse": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/GetFaceListResponse" - } - }, - "CreatePersonGroupRequest": { - "type": "object", - "required": [ - "name" - ], - "description": "", - "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 - } - } - }, - "GetPersonGroupResponse": { - "type": "object", - "required": [], - "description": "", - "properties": { - "personGroupId": { - "type": "string", - "description": "faceListId of the target face list.", - "maxLength": 128 - }, - "name": { - "type": "string", - "description": "Face list's display name.", - "maxLength": 128 - }, - "userData": { - "type": "string", - "description": "User-provided data attached to this face list.", - "maxLength": 16384 - } - } - }, - "ListPersonGroupResponse": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/GetPersonGroupResponse" - } - }, - "CreatePersonRequest": { - "type": "object", - "required": [ - "name" - ], - "description": "", - "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 - } - } - }, - "CreatePersonResponse": { - "type": "object", - "required": [ - "name" - ], - "description": "", - "properties": { - "personId": { - "type": "string", - "description": "personID of the new created person." - } - } - }, - "GetPersonResponse": { - "type": "object", - "required": [], - "description": "", - "properties": { - "personId": { - "type": "string", - "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" - } - }, - "name": { - "type": "string", - "description": "Person's display name." - }, - "userData": { - "type": "string", - "description": "User-provided data attached to this person." - } - } - }, - "ListPersonsResponse": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/GetPersonResponse" - } - }, - "GetPersonFaceResponse": { - "type": "object", - "required": [], - "description": "", - "properties": { - "persistedFaceId": { - "type": "string", - "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." - } - } - }, - "UpdatePersonFaceDataRequest": { - "type": "object", - "required": [], - "description": "", - "properties": { - "userData": { - "type": "string", - "description": "User-provided data attached to the face. The size limit is 1KB", - "maxLength": 1024 - } - } + "produces": [ + "application/json" + ] + } + }, + "/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": "Persons_Delete", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "The target personId to delete.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve a person's information, including registered persisted faces, name and userData.", + "operationId": "Persons_Get", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the target person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person's information.", + "schema": { + "$ref": "#/definitions/GetPersonResponse" + }, + "examples": { + "application/json": { + "personId": "25985303-c537-4467-b41d-bdb45cd95ca1", + "persistedFaceIds": [ + "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "fce92aed-d578-4d2e-8114-068f8af4492e", + "b64d5e15-8257-4af2-b20a-5a750f8940e7" + ], + "name": "Ryan", + "userData": "User-provided data attached to the person" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update name or userData of a person.", + "operationId": "Persons_Update", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "personId of the target person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/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": "Persons_DeleteFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the person that the target persisted face belong to.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "The persisted face to remove.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).", + "operationId": "Persons_GetFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Specifying the target person that the face belongs to.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "The persistedFaceId of the target persisted face of the person.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns target persisted face's information (persistedFaceId and userData).", + "schema": { + "$ref": "#/definitions/GetPersonFaceResponse" + }, + "examples": { + "application/json": { + "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", + "userData": "User-provided data attached to the person" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update a person persisted face's userData field.", + "operationId": "Persons_UpdateFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "personId of the target person.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "persistedFaceId of target face, which is persisted and will not expire.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}": { + "put": { + "description": "Create a new person group with specified personGroupId, name and user-provided userData.", + "operationId": "PersonGroups_Create", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "User-provided personGroupId as a string. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.\n ", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/json" + ] + }, + "delete": { + "description": "Delete an existing person group. Persisted face images of all people in the person group will also be deleted.", + "operationId": "PersonGroups_Delete", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "The personGroupId of the person group to be deleted.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve the information of a person group, including its name and userData.", + "operationId": "PersonGroups_Get", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person group's information.", + "schema": { + "$ref": "#/definitions/GetPersonGroupResponse" + }, + "examples": { + "application/json": { + "personGroupId": "sample_group", + "name": "group1", + "userData": "User-provided data attached to the person group" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "PersonGroups_Update", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of the person group to be updated.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/training": { + "get": { + "description": "Retrieve the training status of a person group (completed or ongoing).", + "operationId": "PersonGroups_GetTrainingStatus", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "personGroupId of target person group.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the person group's training status.", + "schema": { + "$ref": "#/definitions/TrainingStatus" + }, + "examples": { + "application/json": { + "status": "succeeded", + "createdDateTime": "1/3/2017 4:11:35 AM", + "lastActionDateTime": null, + "message": null + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups": { + "get": { + "description": "List person groups and their information.", + "operationId": "PersonGroups_List", + "parameters": [ + { + "name": "start", + "in": "query", + "description": "List person groups from the least personGroupId greater than the \"start\". It contains no more than 64 characters. Default is empty. ", + "type": "string", + "enum": [ + "" + ] + }, + { + "name": "top", + "in": "query", + "description": "The number of person groups to list, ranging in [1, 1000]. Default is 1000. ", + "type": "integer", + "default": "1000", + "enum": [ + "1000" + ] + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of person groups and their information (personGroupId, name and userData).", + "schema": { + "$ref": "#/definitions/ListPersonGroupResponse" + }, + "examples": { + "application/json": [ + { + "personGroupId": "sample_group", + "name": "group1", + "userData": "User-provideddataattachedtothepersongroup" }, - "TrainingStatus": { - "type": "object", - "required": [], - "description": "", - "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", - "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)." - } - } + { + "personGroupId": "sample_group2", + "name": "group2", + "userData": "User-provideddataattachedtothepersongroup" } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } }, - "parameters": { - "AzureRegion": { - "name": "azureRegion", - "description": "Supported Azure regions for Face Detection endpoints", - "x-ms-parameter-location": "client", - "required": true, - "type": "string", - "in": "path", - "x-ms-skip-url-encoding": true, - "x-ms-enum": { - "name": "AzureRegion", - "modelAsString": true - }, - "enum": [ - "westus", - "westeurope", - "southeastasia", - "eastus2", - "westcentralus" - ] - }, - "SubscriptionKey": { - "name": "Ocp-Apim-Subscription-Key", - "x-ms-client-name": "SubscriptionKey", - "in": "header", - "required": true, - "description": "Subscription key in header", - "type": "string" - }, - "ImageStream": { - "name": "Image", - "in": "body", - "required": true, - "x-ms-parameter-location": "method", - "description": "An image stream.", - "schema": { - "type": "file" - } - }, - "ImageUrl": { - "name": "ImageUrl", - "in": "body", - "required": true, - "x-ms-parameter-location": "method", - "x-ms-client-flatten": true, - "description": "A JSON document with a URL pointing to the image that is to be analyzed.", - "schema": { - "$ref": "#/definitions/ImageUrl" - } + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/train": { + "post": { + "description": "Queue a person group training task, the training task may not be started immediately.", + "operationId": "PersonGroups_Train", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Target person group to be trained.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "202": { + "description": "A successful call returns an empty JSON body. " + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists/{faceListId}": { + "put": { + "description": "Create an empty face list with user-specified faceListId, name and an optional userData. Up to 64 face lists are allowed to exist in one subscription.", + "operationId": "FaceLists_Create", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/json" + ] + }, + "get": { + "description": "Retrieve a face list's information, including faceListId, name, userData and faces in the face list. ", + "operationId": "FaceLists_Get", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns the face list's information.", + "schema": { + "$ref": "#/definitions/GetFaceListResponse" + }, + "examples": { + "application/json": { + "faceListId": "sample_list", + "name": "list1", + "userData": "User-provideddataattachedtothefacelist", + "persistedFaces": [ + { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBD", + "userData": "User-provideddataattachedtotheface" + } + ] + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + }, + "patch": { + "description": "Update information of a face list, including name and userData. ", + "operationId": "FaceLists_Update", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "body", + "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" + } + } + }, + "produces": [ + "application/json" + ] + }, + "delete": { + "description": "Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.", + "operationId": "FaceLists_Delete", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists": { + "get": { + "description": "Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.", + "operationId": "FaceLists_List", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an array of faceList.", + "schema": { + "$ref": "#/definitions/ListFaceListResponse" + }, + "examples": { + "application/json": [ + { + "faceListId": "sample_list", + "name": "list1", + "userData": "User-provideddataattachedtothefacelist" + } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "FaceLists_DeleteFace", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "faceListId of an existing face list. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "persistedFaceId", + "in": "path", + "description": "persistedFaceId of an existing face. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "description": "A successful call returns an empty response body." + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + } + }, + "x-ms-paths": { + "/detect?overload=url": { + "post": { + "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", + "operationId": "Faces_Detect", + "parameters": [ + { + "name": "returnFaceId", + "in": "query", + "description": "Return faceIds of the detected faces or not. The default value is true. ", + "type": "boolean", + "default": "true", + "enum": [ + "false", + "true" + ] + }, + { + "name": "returnFaceLandmarks", + "in": "query", + "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "type": "boolean", + "default": "false", + "enum": [ + "false", + "true" + ] + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "consumes": [ + "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/DetectResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "faceRectangle": { + "width": 78, + "height": 78, + "left": 394, + "top": 54 + }, + "faceLandmarks": { + "pupilLeft": { + "x": 412.7, + "y": 78.4 + }, + "pupilRight": { + "x": 446.8, + "y": 74.2 + }, + "noseTip": { + "x": 437.7, + "y": 92.4 + }, + "mouthLeft": { + "x": 417.8, + "y": 114.4 + }, + "mouthRight": { + "x": 451.3, + "y": 109.3 + }, + "eyebrowLeftOuter": { + "x": 397.9, + "y": 78.5 + }, + "eyebrowLeftInner": { + "x": 425.4, + "y": 70.5 + }, + "eyeLeftOuter": { + "x": 406.7, + "y": 80.6 + }, + "eyeLeftTop": { + "x": 412.2, + "y": 76.2 + }, + "eyeLeftBottom": { + "x": 413, + "y": 80.1 + }, + "eyeLeftInner": { + "x": 418.9, + "y": 78 + }, + "eyebrowRightInner": { + "x": 4.8, + "y": 69.7 + }, + "eyebrowRightOuter": { + "x": 5.5, + "y": 68.5 + }, + "eyeRightInner": { + "x": 441.5, + "y": 75 + }, + "eyeRightTop": { + "x": 446.4, + "y": 71.7 + }, + "eyeRightBottom": { + "x": 447, + "y": 75.3 + }, + "eyeRightOuter": { + "x": 451.7, + "y": 73.4 + }, + "noseRootLeft": { + "x": 428, + "y": 77.1 + }, + "noseRootRight": { + "x": 435.8, + "y": 75.6 + }, + "noseLeftAlarTop": { + "x": 428.3, + "y": 89.7 + }, + "noseRightAlarTop": { + "x": 442.2, + "y": 87 + }, + "noseLeftAlarOutTip": { + "x": 424.3, + "y": 96.4 + }, + "noseRightAlarOutTip": { + "x": 446.6, + "y": 92.5 + }, + "upperLipTop": { + "x": 437.6, + "y": 105.9 + }, + "upperLipBottom": { + "x": 437.6, + "y": 108.2 + }, + "underLipTop": { + "x": 436.8, + "y": 111.4 + }, + "underLipBottom": { + "x": 437.3, + "y": 114.5 + } + }, + "faceAttributes": { + "age": 71, + "gender": "male", + "smile": 0.88, + "facialHair": { + "mustache": 0.8, + "beard": 0.1, + "sideburns": 0.02 + } + }, + "glasses": "sunglasses", + "headPose": { + "roll": 2.1, + "yaw": 3, + "pitch": 0 + }, + "emotion": { + "anger": 0.575, + "contempt": 0, + "disgust": 0.006, + "fear": 0.008, + "happiness": 0.394, + "neutral": 0.013, + "sadness": 0, + "surprise": 0.004 + } } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/detect?overload=stream": { + "post": { + "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", + "operationId": "Faces_DetectInStream", + "parameters": [ + { + "name": "returnFaceId", + "in": "query", + "description": "Return faceIds of the detected faces or not. The default value is true. ", + "type": "boolean", + "default": "true", + "enum": [ + "false", + "true" + ] + }, + { + "name": "returnFaceLandmarks", + "in": "query", + "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "type": "boolean", + "default": "false", + "enum": [ + "false", + "true" + ] + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "consumes": [ + "application/octet-stream" + ], + "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/DetectResponse" + }, + "examples": { + "application/json": [ + { + "faceId": "c5c24a82-6845-4031-9d5d-978df9175426", + "faceRectangle": { + "width": 78, + "height": 78, + "left": 394, + "top": 54 + }, + "faceLandmarks": { + "pupilLeft": { + "x": 412.7, + "y": 78.4 + }, + "pupilRight": { + "x": 446.8, + "y": 74.2 + }, + "noseTip": { + "x": 437.7, + "y": 92.4 + }, + "mouthLeft": { + "x": 417.8, + "y": 114.4 + }, + "mouthRight": { + "x": 451.3, + "y": 109.3 + }, + "eyebrowLeftOuter": { + "x": 397.9, + "y": 78.5 + }, + "eyebrowLeftInner": { + "x": 425.4, + "y": 70.5 + }, + "eyeLeftOuter": { + "x": 406.7, + "y": 80.6 + }, + "eyeLeftTop": { + "x": 412.2, + "y": 76.2 + }, + "eyeLeftBottom": { + "x": 413, + "y": 80.1 + }, + "eyeLeftInner": { + "x": 418.9, + "y": 78 + }, + "eyebrowRightInner": { + "x": 4.8, + "y": 69.7 + }, + "eyebrowRightOuter": { + "x": 5.5, + "y": 68.5 + }, + "eyeRightInner": { + "x": 441.5, + "y": 75 + }, + "eyeRightTop": { + "x": 446.4, + "y": 71.7 + }, + "eyeRightBottom": { + "x": 447, + "y": 75.3 + }, + "eyeRightOuter": { + "x": 451.7, + "y": 73.4 + }, + "noseRootLeft": { + "x": 428, + "y": 77.1 + }, + "noseRootRight": { + "x": 435.8, + "y": 75.6 + }, + "noseLeftAlarTop": { + "x": 428.3, + "y": 89.7 + }, + "noseRightAlarTop": { + "x": 442.2, + "y": 87 + }, + "noseLeftAlarOutTip": { + "x": 424.3, + "y": 96.4 + }, + "noseRightAlarOutTip": { + "x": 446.6, + "y": 92.5 + }, + "upperLipTop": { + "x": 437.6, + "y": 105.9 + }, + "upperLipBottom": { + "x": 437.6, + "y": 108.2 + }, + "underLipTop": { + "x": 436.8, + "y": 111.4 + }, + "underLipBottom": { + "x": 437.3, + "y": 114.5 + } + }, + "faceAttributes": { + "age": 71, + "gender": "male", + "smile": 0.88, + "facialHair": { + "mustache": 0.8, + "beard": 0.1, + "sideburns": 0.02 + } + }, + "glasses": "sunglasses", + "headPose": { + "roll": 2.1, + "yaw": 3, + "pitch": 0 + }, + "emotion": { + "anger": 0.575, + "contempt": 0, + "disgust": 0.006, + "fear": 0.008, + "happiness": 0.394, + "neutral": 0.013, + "sadness": 0, + "surprise": 0.004 + } + } + ] + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/persongroups/{personGroupId}/persons/{personId}/persistedFaces?overload=url": { + "post": { + "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.It returns a persistedFaceId representing the added face and this persistedFaceId will not expire. ", + "operationId": "Persons_AddFace", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Target person that the face is added to.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", + "type": "string" + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns the new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "Persons_AddFaceFromStream", + "parameters": [ + { + "name": "personGroupId", + "in": "path", + "description": "Specifying the person group containing the target person.", + "required": true, + "type": "string" + }, + { + "name": "personId", + "in": "path", + "description": "Target person that the face is added to.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the target face to add for any purpose. The maximum length is 1KB. ", + "type": "string" + }, + { + "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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns the new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/json" + ] + } + }, + "/facelists/{faceListId}/persistedFaces?overload=url": { + "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": "FaceLists_AddFace", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", + "type": "string" + }, + { + "name": "targetFace", + "in": "query", + "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns a new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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": "FaceLists_AddFaceFromStream", + "parameters": [ + { + "name": "faceListId", + "in": "path", + "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "required": true, + "type": "string" + }, + { + "name": "userData", + "in": "query", + "description": "User-specified data about the face list for any purpose. The maximum length is 1KB.", + "type": "string" + }, + { + "name": "targetFace", + "in": "query", + "description": "A face rectangle to specify the target face to be added into the face list, 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": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "consumes": [ + "application/json", + "application/octet-stream" + ], + "responses": { + "200": { + "description": "A successful call returns a new persistedFaceId.", + "examples": { + "application/json": { + "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" + } + } + }, + "default": { + "description": "Error response.", + "schema": { + "$ref": "#/definitions/APIError" + } + } + }, + "produces": [ + "application/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" + } + } + }, + "ImageUrl": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + } + } + }, + "DetectResponse": { + "type": "array", + "items": { + "$ref": "#/definitions/DetectResponseElement" + } + }, + "DetectResponseElement": { + "type": "object", + "required": [ + "faceRectangle" + ], + "description": "", + "properties": { + "faceId": { + "type": "string" + }, + "faceRectangle": { + "$ref": "#/definitions/FaceRectangle" + }, + "faceLandmarks": { + "$ref": "#/definitions/FaceLandmarks" + } + } + }, + "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": "integer", + "format": "int32", + "description": "The horizontal component, in pixels." + }, + "y": { + "type": "integer", + "format": "int32", + "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": "Gender: male or female", + "enum": [ + "male", + "female" + ] + }, + "smile": { + "type": "number", + "description": "Smile intensity, a number between [0,1] ", + "minimum": 0, + "maximum": 1 + }, + "glasses": { + "type": "string", + "description": "Glasses type. Possible values are 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'. ", + "enum": [ + "noGlasses", + "readingGlasses", + "sunglasses", + "swimmingGoggles" + ] + }, + "facialHair": { + "$ref": "#/definitions/FacialHairProperties" + }, + "headPose": { + "$ref": "#/definitions/HeadPoseProperties" + }, + "emotion": { + "$ref": "#/definitions/EmotionProperties" + } + } + }, + "FacialHairProperties": { + "type": "object", + "description": "", + "properties": { + "mustache": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "beard": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "sideburns": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "HeadPoseProperties": { + "type": "object", + "description": "", + "properties": { + "roll": { + "type": "number" + }, + "yaw": { + "type": "number" + }, + "pitch": { + "type": "number" + } + } + }, + "EmotionProperties": { + "type": "object", + "description": "", + "properties": { + "anger": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "contempt": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "disgust": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "fear": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "happiness": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "neutral": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "sadness": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "surprise": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + }, + "FindSimilarRequest": { + "type": "object", + "required": [ + "faceId" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "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" + }, + "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. The number of faceIds is limited to 1000. Parameter faceListId and faceIds should not be provided at the same time.", + "maxLength": 1000, + "items": { + "type": "string" + } + }, + "maxNumOfCandidatesReturned": { + "type": "integer", + "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "default": 20, + "minimum": 1, + "maximum": 1000 + }, + "mode": { + "type": "string", + "description": "Similar face searching mode. It can be \"matchPerson\" or \"matchFace\". It defaults to \"matchPerson\".", + "default": "matchPerson", + "enum": [ + "matchPerson", + "matchFace" + ] + } + } + }, + "FindSimilarResponse": { + "type": "array", + "items": { + "$ref": "#/definitions/FindSimilarResponseElement" + } + }, + "FindSimilarResponseElement": { + "type": "object", + "required": [ + "faceId", + "persistedFaceId" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "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", + "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": { + "type": "number", + "description": "Similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1" + } + } + }, + "GroupRequest": { + "type": "object", + "required": [ + "faceIds" + ], + "description": "", + "properties": { + "faceIds": { + "type": "array", + "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", + "maxLength": 1000, + "items": { + "type": "string" + } + } + } + }, + "GroupResponse": { + "type": "object", + "required": [ + "groups" + ], + "description": "", + "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" + } + } + }, + "messyGroup": { + "type": "array", + "description": "Face ids array of faces that cannot find any similar faces from original faces.", + "items": { + "type": "string" + } + } + } + }, + "IdentifyRequest": { + "type": "object", + "required": [ + "personGroupId", + "faceIds" + ], + "description": "", + "properties": { + "personGroupId": { + "type": "string", + "description": "personGroupId of the target person group, created by PersonGroups.Create" + }, + "faceIds": { + "type": "array", + "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", + "maxLength": 10, + "items": { + "type": "string" + } + }, + "maxNumOfCandidatesReturned": { + "type": "integer", + "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "default": 1, + "minimum": 1, + "maximum": 5 + }, + "confidenceThreshold": { + "type": "number", + "description": "Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).", + "minimum": 0, + "maximum": 1 + } + } + }, + "IdentifyResponse": { + "type": "array", + "items": {} + }, + "IdentifyResponseElement": { + "type": "object", + "required": [ + "faceId", + "candidates" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "description": "faceId of the query face" + }, + "candidates": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/IdentifyResponseCandidatesElement" + } + } + } + }, + "IdentifyResponseCandidatesElement": { + "type": "object", + "required": [ + "personId", + "confidence" + ], + "description": "", + "properties": { + "personId": { + "type": "string", + "description": "Id of candidate" + }, + "confidence": { + "type": "number", + "description": "Confidence level in the candidate person: a float number between 0.0 and 1.0.", + "minimum": 0, + "maximum": 1 + } + } + }, + "VerifyRequest": { + "type": "object", + "required": [ + "faceId", + "personId", + "personGroupId" + ], + "description": "", + "properties": { + "faceId": { + "type": "string", + "description": "faceId the face, comes from Face - Detect" + }, + "personId": { + "type": "string", + "description": "Specify a certain person in a person group. personId is created in Persons.Create." + }, + "personGroupId": { + "type": "string", + "description": "Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create." + } + } + }, + "VerifyResponse": { + "type": "object", + "required": [ + "isIdentifical" + ], + "description": "", + "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": { + "type": "number", + "description": "\"A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. By default, isIdentical is set to True if similarity confidence is greater than or equal to 0.5. This is useful for advanced users to override \"isIdentical\" and fine-tune the result on their own data\"", + "minimum": 0, + "maximum": 1 + } + } + }, + "CreateFaceListRequest": { + "type": "object", + "description": "", + "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 + } + } + }, + "GetFaceListResponse": { + "type": "object", + "required": [ + "faceListId" + ], + "description": "", + "properties": { + "faceListId": { + "type": "string", + "description": "faceListId of the target face list.", + "maxLength": 128 + }, + "name": { + "type": "string", + "description": "Face list's display name.", + "maxLength": 128 + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this face list.", + "maxLength": 16384 + } + } + }, + "ListFaceListResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetFaceListResponse" + } + }, + "CreatePersonGroupRequest": { + "type": "object", + "description": "", + "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 + } + } + }, + "GetPersonGroupResponse": { + "type": "object", + "required": [ + "personGroupId" + ], + "description": "", + "properties": { + "personGroupId": { + "type": "string", + "description": "faceListId of the target face list.", + "maxLength": 128 + }, + "name": { + "type": "string", + "description": "Face list's display name.", + "maxLength": 128 + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this face list.", + "maxLength": 16384 + } + } + }, + "ListPersonGroupResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetPersonGroupResponse" + } + }, + "CreatePersonRequest": { + "type": "object", + "description": "", + "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 + } + } + }, + "CreatePersonResponse": { + "type": "object", + "required": [ + "name" + ], + "description": "", + "properties": { + "personId": { + "type": "string", + "description": "personID of the new created person." + } + } + }, + "GetPersonResponse": { + "type": "object", + "required": [ + "personId" + ], + "description": "", + "properties": { + "personId": { + "type": "string", + "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" + } + }, + "name": { + "type": "string", + "description": "Person's display name." + }, + "userData": { + "type": "string", + "description": "User-provided data attached to this person." + } + } + }, + "ListPersonsResponse": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/GetPersonResponse" + } + }, + "GetPersonFaceResponse": { + "type": "object", + "required": [ + "persistedFacedId" + ], + "description": "", + "properties": { + "persistedFaceId": { + "type": "string", + "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." + } + } + }, + "UpdatePersonFaceDataRequest": { + "type": "object", + "description": "", + "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": "", + "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", + "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)." } + } + } + }, + "parameters": { + "AzureRegion": { + "name": "azureRegion", + "description": "Supported Azure regions for Face Detection endpoints", + "x-ms-parameter-location": "client", + "required": true, + "type": "string", + "in": "path", + "x-ms-skip-url-encoding": true, + "x-ms-enum": { + "name": "AzureRegion", + "modelAsString": true + }, + "enum": [ + "westus", + "westeurope", + "southeastasia", + "eastus2", + "westcentralus" + ] + }, + "SubscriptionKey": { + "name": "Ocp-Apim-Subscription-Key", + "x-ms-client-name": "SubscriptionKey", + "in": "header", + "required": true, + "description": "Subscription key in header", + "type": "string" + }, + "ImageStream": { + "name": "Image", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "description": "An image stream.", + "schema": { + "type": "file" + } + }, + "ImageUrl": { + "name": "ImageUrl", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "x-ms-client-flatten": true, + "description": "A JSON document with a URL pointing to the image that is to be analyzed.", + "schema": { + "$ref": "#/definitions/ImageUrl" + } + } + } } \ No newline at end of file From e46c1ff9538a94c101265867dedb3d8bee5a2404 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Thu, 27 Jul 2017 17:47:09 -0700 Subject: [PATCH 04/13] Fixing issues and adding a readme.md --- .../data-plane/Face/readme.md | 37 +++++++++++++++++++ .../data-plane/Face/v1.0/Face.json | 6 +-- 2 files changed, 40 insertions(+), 3 deletions(-) create mode 100644 specification/cognitiveservices/data-plane/Face/readme.md diff --git a/specification/cognitiveservices/data-plane/Face/readme.md b/specification/cognitiveservices/data-plane/Face/readme.md new file mode 100644 index 000000000000..96405550d56b --- /dev/null +++ b/specification/cognitiveservices/data-plane/Face/readme.md @@ -0,0 +1,37 @@ +# Cognitive Services Face SDK + +> see https://aka.ms/autorest + +Example configuration for generating Face SDK. + +The current release is `release_1_0`. + +``` yaml + +tag: release_1_0 +``` +# Releases + +### Release 1.0 +These settings apply only when `--tag=release_1_0` is specified on the command line. + +``` yaml $(tag) == 'release_1_0' +input-file: v1.0/Face.json + +``` + +## CSharp Settings +These settings apply only when `--csharp` is specified on the command line. +``` yaml $(csharp) +csharp: + namespace: Microsoft.CognitiveServices.Face + +``` +## NodeJS Settings + +These settings apply only when `--csharp` is specified on the command line. +``` yaml $(nodejs) +nodejs: + namespace: Microsoft.CognitiveServices.Face + +``` \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json index 63ea7be72e79..feef5466948a 100644 --- a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json @@ -2363,7 +2363,7 @@ "VerifyResponse": { "type": "object", "required": [ - "isIdentifical" + "isIdentical" ], "description": "", "properties": { @@ -2492,7 +2492,7 @@ "CreatePersonResponse": { "type": "object", "required": [ - "name" + "personId" ], "description": "", "properties": { @@ -2540,7 +2540,7 @@ "GetPersonFaceResponse": { "type": "object", "required": [ - "persistedFacedId" + "persistedFaceId" ], "description": "", "properties": { From 53aff4a5f680c953ddda5e0cf4795f0c9e1aa3d3 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Fri, 28 Jul 2017 10:49:04 -0700 Subject: [PATCH 05/13] Fixing examples by removing decimals. --- .../data-plane/Face/v1.0/Face.json | 188 +++++++++--------- 1 file changed, 94 insertions(+), 94 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json index feef5466948a..7c47171ef603 100644 --- a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json @@ -1236,112 +1236,112 @@ }, "faceLandmarks": { "pupilLeft": { - "x": 412.7, - "y": 78.4 + "x": 412, + "y": 78 }, "pupilRight": { - "x": 446.8, - "y": 74.2 + "x": 446, + "y": 74 }, "noseTip": { - "x": 437.7, - "y": 92.4 + "x": 437, + "y": 92 }, "mouthLeft": { - "x": 417.8, - "y": 114.4 + "x": 417, + "y": 114 }, "mouthRight": { - "x": 451.3, - "y": 109.3 + "x": 451, + "y": 109 }, "eyebrowLeftOuter": { - "x": 397.9, - "y": 78.5 + "x": 397, + "y": 78 }, "eyebrowLeftInner": { - "x": 425.4, - "y": 70.5 + "x": 425, + "y": 70 }, "eyeLeftOuter": { - "x": 406.7, - "y": 80.6 + "x": 406, + "y": 80 }, "eyeLeftTop": { - "x": 412.2, - "y": 76.2 + "x": 412, + "y": 76 }, "eyeLeftBottom": { "x": 413, - "y": 80.1 + "y": 80 }, "eyeLeftInner": { - "x": 418.9, + "x": 418, "y": 78 }, "eyebrowRightInner": { "x": 4.8, - "y": 69.7 + "y": 69 }, "eyebrowRightOuter": { - "x": 5.5, - "y": 68.5 + "x": 5, + "y": 68 }, "eyeRightInner": { - "x": 441.5, + "x": 441, "y": 75 }, "eyeRightTop": { - "x": 446.4, - "y": 71.7 + "x": 446, + "y": 71 }, "eyeRightBottom": { "x": 447, - "y": 75.3 + "y": 75 }, "eyeRightOuter": { - "x": 451.7, - "y": 73.4 + "x": 451, + "y": 73 }, "noseRootLeft": { "x": 428, - "y": 77.1 + "y": 77 }, "noseRootRight": { - "x": 435.8, - "y": 75.6 + "x": 435, + "y": 75 }, "noseLeftAlarTop": { - "x": 428.3, - "y": 89.7 + "x": 428, + "y": 89 }, "noseRightAlarTop": { - "x": 442.2, + "x": 442, "y": 87 }, "noseLeftAlarOutTip": { - "x": 424.3, - "y": 96.4 + "x": 424, + "y": 96 }, "noseRightAlarOutTip": { - "x": 446.6, - "y": 92.5 + "x": 446, + "y": 92 }, "upperLipTop": { - "x": 437.6, - "y": 105.9 + "x": 437, + "y": 105 }, "upperLipBottom": { - "x": 437.6, - "y": 108.2 + "x": 437, + "y": 108 }, "underLipTop": { - "x": 436.8, - "y": 111.4 + "x": 436, + "y": 111 }, "underLipBottom": { - "x": 437.3, - "y": 114.5 + "x": 437, + "y": 114 } }, "faceAttributes": { @@ -1447,112 +1447,112 @@ }, "faceLandmarks": { "pupilLeft": { - "x": 412.7, - "y": 78.4 + "x": 412, + "y": 78 }, "pupilRight": { - "x": 446.8, - "y": 74.2 + "x": 446, + "y": 74 }, "noseTip": { - "x": 437.7, - "y": 92.4 + "x": 437, + "y": 92 }, "mouthLeft": { - "x": 417.8, - "y": 114.4 + "x": 417, + "y": 114 }, "mouthRight": { - "x": 451.3, - "y": 109.3 + "x": 451, + "y": 109 }, "eyebrowLeftOuter": { - "x": 397.9, - "y": 78.5 + "x": 397, + "y": 78 }, "eyebrowLeftInner": { - "x": 425.4, - "y": 70.5 + "x": 425, + "y": 70 }, "eyeLeftOuter": { - "x": 406.7, - "y": 80.6 + "x": 406, + "y": 80 }, "eyeLeftTop": { - "x": 412.2, - "y": 76.2 + "x": 412, + "y": 76 }, "eyeLeftBottom": { "x": 413, - "y": 80.1 + "y": 80 }, "eyeLeftInner": { - "x": 418.9, + "x": 418, "y": 78 }, "eyebrowRightInner": { "x": 4.8, - "y": 69.7 + "y": 69 }, "eyebrowRightOuter": { - "x": 5.5, - "y": 68.5 + "x": 5, + "y": 68 }, "eyeRightInner": { - "x": 441.5, + "x": 441, "y": 75 }, "eyeRightTop": { - "x": 446.4, - "y": 71.7 + "x": 446, + "y": 71 }, "eyeRightBottom": { "x": 447, - "y": 75.3 + "y": 75 }, "eyeRightOuter": { - "x": 451.7, - "y": 73.4 + "x": 451, + "y": 73 }, "noseRootLeft": { "x": 428, - "y": 77.1 + "y": 77 }, "noseRootRight": { - "x": 435.8, - "y": 75.6 + "x": 435, + "y": 75 }, "noseLeftAlarTop": { - "x": 428.3, - "y": 89.7 + "x": 428, + "y": 89 }, "noseRightAlarTop": { - "x": 442.2, + "x": 442, "y": 87 }, "noseLeftAlarOutTip": { - "x": 424.3, - "y": 96.4 + "x": 424, + "y": 96 }, "noseRightAlarOutTip": { - "x": 446.6, - "y": 92.5 + "x": 446, + "y": 92 }, "upperLipTop": { - "x": 437.6, - "y": 105.9 + "x": 437, + "y": 105 }, "upperLipBottom": { - "x": 437.6, - "y": 108.2 + "x": 437, + "y": 108 }, "underLipTop": { - "x": 436.8, - "y": 111.4 + "x": 436, + "y": 111 }, "underLipBottom": { - "x": 437.3, - "y": 114.5 + "x": 437, + "y": 114 } }, "faceAttributes": { From c529bbb9954f9dc25b411c8fcb196838168f9c90 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Fri, 28 Jul 2017 11:19:22 -0700 Subject: [PATCH 06/13] Removing another decimal value --- .../cognitiveservices/data-plane/Face/v1.0/Face.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json index 7c47171ef603..e73d65f988eb 100644 --- a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json @@ -1280,7 +1280,7 @@ "y": 78 }, "eyebrowRightInner": { - "x": 4.8, + "x": 4, "y": 69 }, "eyebrowRightOuter": { @@ -1491,7 +1491,7 @@ "y": 78 }, "eyebrowRightInner": { - "x": 4.8, + "x": 4, "y": 69 }, "eyebrowRightOuter": { From 93cb8ef7398ffdaf29b54e75f0f133416e585dd7 Mon Sep 17 00:00:00 2001 From: Garrett Serack Date: Fri, 28 Jul 2017 11:45:27 -0700 Subject: [PATCH 07/13] Update readme.md --- specification/cognitiveservices/data-plane/Face/readme.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/readme.md b/specification/cognitiveservices/data-plane/Face/readme.md index 96405550d56b..1dbb48f203cd 100644 --- a/specification/cognitiveservices/data-plane/Face/readme.md +++ b/specification/cognitiveservices/data-plane/Face/readme.md @@ -27,11 +27,4 @@ csharp: namespace: Microsoft.CognitiveServices.Face ``` -## NodeJS Settings -These settings apply only when `--csharp` is specified on the command line. -``` yaml $(nodejs) -nodejs: - namespace: Microsoft.CognitiveServices.Face - -``` \ No newline at end of file From 95cac3a2836df48b5bfedf77205ff1b9bb02df4a Mon Sep 17 00:00:00 2001 From: "David Li (COGNITIVE SERVICES)" Date: Tue, 8 Aug 2017 19:42:04 -0700 Subject: [PATCH 08/13] Updating spec based on comments. --- .../data-plane/Face/.gitignore | 2 + .../data-plane/Face/readme.md | 6 +- .../data-plane/Face/v1.0/Face.json | 346 +++++++++--------- 3 files changed, 182 insertions(+), 172 deletions(-) create mode 100644 specification/cognitiveservices/data-plane/Face/.gitignore diff --git a/specification/cognitiveservices/data-plane/Face/.gitignore b/specification/cognitiveservices/data-plane/Face/.gitignore new file mode 100644 index 000000000000..6a52bb523393 --- /dev/null +++ b/specification/cognitiveservices/data-plane/Face/.gitignore @@ -0,0 +1,2 @@ +out/** +log/** \ No newline at end of file diff --git a/specification/cognitiveservices/data-plane/Face/readme.md b/specification/cognitiveservices/data-plane/Face/readme.md index 1dbb48f203cd..b4ffaa6ab146 100644 --- a/specification/cognitiveservices/data-plane/Face/readme.md +++ b/specification/cognitiveservices/data-plane/Face/readme.md @@ -2,7 +2,7 @@ > see https://aka.ms/autorest -Example configuration for generating Face SDK. +Configuration for generating Face SDK. The current release is `release_1_0`. @@ -17,7 +17,7 @@ These settings apply only when `--tag=release_1_0` is specified on the command l ``` yaml $(tag) == 'release_1_0' input-file: v1.0/Face.json - +log-file: logs/log.txt ``` ## CSharp Settings @@ -25,6 +25,6 @@ These settings apply only when `--csharp` is specified on the command line. ``` yaml $(csharp) csharp: namespace: Microsoft.CognitiveServices.Face - + output-folder: out/csharp ``` diff --git a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json index e73d65f988eb..de17b1c3a3a7 100644 --- a/specification/cognitiveservices/data-plane/Face/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/v1.0/Face.json @@ -28,7 +28,7 @@ "/findsimilars": { "post": { "description": "Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.", - "operationId": "Faces_FindSimilar", + "operationId": "Face_FindSimilar", "parameters": [ { "$ref": "#/parameters/SubscriptionKey" @@ -50,7 +50,7 @@ "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/FindSimilarResponse" + "$ref": "#/definitions/SimilarFaceResults" }, "examples": { "application/json": [ @@ -76,7 +76,7 @@ "/group": { "post": { "description": "Divide candidate faces into groups based on face similarity.", - "operationId": "Faces_Group", + "operationId": "Face_Group", "parameters": [ { "$ref": "#/parameters/SubscriptionKey" @@ -135,7 +135,7 @@ "/identify": { "post": { "description": "Identify unknown faces from a person group.", - "operationId": "Faces_Identify", + "operationId": "Face_Identify", "parameters": [ { "$ref": "#/parameters/SubscriptionKey" @@ -157,7 +157,7 @@ "200": { "description": "A successful call returns the identified candidate person(s) for each query face.", "schema": { - "$ref": "#/definitions/IdentifyResponse" + "$ref": "#/definitions/IdentifyResult" }, "examples": { "application/json": [ @@ -197,7 +197,7 @@ "/verify": { "post": { "description": "Verify whether two faces belong to a same person or whether one face belongs to a person.", - "operationId": "Faces_Verify", + "operationId": "Face_Verify", "parameters": [ { "$ref": "#/parameters/SubscriptionKey" @@ -219,7 +219,7 @@ "200": { "description": "A successful call returns the verification result.", "schema": { - "$ref": "#/definitions/VerifyResponse" + "$ref": "#/definitions/VerifyResult" }, "examples": { "application/json": { @@ -243,7 +243,7 @@ "/persongroups/{personGroupId}/persons": { "post": { "description": "Create a new person in a specified person group.", - "operationId": "Persons_Create", + "operationId": "Person_Create", "parameters": [ { "name": "personGroupId", @@ -272,7 +272,7 @@ "200": { "description": "A successful call returns a new personId created.", "schema": { - "$ref": "#/definitions/CreatePersonResponse" + "$ref": "#/definitions/CreatePersonResult" }, "examples": { "application/json": { @@ -293,7 +293,7 @@ }, "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": "Persons_List", + "operationId": "Person_List", "parameters": [ { "name": "personGroupId", @@ -310,7 +310,7 @@ "200": { "description": "A successful call returns an array of person information that belong to the person group.", "schema": { - "$ref": "#/definitions/ListPersonsResponse" + "$ref": "#/definitions/PersonResults" }, "examples": { "application/json": [ @@ -351,7 +351,7 @@ "/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": "Persons_Delete", + "operationId": "Person_Delete", "parameters": [ { "name": "personGroupId", @@ -388,7 +388,7 @@ }, "get": { "description": "Retrieve a person's information, including registered persisted faces, name and userData.", - "operationId": "Persons_Get", + "operationId": "Person_Get", "parameters": [ { "name": "personGroupId", @@ -412,7 +412,7 @@ "200": { "description": "A successful call returns the person's information.", "schema": { - "$ref": "#/definitions/GetPersonResponse" + "$ref": "#/definitions/PersonResult" }, "examples": { "application/json": { @@ -440,7 +440,7 @@ }, "patch": { "description": "Update name or userData of a person.", - "operationId": "Persons_Update", + "operationId": "Person_Update", "parameters": [ { "name": "personGroupId", @@ -491,7 +491,7 @@ "/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": "Persons_DeleteFace", + "operationId": "Person_DeleteFace", "parameters": [ { "name": "personGroupId", @@ -535,7 +535,7 @@ }, "get": { "description": "Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).", - "operationId": "Persons_GetFace", + "operationId": "Person_GetFace", "parameters": [ { "name": "personGroupId", @@ -566,7 +566,7 @@ "200": { "description": "A successful call returns target persisted face's information (persistedFaceId and userData).", "schema": { - "$ref": "#/definitions/GetPersonFaceResponse" + "$ref": "#/definitions/PersonFaceResult" }, "examples": { "application/json": { @@ -588,7 +588,7 @@ }, "patch": { "description": "Update a person persisted face's userData field.", - "operationId": "Persons_UpdateFace", + "operationId": "Person_UpdateFace", "parameters": [ { "name": "personGroupId", @@ -646,14 +646,16 @@ "/persongroups/{personGroupId}": { "put": { "description": "Create a new person group with specified personGroupId, name and user-provided userData.", - "operationId": "PersonGroups_Create", + "operationId": "PersonGroup_Create", "parameters": [ { "name": "personGroupId", "in": "path", - "description": "User-provided personGroupId as a string. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.\n ", + "description": "User-provided personGroupId as a string.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "$ref": "#/parameters/SubscriptionKey" @@ -688,7 +690,7 @@ }, "delete": { "description": "Delete an existing person group. Persisted face images of all people in the person group will also be deleted.", - "operationId": "PersonGroups_Delete", + "operationId": "PersonGroup_Delete", "parameters": [ { "name": "personGroupId", @@ -718,7 +720,7 @@ }, "get": { "description": "Retrieve the information of a person group, including its name and userData.", - "operationId": "PersonGroups_Get", + "operationId": "PersonGroup_Get", "parameters": [ { "name": "personGroupId", @@ -735,7 +737,7 @@ "200": { "description": "A successful call returns the person group's information.", "schema": { - "$ref": "#/definitions/GetPersonGroupResponse" + "$ref": "#/definitions/PersonGroupResult" }, "examples": { "application/json": { @@ -758,7 +760,7 @@ }, "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": "PersonGroups_Update", + "operationId": "PersonGroup_Update", "parameters": [ { "name": "personGroupId", @@ -802,7 +804,7 @@ "/persongroups/{personGroupId}/training": { "get": { "description": "Retrieve the training status of a person group (completed or ongoing).", - "operationId": "PersonGroups_GetTrainingStatus", + "operationId": "PersonGroup_GetTrainingStatus", "parameters": [ { "name": "personGroupId", @@ -845,26 +847,23 @@ "/persongroups": { "get": { "description": "List person groups and their information.", - "operationId": "PersonGroups_List", + "operationId": "PersonGroup_List", "parameters": [ { "name": "start", "in": "query", - "description": "List person groups from the least personGroupId greater than the \"start\". It contains no more than 64 characters. Default is empty. ", + "description": "List person groups from the least personGroupId greater than the \"start\".", "type": "string", - "enum": [ - "" - ] + "maxLength": 64 }, { "name": "top", "in": "query", - "description": "The number of person groups to list, ranging in [1, 1000]. Default is 1000. ", + "description": "The number of person groups to list.", "type": "integer", - "default": "1000", - "enum": [ - "1000" - ] + "minimum": 1, + "maximum": 1000, + "default": 1000 }, { "$ref": "#/parameters/SubscriptionKey" @@ -872,9 +871,9 @@ ], "responses": { "200": { - "description": "A successful call returns an array of person groups and their information (personGroupId, name and userData).", + "description": "A successful call returns an array of person groups and their information.", "schema": { - "$ref": "#/definitions/ListPersonGroupResponse" + "$ref": "#/definitions/PersonGroupResults" }, "examples": { "application/json": [ @@ -906,7 +905,7 @@ "/persongroups/{personGroupId}/train": { "post": { "description": "Queue a person group training task, the training task may not be started immediately.", - "operationId": "PersonGroups_Train", + "operationId": "PersonGroup_Train", "parameters": [ { "name": "personGroupId", @@ -921,7 +920,7 @@ ], "responses": { "202": { - "description": "A successful call returns an empty JSON body. " + "description": "The training task was queued successfully." }, "default": { "description": "Error response.", @@ -937,15 +936,17 @@ }, "/facelists/{faceListId}": { "put": { - "description": "Create an empty face list with user-specified faceListId, name and an optional userData. Up to 64 face lists are allowed to exist in one subscription.", - "operationId": "FaceLists_Create", + "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": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a particular face list.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "$ref": "#/parameters/SubscriptionKey" @@ -979,15 +980,17 @@ ] }, "get": { - "description": "Retrieve a face list's information, including faceListId, name, userData and faces in the face list. ", - "operationId": "FaceLists_Get", + "description": "Retrieve a face list's information.", + "operationId": "FaceList_Get", "parameters": [ { "name": "faceListId", "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a Face List.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "$ref": "#/parameters/SubscriptionKey" @@ -997,7 +1000,7 @@ "200": { "description": "A successful call returns the face list's information.", "schema": { - "$ref": "#/definitions/GetFaceListResponse" + "$ref": "#/definitions/GetFaceListResult" }, "examples": { "application/json": { @@ -1025,15 +1028,17 @@ ] }, "patch": { - "description": "Update information of a face list, including name and userData. ", - "operationId": "FaceLists_Update", + "description": "Update information of a face list. ", + "operationId": "FaceList_Update", "parameters": [ { "name": "faceListId", "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a Face List.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "$ref": "#/parameters/SubscriptionKey" @@ -1068,14 +1073,16 @@ }, "delete": { "description": "Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.", - "operationId": "FaceLists_Delete", + "operationId": "FaceList_Delete", "parameters": [ { "name": "faceListId", "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a Face List.", "required": true, - "type": "string" + "type": "string", + "pattern": "^[a-z0-9-_]+$", + "maxLength": 64 }, { "$ref": "#/parameters/SubscriptionKey" @@ -1100,7 +1107,7 @@ "/facelists": { "get": { "description": "Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.", - "operationId": "FaceLists_List", + "operationId": "FaceList_List", "parameters": [ { "$ref": "#/parameters/SubscriptionKey" @@ -1110,7 +1117,7 @@ "200": { "description": "A successful call returns an array of faceList.", "schema": { - "$ref": "#/definitions/ListFaceListResponse" + "$ref": "#/definitions/FaceListResults" }, "examples": { "application/json": [ @@ -1137,19 +1144,21 @@ "/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": "FaceLists_DeleteFace", + "operationId": "FaceList_DeleteFace", "parameters": [ { "name": "faceListId", "in": "path", - "description": "faceListId of an existing face list. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "faceListId of an existing face list.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "name": "persistedFaceId", "in": "path", - "description": "persistedFaceId of an existing face. Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "persistedFaceId of an existing face. ", "required": true, "type": "string" }, @@ -1178,29 +1187,21 @@ "/detect?overload=url": { "post": { "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", - "operationId": "Faces_Detect", + "operationId": "Face_Detect", "parameters": [ { "name": "returnFaceId", "in": "query", - "description": "Return faceIds of the detected faces or not. The default value is true. ", + "description": "A value indicating whether the operation should return faceIds of detected faces.", "type": "boolean", - "default": "true", - "enum": [ - "false", - "true" - ] + "default": true }, { "name": "returnFaceLandmarks", "in": "query", - "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "description": "A value indicating whether the operation should return landmarks of the detected faces.", "type": "boolean", - "default": "false", - "enum": [ - "false", - "true" - ] + "default": false }, { "name": "returnFaceAttributes", @@ -1222,7 +1223,7 @@ "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/DetectResponse" + "$ref": "#/definitions/DetectionResult" }, "examples": { "application/json": [ @@ -1389,29 +1390,21 @@ "/detect?overload=stream": { "post": { "description": "Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.", - "operationId": "Faces_DetectInStream", + "operationId": "Face_DetectInStream", "parameters": [ { "name": "returnFaceId", "in": "query", - "description": "Return faceIds of the detected faces or not. The default value is true. ", + "description": "A value indicating whether the operation should return faceIds of detected faces.", "type": "boolean", - "default": "true", - "enum": [ - "false", - "true" - ] + "default": true }, { "name": "returnFaceLandmarks", "in": "query", - "description": "Return face landmarks of the detected faces or not. The default value is false. ", + "description": "A value indicating whether the operation should return landmarks of the detected faces.", "type": "boolean", - "default": "false", - "enum": [ - "false", - "true" - ] + "default": false }, { "name": "returnFaceAttributes", @@ -1433,7 +1426,7 @@ "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/DetectResponse" + "$ref": "#/definitions/DetectionResult" }, "examples": { "application/json": [ @@ -1599,8 +1592,8 @@ }, "/persongroups/{personGroupId}/persons/{personId}/persistedFaces?overload=url": { "post": { - "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.It returns a persistedFaceId representing the added face and this persistedFaceId will not expire. ", - "operationId": "Persons_AddFace", + "description": "Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.", + "operationId": "Person_AddFace", "parameters": [ { "name": "personGroupId", @@ -1660,7 +1653,7 @@ "/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": "Persons_AddFaceFromStream", + "operationId": "Person_AddFaceFromStream", "parameters": [ { "name": "personGroupId", @@ -1720,14 +1713,16 @@ "/facelists/{faceListId}/persistedFaces?overload=url": { "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": "FaceLists_AddFace", + "operationId": "FaceList_AddFace", "parameters": [ { "name": "faceListId", "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a Face List.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "name": "userData", @@ -1773,14 +1768,16 @@ "/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": "FaceLists_AddFaceFromStream", + "operationId": "FaceList_AddFaceFromStream", "parameters": [ { "name": "faceListId", "in": "path", - "description": "Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.", + "description": "Id referencing a Face List.", "required": true, - "type": "string" + "type": "string", + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, { "name": "userData", @@ -1857,21 +1854,22 @@ } } }, - "DetectResponse": { + "DetectionResult": { "type": "array", "items": { - "$ref": "#/definitions/DetectResponseElement" + "$ref": "#/definitions/DetectedFace" } }, - "DetectResponseElement": { + "DetectedFace": { "type": "object", "required": [ "faceRectangle" ], - "description": "", + "description": "Detected Face object.", "properties": { "faceId": { - "type": "string" + "type": "string", + "maxLength": 64 }, "faceRectangle": { "$ref": "#/definitions/FaceRectangle" @@ -2065,7 +2063,7 @@ }, "FacialHairProperties": { "type": "object", - "description": "", + "description": "Properties describing facial hair attributes.", "properties": { "mustache": { "type": "number", @@ -2086,7 +2084,7 @@ }, "HeadPoseProperties": { "type": "object", - "description": "", + "description": "Properties indicating head pose of the face.", "properties": { "roll": { "type": "number" @@ -2101,7 +2099,7 @@ }, "EmotionProperties": { "type": "object", - "description": "", + "description": "Properties describing facial emotion.", "properties": { "anger": { "type": "number", @@ -2150,34 +2148,38 @@ "required": [ "faceId" ], - "description": "", + "description": "Request body for find similar operation.", "properties": { "faceId": { "type": "string", - "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" + "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", + "maxLength": 64 }, "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" + "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. The number of faceIds is limited to 1000. Parameter faceListId and faceIds should not be provided at the same time.", - "maxLength": 1000, + "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" + "type": "string", + "maxLength": 64 } }, "maxNumOfCandidatesReturned": { "type": "integer", - "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "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\". It defaults to \"matchPerson\".", + "description": "Similar face searching mode. It can be \"matchPerson\" or \"matchFace\".", "default": "matchPerson", "enum": [ "matchPerson", @@ -2186,23 +2188,24 @@ } } }, - "FindSimilarResponse": { + "SimilarFaceResults": { "type": "array", "items": { - "$ref": "#/definitions/FindSimilarResponseElement" + "$ref": "#/definitions/SimilarFaceResult" } }, - "FindSimilarResponseElement": { + "SimilarFaceResult": { "type": "object", "required": [ "faceId", "persistedFaceId" ], - "description": "", + "description": "Response body for find similar face operation.", "properties": { "faceId": { "type": "string", - "description": "faceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call" + "description": "faceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call", + "maxLength": 64 }, "persistedFaceId": { "type": "string", @@ -2219,14 +2222,15 @@ "required": [ "faceIds" ], - "description": "", + "description": "Request body for group request.", "properties": { "faceIds": { "type": "array", "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", - "maxLength": 1000, + "maxItems": 1000, "items": { - "type": "string" + "type": "string", + "maxLength": 64 } } } @@ -2236,7 +2240,7 @@ "required": [ "groups" ], - "description": "", + "description": "An array of face groups based on face similarity.", "properties": { "groups": { "type": "array", @@ -2263,7 +2267,7 @@ "personGroupId", "faceIds" ], - "description": "", + "description": "Request body for identify face operation.", "properties": { "personGroupId": { "type": "string", @@ -2271,59 +2275,61 @@ }, "faceIds": { "type": "array", - "description": "Array of candidate faceId created by Face - Detect. The maximum is 1000 faces", - "maxLength": 10, + "description": "Array of candidate faceId created by Face - Detect.", + "maxItems": 1000, "items": { "type": "string" } }, "maxNumOfCandidatesReturned": { "type": "integer", - "description": "The number of top similar faces returned. The valid range is [1, 1000].It defaults to 20.", + "description": "The number of top similar faces returned.", "default": 1, "minimum": 1, - "maximum": 5 + "maximum": 1000 }, "confidenceThreshold": { "type": "number", - "description": "Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).", + "description": "Confidence threshold of identification, used to judge whether one face belong to one person.", "minimum": 0, "maximum": 1 } } }, - "IdentifyResponse": { + "IdentifyResult": { "type": "array", - "items": {} + "items": { + "$ref": "#/definitions/IdentifyResultItem" + } }, - "IdentifyResponseElement": { + "IdentifyResultItem": { "type": "object", "required": [ "faceId", "candidates" ], - "description": "", + "description": "Response body for identify face operation.", "properties": { "faceId": { "type": "string", - "description": "faceId of the query face" + "description": "faceId of the query face", + "maxLength": 64 }, "candidates": { "type": "array", - "description": "", "items": { - "$ref": "#/definitions/IdentifyResponseCandidatesElement" + "$ref": "#/definitions/IdentifyResultCandidate" } } } }, - "IdentifyResponseCandidatesElement": { + "IdentifyResultCandidate": { "type": "object", "required": [ "personId", "confidence" ], - "description": "", + "description": "All possible faces that may qualify.", "properties": { "personId": { "type": "string", @@ -2344,11 +2350,12 @@ "personId", "personGroupId" ], - "description": "", + "description": "Request body for verify operation.", "properties": { "faceId": { "type": "string", - "description": "faceId the face, comes from Face - Detect" + "description": "faceId the face, comes from Face - Detect", + "maxLength": 64 }, "personId": { "type": "string", @@ -2360,12 +2367,12 @@ } } }, - "VerifyResponse": { + "VerifyResult": { "type": "object", "required": [ "isIdentical" ], - "description": "", + "description": "Result of the verify operation.", "properties": { "isIdentical": { "type": "boolean", @@ -2381,7 +2388,7 @@ }, "CreateFaceListRequest": { "type": "object", - "description": "", + "description": "Request to create a face list.", "properties": { "name": { "type": "string", @@ -2395,17 +2402,18 @@ } } }, - "GetFaceListResponse": { + "GetFaceListResult": { "type": "object", "required": [ "faceListId" ], - "description": "", + "description": "Result of the GetFaceList operation.", "properties": { "faceListId": { "type": "string", "description": "faceListId of the target face list.", - "maxLength": 128 + "maxLength": 64, + "pattern": "^[a-z0-9-_]+$" }, "name": { "type": "string", @@ -2419,16 +2427,16 @@ } } }, - "ListFaceListResponse": { + "FaceListResults": { "type": "array", - "description": "", + "description": "An array of face list results.", "items": { - "$ref": "#/definitions/GetFaceListResponse" + "$ref": "#/definitions/GetFaceListResult" } }, "CreatePersonGroupRequest": { "type": "object", - "description": "", + "description": "Request to create a person group.", "properties": { "name": { "type": "string", @@ -2442,12 +2450,12 @@ } } }, - "GetPersonGroupResponse": { + "PersonGroupResult": { "type": "object", "required": [ "personGroupId" ], - "description": "", + "description": "Person group object.", "properties": { "personGroupId": { "type": "string", @@ -2466,16 +2474,16 @@ } } }, - "ListPersonGroupResponse": { + "PersonGroupResults": { "type": "array", - "description": "", + "description": "An array of person groups.", "items": { - "$ref": "#/definitions/GetPersonGroupResponse" + "$ref": "#/definitions/PersonGroupResult" } }, "CreatePersonRequest": { "type": "object", - "description": "", + "description": "Request to create a person object.", "properties": { "name": { "type": "string", @@ -2489,12 +2497,12 @@ } } }, - "CreatePersonResponse": { + "CreatePersonResult": { "type": "object", "required": [ "personId" ], - "description": "", + "description": "Result of creating person.", "properties": { "personId": { "type": "string", @@ -2502,12 +2510,12 @@ } } }, - "GetPersonResponse": { + "PersonResult": { "type": "object", "required": [ "personId" ], - "description": "", + "description": "Person object.", "properties": { "personId": { "type": "string", @@ -2530,19 +2538,19 @@ } } }, - "ListPersonsResponse": { + "PersonResults": { "type": "array", - "description": "", + "description": "An array of PersonResults.", "items": { - "$ref": "#/definitions/GetPersonResponse" + "$ref": "#/definitions/PersonResult" } }, - "GetPersonFaceResponse": { + "PersonFaceResult": { "type": "object", "required": [ "persistedFaceId" ], - "description": "", + "description": "PersonFace object.", "properties": { "persistedFaceId": { "type": "string", @@ -2556,7 +2564,7 @@ }, "UpdatePersonFaceDataRequest": { "type": "object", - "description": "", + "description": "Request to update person face data.", "properties": { "userData": { "type": "string", @@ -2570,7 +2578,7 @@ "required": [ "status" ], - "description": "", + "description": "Training status object.", "properties": { "status": { "type": "string", From 3de638b182940786b87053dba7a2c00687664e50 Mon Sep 17 00:00:00 2001 From: "David Li (COGNITIVE SERVICES)" Date: Fri, 11 Aug 2017 11:28:16 -0700 Subject: [PATCH 09/13] Removing .gitignore. --- specification/cognitiveservices/data-plane/Face/.gitignore | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 specification/cognitiveservices/data-plane/Face/.gitignore diff --git a/specification/cognitiveservices/data-plane/Face/.gitignore b/specification/cognitiveservices/data-plane/Face/.gitignore deleted file mode 100644 index 6a52bb523393..000000000000 --- a/specification/cognitiveservices/data-plane/Face/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -out/** -log/** \ No newline at end of file From 16d965056391f2ccdddb078a2612d08ce1fac65a Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Sat, 19 Aug 2017 21:35:56 -0700 Subject: [PATCH 10/13] Changing namespace to include category. --- specification/cognitiveservices/data-plane/Face/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/cognitiveservices/data-plane/Face/readme.md b/specification/cognitiveservices/data-plane/Face/readme.md index b4ffaa6ab146..1a4f1740ab56 100644 --- a/specification/cognitiveservices/data-plane/Face/readme.md +++ b/specification/cognitiveservices/data-plane/Face/readme.md @@ -24,7 +24,7 @@ log-file: logs/log.txt These settings apply only when `--csharp` is specified on the command line. ``` yaml $(csharp) csharp: - namespace: Microsoft.CognitiveServices.Face + namespace: Microsoft.CognitiveServices.Vision.Face output-folder: out/csharp ``` From b0bd08e4060ceba449110d7930c5ee78ddba5c17 Mon Sep 17 00:00:00 2001 From: "David Li (WINDOWS)" Date: Sun, 20 Aug 2017 22:07:03 -0700 Subject: [PATCH 11/13] Adding ComputerVision jsopn --- .../data-plane/ComputerVision/readme.md | 30 + .../ComputerVision/v1.0/ComputerVision.json | 1435 +++++++++++++++++ 2 files changed, 1465 insertions(+) create mode 100644 specification/cognitiveservices/data-plane/ComputerVision/readme.md create mode 100644 specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json diff --git a/specification/cognitiveservices/data-plane/ComputerVision/readme.md b/specification/cognitiveservices/data-plane/ComputerVision/readme.md new file mode 100644 index 000000000000..88c217861cb7 --- /dev/null +++ b/specification/cognitiveservices/data-plane/ComputerVision/readme.md @@ -0,0 +1,30 @@ +# Cognitive Services Computer Vision SDK + +> see https://aka.ms/autorest + +Configuration for generating Computer Vision SDK. + +The current release is `release_1_0`. + +``` yaml + +tag: release_1_0 +``` +# Releases + +### Release 1.0 +These settings apply only when `--tag=release_1_0` is specified on the command line. + +``` yaml $(tag) == 'release_1_0' +input-file: v1.0/ComputerVision.json +log-file: logs/log.txt +``` + +## CSharp Settings +These settings apply only when `--csharp` is specified on the command line. +``` yaml $(csharp) +csharp: + namespace: Microsoft.CognitiveServices.Vision.ComputerVision + output-folder: out/csharp +``` + diff --git a/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json b/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json new file mode 100644 index 000000000000..d6ab789758ed --- /dev/null +++ b/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json @@ -0,0 +1,1435 @@ +{ + "swagger": "2.0", + "info": { + "version": "1.0", + "title": "Computer Vision", + "description": "The Computer Vision API provides state-of-the-art algorithms to process images and return information. For example, it can be used to determine if an image contains mature content, or it can be used to find all the faces in an image. It also has other features like estimating dominant and accent colors, categorizing the content of images, and describing an image with complete English sentences. Additionally, it can also intelligently generate images thumbnails for displaying large images effectively." + }, + "x-ms-parameterized-host": { + "hostTemplate": "{azureRegion}.api.cognitive.microsoft.com", + "parameters": [ + { + "$ref": "#/parameters/AzureRegion" + } + ] + }, + "basePath": "/vision/v1.0", + "schemes": [ + "https" + ], + "paths": { + "/models": { + "get": { + "description": "This operation returns the list of domain-specific models that are supported by the Computer Vision API. Currently, the API only supports one domain-specific model: a celebrity recognizer. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", + "operationId": "List Domain Specific Models", + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/ListModelsResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/analyze?overload=url": { + "post": { + "description": "This operation extracts a rich set of visual features based on the image content. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response.", + "operationId": "Analyze Image", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "visualFeatures", + "in": "query", + "description": "A string indicating what visual feature types to return. Multiple values should be comma-separated. Valid visual feature types include:Categories - categorizes image content according to a taxonomy defined in documentation. Tags - tags the image with a detailed list of words related to the image content. Description - describes the image content with a complete English sentence. Faces - detects if faces are present. If present, generate coordinates, gender and age. ImageType - detects if image is clipart or a line drawing. Color - determines the accent color, dominant color, and whether an image is black&white.Adult - detects if the image is pornographic in nature (depicts nudity or a sex act). Sexually suggestive content is also detected.", + "type": "array", + "required": false, + "collectionFormat": "csv", + "items": { + "type": "string", + "enum": [ + "ImageType", + "Faces", + "Adult", + "Categories", + "Color", + "Tags", + "Description" + ] + } + }, + { + "name": "details", + "in": "query", + "description": "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include:Celebrities - identifies celebrities if detected in the image.", + "type": "string", + "required": false, + "enum": [ + "Celebrities" + ] + }, + { + "name": "language", + "in": "query", + "description": "A string indicating which language to return. The service will return recognition results in specified language. If this parameter is not specified, the default value is "en".Supported languages:en - English, Default.zh - Simplified Chinese.", + "type": "string", + "required": false, + "default": "en", + "enum": [ + "en", + "zh" + ] + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "responses": { + "200": { + "description": "The response include the extracted features in JSON format.Here is the definitions for enumeration typesClipartTypeNon-clipart = 0, ambiguous = 1, normal-clipart = 2, good-clipart = 3.LineDrawingTypeNon-LineDrawing = 0,LineDrawing = 1.", + "schema": { + "$ref": "#/definitions/ImageAnalysis" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/generateThumbnail": { + "post": { + "description": "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image. A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.", + "operationId": "GenerateThumbnail", + "consumes": [ + "application/json" + ], + "produces": [ + "application/octet-stream", + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "width", + "type": "integer", + "in": "query", + "required": true, + "minimum": 1, + "maximum": 1023, + "description": "Width of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." + }, + { + "name": "height", + "type": "integer", + "in": "query", + "required": true, + "minimum": 1, + "maximum": 1023, + "description": "Height of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." + }, + { + "$ref": "#/parameters/ImageUrl" + }, + { + "name": "smartCropping", + "type": "boolean", + "in": "query", + "required": false, + "default": false, + "description": "Boolean flag for enabling smart cropping." + } + ], + "responses": { + "200": { + "schema": { + "type": "file" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/ocr": { + "post": { + "description": "Optical Character Recognition (OCR) detects printed text in an image and extracts the recognized characters into a machine-usable character stream. Upon success, the OCR results will be returned. Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError.", + "operationId": "RecognizePrintedText", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/DetectOrientation" + }, + { + "$ref": "#/parameters/ImageUrl" + }, + { + "$ref": "#/parameters/Language" + } + ], + "responses": { + "200": { + "description": "The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words.textAngleThe angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.orientationOrientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).languageThe BCP-47 language code (user-provided or auto-detected) of the text detected in the image.regionsAn array of objects, where each object represents a region of recognized text. A region consists of multiple lines (e.g. a column of text in a multi-column document).linesAn array of objects, where each object represents a line of recognized text.wordsAn array of objects, where each object represents a recognized word.boundingBoxBounding box of a recognized region, line, or word, depending on the parent object. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.textString value of a recognized word.", + "schema": { + "$ref": "#/definitions/OcrResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/describe": { + "post": { + "description": "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", + "operationId": "DescribeImage", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "maxCandidates", + "in": "query", + "description": "Maximum number of candidate descriptions to be returned. The default is 1.", + "type": "string", + "required": false, + "default": "1" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/ImageDescription" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/tag": { + "post": { + "description": "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag “cello” may be accompanied by the hint “musical instrument”. All tags are in English.", + "operationId": "TagImage", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/TagResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/models/{model}/analyze": { + "post": { + "description": "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API only provides a single domain-specific model: celebrities. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", + "operationId": "Recognize Domain Specific Content", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "model", + "in": "path", + "description": "The domain-specific content to recognize.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/ImageUrl" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/DomainModelResults" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/recognizeText": { + "post": { + "description": "Recognize Text operation. When you use the Recognize Text interface, the response contains a field called “Operation-Location”. The “Operation-Location” field contains the URL that you must use for your Get Handwritten Text Operation Result operation.\r\n
\r\n
\r\nFor the result of a Recognize Handwritten Text operation to be available, it requires an amount of time that depends on the length of the text. So, you may need to wait before using this Get Handwritten Text Operation Result interface. The time you need to wait may be up to a number of seconds.\r\n
\r\n
\r\nNote: this technology is currently in preview and is only available for English text.", + "operationId": "RecognizeText", + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageUrl" + }, + { + "$ref": "#/parameters/HandwritingBoolean" + } + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "202": { + "description": "The service has accepted the request and will start processing later.\r\n
\r\nIt will return Accepted immediately and include an “Operation-Location” header. Client side should further query the operation status using the URL specified in this header. The operation ID will expire in 48 hours.\r\n
\r\n\r\n \r\n \r\n \r\n \r\n \r\n
Operation-LocationClient side should use this URL to query operation status/result.
Example: https://cognitiveservice/vision/v1.0/textOperations/49a36324-fc4b-4387-aa06-090cfbf0064f\r\n.
", + "headers": { + "Operation-Location": { + "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ", + "type": "string" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/textOperations/{operationId}": { + "get": { + "description": "This interface is used for getting text operation result. The URL to this interface should be retrieved from “Operation-Location” field returned from Recognize Text interface.", + "operationId": "GetTextOperationResult", + "parameters": [ + { + "name": "operationId", + "in": "path", + "description": "Id of the text operation returned in the response of the Recognize Handwritten Text interface.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/SubscriptionKey" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Returns the operation status. Possible values of \"status\" field are:\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\t \r\n\t \r\n\t \r\n
Status CodeDescription
Not startedThe text recognition process has not started.
RunningThe text recognition is being processed.
FailedThe text recognition process failed.
SucceededThe text recognition process succeeded.
\r\n\r\n\r\nIf the status is \"Succeeded\", the response JSON will include the text recognition result. The result is organized in the hierarchy of Line/Word/Text. Result fields include lines, words, bounding box and text:\r\n
\r\n
Lines\r\n
\r\nAn array of objects, where each object represents a line of recognized text.\r\n
Words\r\n
\r\nAn array of objects, where each object represents a recognized word.\r\n
BoundingBox\r\n
\r\nBounding box of a recognized region, line, or word, depending on the parent object. The eight integers represent the four points (x-coordinate, y-coordinate) of the detected rectangle from the left-top corner and clockwise. \r\n
Text\r\n
\r\nString value of a recognized word/line.\r\n
", + "schema": { + "$ref": "#/definitions/TextOperationResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + } + }, + "x-ms-paths": { + "/analyze?overload=stream": { + "post": { + "description": "This operation extracts a rich set of visual features based on the image content. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong. ", + "operationId": "Analyze Image In Stream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "visualFeatures", + "in": "query", + "description": "A string indicating what visual feature types to return. Multiple values should be comma-separated. Valid visual feature types include:Categories - categorizes image content according to a taxonomy defined in documentation. Tags - tags the image with a detailed list of words related to the image content. Description - describes the image content with a complete English sentence. Faces - detects if faces are present. If present, generate coordinates, gender and age. ImageType - detects if image is clipart or a line drawing. Color - determines the accent color, dominant color, and whether an image is black&white.Adult - detects if the image is pornographic in nature (depicts nudity or a sex act). Sexually suggestive content is also detected.", + "type": "array", + "required": false, + "collectionFormat": "csv", + "items": { + "type": "string", + "enum": [ + "ImageType", + "Faces", + "Adult", + "Categories", + "Color", + "Tags", + "Description" + ] + } + }, + { + "name": "details", + "in": "query", + "description": "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include:Celebrities - identifies celebrities if detected in the image.", + "type": "string", + "required": false, + "enum": [ + "Celebrities" + ] + }, + { + "name": "language", + "in": "query", + "description": "A string indicating which language to return. The service will return recognition results in specified language. If this parameter is not specified, the default value is "en".Supported languages:en - English, Default.zh - Simplified Chinese.", + "type": "string", + "required": false, + "default": "en", + "enum": [ + "en", + "zh" + ] + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "responses": { + "200": { + "description": "The response include the extracted features in JSON format. Here is the definitions for enumeration types clipart = 0, ambiguous = 1, normal-clipart = 2, good-clipart = 3. Non-LineDrawing = 0,LineDrawing = 1.", + "schema": { + "$ref": "#/definitions/ImageAnalysis" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/generateThumbnail?overload=stream": { + "post": { + "description": "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image. A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.", + "operationId": "GenerateThumbnailFromStream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/octet-stream", + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "width", + "type": "integer", + "in": "query", + "required": true, + "minimum": 1, + "maximum": 1023, + "description": "Width of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." + }, + { + "name": "height", + "type": "integer", + "in": "query", + "required": true, + "minimum": 1, + "maximum": 1023, + "description": "Height of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." + }, + { + "$ref": "#/parameters/ImageStream" + }, + { + "name": "smartCropping", + "type": "boolean", + "in": "query", + "required": false, + "default": false, + "description": "Boolean flag for enabling smart cropping." + } + ], + "responses": { + "200": { + "schema": { + "type": "file" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/ocr?overload=stream": { + "post": { + "description": "Optical Character Recognition (OCR) detects printed text in an image and extracts the recognized characters into a machine-usable character stream. Upon success, the OCR results will be returned. Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError.", + "operationId": "RecognizePrintedTextInStream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/Language" + }, + { + "$ref": "#/parameters/DetectOrientation" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "responses": { + "200": { + "description": "The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words.textAngleThe angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.orientationOrientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).languageThe BCP-47 language code (user-provided or auto-detected) of the text detected in the image.regionsAn array of objects, where each object represents a region of recognized text. A region consists of multiple lines (e.g. a column of text in a multi-column document).linesAn array of objects, where each object represents a line of recognized text.wordsAn array of objects, where each object represents a recognized word.boundingBoxBounding box of a recognized region, line, or word, depending on the parent object. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.textString value of a recognized word.", + "schema": { + "$ref": "#/definitions/OcrResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/describe?overload=stream": { + "post": { + "description": "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", + "operationId": "DescribeImageInStream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "maxCandidates", + "in": "query", + "description": "Maximum number of candidate descriptions to be returned. The default is 1.", + "type": "string", + "required": false, + "default": "1" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/ImageDescription" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/tag?overload=stream": { + "post": { + "description": "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag “cello” may be accompanied by the hint “musical instrument”. All tags are in English.", + "operationId": "TagImageInStream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/TagResult" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/models/{model}/analyze?overload=stream": { + "post": { + "description": "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API only provides a single domain-specific model: celebrities. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", + "operationId": "Recognize Domain Specific Content In Stream", + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "name": "model", + "in": "path", + "description": "The domain-specific content to recognize.", + "required": true, + "type": "string" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "responses": { + "200": { + "schema": { + "$ref": "#/definitions/DomainModelResults" + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + }, + "/recognizeText?overload=stream": { + "post": { + "description": "Recognize Text operation. When you use the Recognize Text interface, the response contains a field called “Operation-Location”. The “Operation-Location” field contains the URL that you must use for your Get Handwritten Text Operation Result operation.\r\n
\r\n
\r\nFor the result of a Recognize Handwritten Text operation to be available, it requires an amount of time that depends on the length of the text. So, you may need to wait before using this Get Handwritten Text Operation Result interface. The time you need to wait may be up to a number of seconds.\r\n
\r\n
\r\nNote: this technology is currently in preview and is only available for English text.", + "operationId": "RecognizeTextInStream", + "parameters": [ + { + "$ref": "#/parameters/HandwritingBoolean" + }, + { + "$ref": "#/parameters/SubscriptionKey" + }, + { + "$ref": "#/parameters/ImageStream" + } + ], + "consumes": [ + "application/octet-stream" + ], + "produces": [ + "application/json" + ], + "responses": { + "202": { + "description": "The service has accepted the request and will start processing later.\r\n
\r\nIt will return Accepted immediately and include an “Operation-Location” header. Client side should further query the operation status using the URL specified in this header. The operation ID will expire in 48 hours.\r\n
\r\n\r\n \r\n \r\n \r\n \r\n \r\n
Operation-LocationClient side should use this URL to query operation status/result.
Example: https://cognitiveservice/vision/v1.0/textOperations/49a36324-fc4b-4387-aa06-090cfbf0064f\r\n.
", + "headers": { + "Operation-Location": { + "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ", + "type": "string" + } + } + }, + "default": { + "schema": { + "$ref": "#/definitions/ComputerVisionError" + } + } + } + } + } + }, + "definitions": { + "TextOperationResult": { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "", + "enum": [ + "Not Started", + "Running", + "Failed", + "Succeeded" + ], + "x-ms-enum": { + "name": "TextOperationStatusCodes", + "modelAsString": false + }, + "x-nullable": false + }, + "recognitionResult": { + "$ref": "#/definitions/RecognitionResult" + } + } + }, + "RecognitionResult": { + "type": "object", + "properties": { + "lines": { + "type": "array", + "items": { + "$ref": "#/definitions/Line" + } + } + } + }, + "Line": { + "type": "object", + "properties": { + "boundingBox": { + "$ref": "#/definitions/BoundingBox" + }, + "text": { + "type": "string" + }, + "words": { + "type": "array", + "items": { + "$ref": "#/definitions/Word" + } + } + } + }, + "Word": { + "type": "object", + "properties": { + "boundingBox": { + "$ref": "#/definitions/BoundingBox" + }, + "text": { + "type": "string" + } + } + }, + "BoundingBox": { + "type": "array", + "items": { + "type": "integer", + "x-nullable": false + } + }, + "ImageAnalysis": { + "type": "object", + "description": "", + "properties": { + "categories": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/Category" + } + }, + "adult": { + "description": "", + "$ref": "#/definitions/AdultInfo" + }, + "color": { + "description": "", + "$ref": "#/definitions/ColorInfo" + }, + "imageType": { + "description": "", + "$ref": "#/definitions/ImageType" + }, + "tags": { + "type": "array", + "description": "A list of tags with confidence level.", + "items": { + "$ref": "#/definitions/ImageTag" + } + }, + "description": { + "description": "", + "$ref": "#/definitions/ImageDescriptionDetails" + }, + "faces": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/FaceDescription" + } + }, + "requestId": { + "type": "string", + "description": "" + }, + "metadata": { + "description": "Image metadata", + "$ref": "#/definitions/ImageMetadata" + } + } + }, + "ImageUrl": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + } + } + }, + "OcrResult": { + "type": "object", + "properties": { + "language": { + "type": "string", + "description": "The BCP-47 language code (user-provided or auto-detected) of the text detected in the image.", + "enum": [ + "unk", + "zh-Hans", + "zh-Hant", + "cs", + "da", + "nl", + "en", + "fi", + "fr", + "de", + "el", + "hu", + "it", + "ja", + "ko", + "nb", + "pl", + "pt", + "ru", + "es", + "sv", + "tr" + ] + }, + "textAngle": { + "type": "number", + "format": "double", + "description": "The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly." + }, + "orientation": { + "type": "string", + "description": "Orientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property)." + }, + "regions": { + "type": "array", + "description": "An array of objects, where each object represents a region of recognized text.", + "items": { + "$ref": "#/definitions/OcrRegion" + } + } + } + }, + "OcrRegion": { + "type": "object", + "description": "A region consists of multiple lines (e.g. a column of text in a multi-column document).", + "properties": { + "boundingBox": { + "type": "string", + "description": "Bounding box of a recognized region. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." + }, + "lines": { + "type": "array", + "items": { + "$ref": "#/definitions/OcrLine" + } + } + } + }, + "OcrLine": { + "type": "object", + "description": "", + "properties": { + "boundingBox": { + "type": "string", + "description": "Bounding box of a recognized line. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." + }, + "words": { + "type": "array", + "description": "An array of objects, where each object represents a recognized word.", + "items": { + "$ref": "#/definitions/OcrWord" + } + } + } + }, + "OcrWord": { + "type": "object", + "description": "Information on a recognized word.", + "properties": { + "boundingBox": { + "type": "string", + "description": "Bounding box of a recognized word. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." + }, + "text": { + "type": "string", + "description": "String value of a recognized word." + } + } + }, + "ListModelsResult": { + "type": "object", + "description": "", + "properties": { + "models": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/ModelDescription" + } + } + } + }, + "ModelDescription": { + "type": "object", + "description": "", + "properties": { + "name": { + "type": "string" + }, + "categories": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "DomainModelResults": { + "type": "object", + "description": "", + "properties": { + "result": { + "description": "", + "x-ms-client-flatten": true, + "$ref": "#/definitions/DomainModelResult" + }, + "requestId": { + "type": "string", + "description": "" + }, + "metadata": { + "description": "Image metadata", + "$ref": "#/definitions/ImageMetadata" + } + } + }, + "DomainModelResult": { + "type": "object", + "properties": { + "celebrities": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/CelebritiesModel" + } + } + } + }, + "ImageDescription": { + "type": "object", + "description": "A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.", + "properties": { + "description": { + "description": "", + "x-ms-client-flatten": true, + "$ref": "#/definitions/ImageDescriptionDetails" + } + } + }, + "TagResult": { + "type": "object", + "description": "The results of a image tag operation, including any tags and image metadata.", + "properties": { + "tags": { + "type": "array", + "description": "A list of tags with confidence level.", + "items": { + "$ref": "#/definitions/ImageTag" + } + }, + "requestId": { + "type": "string", + "description": "" + }, + "metadata": { + "description": "Image metadata", + "$ref": "#/definitions/ImageMetadata" + } + } + }, + "ImageDescriptionDetails": { + "type": "object", + "description": "A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.", + "properties": { + "tags": { + "type": "array", + "description": "A collection of image tags.", + "items": { + "type": "string" + } + }, + "captions": { + "type": "array", + "description": "A list of captions, sorted by confidence level.", + "items": { + "$ref": "#/definitions/ImageCaption" + } + }, + "requestId": { + "type": "string", + "description": "" + }, + "metadata": { + "description": "Image metadata", + "$ref": "#/definitions/ImageMetadata" + } + } + }, + "ImageCaption": { + "type": "object", + "description": "An image caption, i.e. a brief description of what the image depicts.", + "properties": { + "text": { + "type": "string", + "description": "The text of the caption" + }, + "confidence": { + "type": "number", + "format": "double", + "description": "The level of confidence the service has in the caption" + } + } + }, + "ImageTag": { + "type": "object", + "description": "An image caption, i.e. a brief description of what the image depicts.", + "properties": { + "name": { + "type": "string", + "description": "The tag value" + }, + "confidence": { + "type": "number", + "format": "double", + "description": "The level of confidence the service has in the caption" + } + } + }, + "ImageMetadata": { + "type": "object", + "description": "Image metadata", + "properties": { + "width": { + "type": "integer", + "format": "int32", + "description": "Image width" + }, + "height": { + "type": "integer", + "format": "int32", + "description": "Image height" + }, + "format": { + "type": "string", + "description": "Image format" + } + } + }, + "CelebritiesModel": { + "type": "object", + "description": "", + "properties": { + "name": { + "type": "string", + "description": "" + }, + "confidence": { + "type": "number", + "format": "double", + "description": "" + }, + "faceRectangle": { + "$ref": "#/definitions/FaceRectangle" + } + } + }, + "FaceRectangle": { + "type": "object", + "description": "", + "properties": { + "left": { + "type": "integer", + "description": "" + }, + "right": { + "type": "integer", + "description": "" + }, + "width": { + "type": "integer", + "description": "" + }, + "height": { + "type": "integer", + "description": "" + } + } + }, + "FaceDescription": { + "type": "object", + "description": "", + "properties": { + "age": { + "type": "integer", + "description": "" + }, + "gender": { + "type": "string", + "description": "", + "enum": [ + "Male", + "Female" + ] + }, + "faceRectangle": { + "$ref": "#/definitions/FaceRectangle" + } + } + }, + "ImageType": { + "type": "object", + "description": "", + "properties": { + "clipArtType": { + "type": "integer", + "description": "" + }, + "lineDrawingType": { + "type": "integer", + "description": "" + } + } + }, + "ColorInfo": { + "type": "object", + "description": "", + "properties": { + "dominantColorForeground": { + "type": "string", + "description": "" + }, + "dominantColorBackground": { + "type": "string", + "description": "" + }, + "dominantColors": { + "type": "array", + "items": { + "type": "string", + "description": "" + } + }, + "accentColor": { + "type": "string", + "description": "" + }, + "isBWImg": { + "type": "boolean", + "description": "" + } + } + }, + "AdultInfo": { + "type": "object", + "description": "", + "properties": { + "isAdultContent": { + "type": "boolean", + "description": "" + }, + "isRacyContent": { + "type": "boolean", + "description": "" + }, + "adultScore": { + "type": "number", + "format": "double", + "description": "" + }, + "racyScore": { + "type": "number", + "format": "double", + "description": "" + } + } + }, + "Category": { + "type": "object", + "description": "", + "properties": { + "name": { + "type": "string", + "description": "" + }, + "score": { + "type": "number", + "format": "double", + "description": "" + }, + "detail": { + "type": "object", + "description": "", + "$ref": "#/definitions/CategoryDetail" + } + } + }, + "CategoryDetail": { + "type": "object", + "description": "", + "properties": { + "celebrities": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/CelebritiesModel" + } + } + } + }, + "ComputerVisionError": { + "type": "object", + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "type": "string", + "description": "The error code.", + "enum": [ + "InvalidImageUrl", + "InvalidImageFormat", + "InvalidImageSize", + "NotSupportedVisualFeature", + "NotSupportedImage", + "InvalidDetails", + "NotSupportedLanguage", + "BadArgument", + "FailedToProcess", + "Timeout", + "InternalServerError", + "Unspecified", + "StorageException" + ], + "x-ms-enum": { + "name": "ComputerVisionErrorCodes", + "modelAsString": false + } + }, + "message": { + "type": "string", + "description": "A message explaining the error reported by the service." + }, + "requestId": { + "type": "string", + "description": "A unique request identifier." + } + } + } + }, + "parameters": { + "AzureRegion": { + "name": "azureRegion", + "description": "Supported Azure regions for Computer Vision endpoints", + "x-ms-parameter-location": "client", + "required": true, + "type": "string", + "in": "path", + "x-ms-skip-url-encoding": true, + "x-ms-enum": { + "name": "AzureRegion", + "modelAsString": true + }, + "enum": [ + "westus", + "westeurope", + "southeastasia", + "eastus2", + "westcentralus" + ] + }, + "SubscriptionKey": { + "name": "Ocp-Apim-Subscription-Key", + "x-ms-client-name": "SubscriptionKey", + "in": "header", + "required": true, + "description": "Subscription key in header", + "type": "string" + }, + "Language": { + "name": "language", + "in": "query", + "description": "The BCP-47 language code of the text to be detected in the image.The default value is "unk", then the service will auto detect the language of the text in the image. Supported languages:
    unk (AutoDetect) zh-Hans (ChineseSimplified) zh-Hant (ChineseTraditional) cs (Czech) da (Danish) nl (Dutch) en (English) fi (Finnish) fr (French) de (German) el (Greek) hu (Hungarian) it (Italian) Ja (Japanese) ko (Korean) nb (Norwegian) pl (Polish) pt (Portuguese, ru (Russian) es (Spanish) sv (Swedish) tr (Turkish) ", + "type": "string", + "required": false, + "x-ms-parameter-location": "method", + "default": "unk", + "enum": [ + "unk", + "zh-Hans", + "zh-Hant", + "cs", + "da", + "nl", + "en", + "fi", + "fr", + "de", + "el", + "hu", + "it", + "ja", + "ko", + "nb", + "pl", + "pt", + "ru", + "es", + "sv", + "tr" + ] + }, + "DetectOrientation": { + "name": "detectOrientation", + "in": "query", + "description": "Whether detect the text orientation in the image. With detectOrientation=true the OCR service tries to detect the image orientation and correct it before further processing (e.g. if it's upside-down). ", + "required": true, + "x-ms-parameter-location": "method", + "type": "boolean", + "default": true + }, + "ImageStream": { + "name": "Image", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "description": "An image stream.", + "schema": { + "type": "file" + } + }, + "ImageUrl": { + "name": "ImageUrl", + "in": "body", + "required": true, + "x-ms-parameter-location": "method", + "x-ms-client-flatten": true, + "description": "A JSON document with a URL pointing to the image that is to be analyzed.", + "schema": { + "$ref": "#/definitions/ImageUrl" + } + }, + "HandwritingBoolean": { + "name": "detectHandwriting", + "in": "query", + "description": "If “true” is specified, handwriting recognition is performed. If this parameter is set to “false” or is not specified, printed text recognition is performed.", + "required": false, + "x-ms-parameter-location": "method", + "type": "boolean", + "default": "false", + "enum": [ + "true", + "false" + ] + } + } +} \ No newline at end of file From cef9045bed15674303b0d14013c3e159b6b76035 Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 26 Aug 2019 17:03:35 +0800 Subject: [PATCH 12/13] Fixing CheckDomainAvailability path --- .../stable/2017-04-18/cognitiveservices.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/stable/2017-04-18/cognitiveservices.json b/specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/stable/2017-04-18/cognitiveservices.json index de9845f17678..8dce807da01d 100644 --- a/specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/stable/2017-04-18/cognitiveservices.json +++ b/specification/cognitiveservices/resource-manager/Microsoft.CognitiveServices/stable/2017-04-18/cognitiveservices.json @@ -676,7 +676,7 @@ } } }, - "/providers/Microsoft.CognitiveServices/checkDomainAvailability": { + "/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/checkDomainAvailability": { "post": { "tags": [ "CognitiveServicesAccounts" @@ -689,6 +689,9 @@ } }, "parameters": [ + { + "$ref": "#/parameters/subscriptionIdParameter" + }, { "$ref": "#/parameters/apiVersionParameter" }, From 111d1bc1666fe89cebb960135cf2f5336bbcb35a Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 26 Aug 2019 17:05:32 +0800 Subject: [PATCH 13/13] Removed rogue file --- .../ComputerVision/v1.0/ComputerVision.json | 1435 ----------------- 1 file changed, 1435 deletions(-) delete mode 100644 specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json diff --git a/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json b/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json deleted file mode 100644 index d6ab789758ed..000000000000 --- a/specification/cognitiveservices/data-plane/ComputerVision/v1.0/ComputerVision.json +++ /dev/null @@ -1,1435 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0", - "title": "Computer Vision", - "description": "The Computer Vision API provides state-of-the-art algorithms to process images and return information. For example, it can be used to determine if an image contains mature content, or it can be used to find all the faces in an image. It also has other features like estimating dominant and accent colors, categorizing the content of images, and describing an image with complete English sentences. Additionally, it can also intelligently generate images thumbnails for displaying large images effectively." - }, - "x-ms-parameterized-host": { - "hostTemplate": "{azureRegion}.api.cognitive.microsoft.com", - "parameters": [ - { - "$ref": "#/parameters/AzureRegion" - } - ] - }, - "basePath": "/vision/v1.0", - "schemes": [ - "https" - ], - "paths": { - "/models": { - "get": { - "description": "This operation returns the list of domain-specific models that are supported by the Computer Vision API. Currently, the API only supports one domain-specific model: a celebrity recognizer. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", - "operationId": "List Domain Specific Models", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/ListModelsResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/analyze?overload=url": { - "post": { - "description": "This operation extracts a rich set of visual features based on the image content. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response.", - "operationId": "Analyze Image", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "visualFeatures", - "in": "query", - "description": "A string indicating what visual feature types to return. Multiple values should be comma-separated. Valid visual feature types include:Categories - categorizes image content according to a taxonomy defined in documentation. Tags - tags the image with a detailed list of words related to the image content. Description - describes the image content with a complete English sentence. Faces - detects if faces are present. If present, generate coordinates, gender and age. ImageType - detects if image is clipart or a line drawing. Color - determines the accent color, dominant color, and whether an image is black&white.Adult - detects if the image is pornographic in nature (depicts nudity or a sex act). Sexually suggestive content is also detected.", - "type": "array", - "required": false, - "collectionFormat": "csv", - "items": { - "type": "string", - "enum": [ - "ImageType", - "Faces", - "Adult", - "Categories", - "Color", - "Tags", - "Description" - ] - } - }, - { - "name": "details", - "in": "query", - "description": "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include:Celebrities - identifies celebrities if detected in the image.", - "type": "string", - "required": false, - "enum": [ - "Celebrities" - ] - }, - { - "name": "language", - "in": "query", - "description": "A string indicating which language to return. The service will return recognition results in specified language. If this parameter is not specified, the default value is "en".Supported languages:en - English, Default.zh - Simplified Chinese.", - "type": "string", - "required": false, - "default": "en", - "enum": [ - "en", - "zh" - ] - }, - { - "$ref": "#/parameters/ImageUrl" - } - ], - "responses": { - "200": { - "description": "The response include the extracted features in JSON format.Here is the definitions for enumeration typesClipartTypeNon-clipart = 0, ambiguous = 1, normal-clipart = 2, good-clipart = 3.LineDrawingTypeNon-LineDrawing = 0,LineDrawing = 1.", - "schema": { - "$ref": "#/definitions/ImageAnalysis" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/generateThumbnail": { - "post": { - "description": "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image. A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.", - "operationId": "GenerateThumbnail", - "consumes": [ - "application/json" - ], - "produces": [ - "application/octet-stream", - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "width", - "type": "integer", - "in": "query", - "required": true, - "minimum": 1, - "maximum": 1023, - "description": "Width of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." - }, - { - "name": "height", - "type": "integer", - "in": "query", - "required": true, - "minimum": 1, - "maximum": 1023, - "description": "Height of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." - }, - { - "$ref": "#/parameters/ImageUrl" - }, - { - "name": "smartCropping", - "type": "boolean", - "in": "query", - "required": false, - "default": false, - "description": "Boolean flag for enabling smart cropping." - } - ], - "responses": { - "200": { - "schema": { - "type": "file" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/ocr": { - "post": { - "description": "Optical Character Recognition (OCR) detects printed text in an image and extracts the recognized characters into a machine-usable character stream. Upon success, the OCR results will be returned. Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError.", - "operationId": "RecognizePrintedText", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/DetectOrientation" - }, - { - "$ref": "#/parameters/ImageUrl" - }, - { - "$ref": "#/parameters/Language" - } - ], - "responses": { - "200": { - "description": "The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words.textAngleThe angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.orientationOrientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).languageThe BCP-47 language code (user-provided or auto-detected) of the text detected in the image.regionsAn array of objects, where each object represents a region of recognized text. A region consists of multiple lines (e.g. a column of text in a multi-column document).linesAn array of objects, where each object represents a line of recognized text.wordsAn array of objects, where each object represents a recognized word.boundingBoxBounding box of a recognized region, line, or word, depending on the parent object. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.textString value of a recognized word.", - "schema": { - "$ref": "#/definitions/OcrResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/describe": { - "post": { - "description": "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", - "operationId": "DescribeImage", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "maxCandidates", - "in": "query", - "description": "Maximum number of candidate descriptions to be returned. The default is 1.", - "type": "string", - "required": false, - "default": "1" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageUrl" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/ImageDescription" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/tag": { - "post": { - "description": "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag “cello” may be accompanied by the hint “musical instrument”. All tags are in English.", - "operationId": "TagImage", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageUrl" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/TagResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/models/{model}/analyze": { - "post": { - "description": "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API only provides a single domain-specific model: celebrities. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", - "operationId": "Recognize Domain Specific Content", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "model", - "in": "path", - "description": "The domain-specific content to recognize.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/ImageUrl" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/DomainModelResults" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/recognizeText": { - "post": { - "description": "Recognize Text operation. When you use the Recognize Text interface, the response contains a field called “Operation-Location”. The “Operation-Location” field contains the URL that you must use for your Get Handwritten Text Operation Result operation.\r\n
    \r\n
    \r\nFor the result of a Recognize Handwritten Text operation to be available, it requires an amount of time that depends on the length of the text. So, you may need to wait before using this Get Handwritten Text Operation Result interface. The time you need to wait may be up to a number of seconds.\r\n
    \r\n
    \r\nNote: this technology is currently in preview and is only available for English text.", - "operationId": "RecognizeText", - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageUrl" - }, - { - "$ref": "#/parameters/HandwritingBoolean" - } - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "202": { - "description": "The service has accepted the request and will start processing later.\r\n
    \r\nIt will return Accepted immediately and include an “Operation-Location” header. Client side should further query the operation status using the URL specified in this header. The operation ID will expire in 48 hours.\r\n
    \r\n\r\n \r\n \r\n \r\n \r\n \r\n
    Operation-LocationClient side should use this URL to query operation status/result.
    Example: https://cognitiveservice/vision/v1.0/textOperations/49a36324-fc4b-4387-aa06-090cfbf0064f\r\n.
    ", - "headers": { - "Operation-Location": { - "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ", - "type": "string" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/textOperations/{operationId}": { - "get": { - "description": "This interface is used for getting text operation result. The URL to this interface should be retrieved from “Operation-Location” field returned from Recognize Text interface.", - "operationId": "GetTextOperationResult", - "parameters": [ - { - "name": "operationId", - "in": "path", - "description": "Id of the text operation returned in the response of the Recognize Handwritten Text interface.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/SubscriptionKey" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "Returns the operation status. Possible values of \"status\" field are:\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\t \r\n\t \r\n\t \r\n
    Status CodeDescription
    Not startedThe text recognition process has not started.
    RunningThe text recognition is being processed.
    FailedThe text recognition process failed.
    SucceededThe text recognition process succeeded.
    \r\n\r\n\r\nIf the status is \"Succeeded\", the response JSON will include the text recognition result. The result is organized in the hierarchy of Line/Word/Text. Result fields include lines, words, bounding box and text:\r\n
    \r\n
    Lines\r\n
    \r\nAn array of objects, where each object represents a line of recognized text.\r\n
    Words\r\n
    \r\nAn array of objects, where each object represents a recognized word.\r\n
    BoundingBox\r\n
    \r\nBounding box of a recognized region, line, or word, depending on the parent object. The eight integers represent the four points (x-coordinate, y-coordinate) of the detected rectangle from the left-top corner and clockwise. \r\n
    Text\r\n
    \r\nString value of a recognized word/line.\r\n
    ", - "schema": { - "$ref": "#/definitions/TextOperationResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - } - }, - "x-ms-paths": { - "/analyze?overload=stream": { - "post": { - "description": "This operation extracts a rich set of visual features based on the image content. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong. ", - "operationId": "Analyze Image In Stream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "visualFeatures", - "in": "query", - "description": "A string indicating what visual feature types to return. Multiple values should be comma-separated. Valid visual feature types include:Categories - categorizes image content according to a taxonomy defined in documentation. Tags - tags the image with a detailed list of words related to the image content. Description - describes the image content with a complete English sentence. Faces - detects if faces are present. If present, generate coordinates, gender and age. ImageType - detects if image is clipart or a line drawing. Color - determines the accent color, dominant color, and whether an image is black&white.Adult - detects if the image is pornographic in nature (depicts nudity or a sex act). Sexually suggestive content is also detected.", - "type": "array", - "required": false, - "collectionFormat": "csv", - "items": { - "type": "string", - "enum": [ - "ImageType", - "Faces", - "Adult", - "Categories", - "Color", - "Tags", - "Description" - ] - } - }, - { - "name": "details", - "in": "query", - "description": "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include:Celebrities - identifies celebrities if detected in the image.", - "type": "string", - "required": false, - "enum": [ - "Celebrities" - ] - }, - { - "name": "language", - "in": "query", - "description": "A string indicating which language to return. The service will return recognition results in specified language. If this parameter is not specified, the default value is "en".Supported languages:en - English, Default.zh - Simplified Chinese.", - "type": "string", - "required": false, - "default": "en", - "enum": [ - "en", - "zh" - ] - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "responses": { - "200": { - "description": "The response include the extracted features in JSON format. Here is the definitions for enumeration types clipart = 0, ambiguous = 1, normal-clipart = 2, good-clipart = 3. Non-LineDrawing = 0,LineDrawing = 1.", - "schema": { - "$ref": "#/definitions/ImageAnalysis" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/generateThumbnail?overload=stream": { - "post": { - "description": "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image. A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.", - "operationId": "GenerateThumbnailFromStream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/octet-stream", - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "width", - "type": "integer", - "in": "query", - "required": true, - "minimum": 1, - "maximum": 1023, - "description": "Width of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." - }, - { - "name": "height", - "type": "integer", - "in": "query", - "required": true, - "minimum": 1, - "maximum": 1023, - "description": "Height of the thumbnail. It must be between 1 and 1024. Recommended minimum of 50." - }, - { - "$ref": "#/parameters/ImageStream" - }, - { - "name": "smartCropping", - "type": "boolean", - "in": "query", - "required": false, - "default": false, - "description": "Boolean flag for enabling smart cropping." - } - ], - "responses": { - "200": { - "schema": { - "type": "file" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/ocr?overload=stream": { - "post": { - "description": "Optical Character Recognition (OCR) detects printed text in an image and extracts the recognized characters into a machine-usable character stream. Upon success, the OCR results will be returned. Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError.", - "operationId": "RecognizePrintedTextInStream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/Language" - }, - { - "$ref": "#/parameters/DetectOrientation" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "responses": { - "200": { - "description": "The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words.textAngleThe angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.orientationOrientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).languageThe BCP-47 language code (user-provided or auto-detected) of the text detected in the image.regionsAn array of objects, where each object represents a region of recognized text. A region consists of multiple lines (e.g. a column of text in a multi-column document).linesAn array of objects, where each object represents a line of recognized text.wordsAn array of objects, where each object represents a recognized word.boundingBoxBounding box of a recognized region, line, or word, depending on the parent object. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.textString value of a recognized word.", - "schema": { - "$ref": "#/definitions/OcrResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/describe?overload=stream": { - "post": { - "description": "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", - "operationId": "DescribeImageInStream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "maxCandidates", - "in": "query", - "description": "Maximum number of candidate descriptions to be returned. The default is 1.", - "type": "string", - "required": false, - "default": "1" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/ImageDescription" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/tag?overload=stream": { - "post": { - "description": "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag “cello” may be accompanied by the hint “musical instrument”. All tags are in English.", - "operationId": "TagImageInStream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/TagResult" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/models/{model}/analyze?overload=stream": { - "post": { - "description": "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API only provides a single domain-specific model: celebrities. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.", - "operationId": "Recognize Domain Specific Content In Stream", - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "name": "model", - "in": "path", - "description": "The domain-specific content to recognize.", - "required": true, - "type": "string" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "responses": { - "200": { - "schema": { - "$ref": "#/definitions/DomainModelResults" - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - }, - "/recognizeText?overload=stream": { - "post": { - "description": "Recognize Text operation. When you use the Recognize Text interface, the response contains a field called “Operation-Location”. The “Operation-Location” field contains the URL that you must use for your Get Handwritten Text Operation Result operation.\r\n
    \r\n
    \r\nFor the result of a Recognize Handwritten Text operation to be available, it requires an amount of time that depends on the length of the text. So, you may need to wait before using this Get Handwritten Text Operation Result interface. The time you need to wait may be up to a number of seconds.\r\n
    \r\n
    \r\nNote: this technology is currently in preview and is only available for English text.", - "operationId": "RecognizeTextInStream", - "parameters": [ - { - "$ref": "#/parameters/HandwritingBoolean" - }, - { - "$ref": "#/parameters/SubscriptionKey" - }, - { - "$ref": "#/parameters/ImageStream" - } - ], - "consumes": [ - "application/octet-stream" - ], - "produces": [ - "application/json" - ], - "responses": { - "202": { - "description": "The service has accepted the request and will start processing later.\r\n
    \r\nIt will return Accepted immediately and include an “Operation-Location” header. Client side should further query the operation status using the URL specified in this header. The operation ID will expire in 48 hours.\r\n
    \r\n\r\n \r\n \r\n \r\n \r\n \r\n
    Operation-LocationClient side should use this URL to query operation status/result.
    Example: https://cognitiveservice/vision/v1.0/textOperations/49a36324-fc4b-4387-aa06-090cfbf0064f\r\n.
    ", - "headers": { - "Operation-Location": { - "description": "URL to query for status of the operation. The operation ID will expire in 48 hours. ", - "type": "string" - } - } - }, - "default": { - "schema": { - "$ref": "#/definitions/ComputerVisionError" - } - } - } - } - } - }, - "definitions": { - "TextOperationResult": { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "", - "enum": [ - "Not Started", - "Running", - "Failed", - "Succeeded" - ], - "x-ms-enum": { - "name": "TextOperationStatusCodes", - "modelAsString": false - }, - "x-nullable": false - }, - "recognitionResult": { - "$ref": "#/definitions/RecognitionResult" - } - } - }, - "RecognitionResult": { - "type": "object", - "properties": { - "lines": { - "type": "array", - "items": { - "$ref": "#/definitions/Line" - } - } - } - }, - "Line": { - "type": "object", - "properties": { - "boundingBox": { - "$ref": "#/definitions/BoundingBox" - }, - "text": { - "type": "string" - }, - "words": { - "type": "array", - "items": { - "$ref": "#/definitions/Word" - } - } - } - }, - "Word": { - "type": "object", - "properties": { - "boundingBox": { - "$ref": "#/definitions/BoundingBox" - }, - "text": { - "type": "string" - } - } - }, - "BoundingBox": { - "type": "array", - "items": { - "type": "integer", - "x-nullable": false - } - }, - "ImageAnalysis": { - "type": "object", - "description": "", - "properties": { - "categories": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/Category" - } - }, - "adult": { - "description": "", - "$ref": "#/definitions/AdultInfo" - }, - "color": { - "description": "", - "$ref": "#/definitions/ColorInfo" - }, - "imageType": { - "description": "", - "$ref": "#/definitions/ImageType" - }, - "tags": { - "type": "array", - "description": "A list of tags with confidence level.", - "items": { - "$ref": "#/definitions/ImageTag" - } - }, - "description": { - "description": "", - "$ref": "#/definitions/ImageDescriptionDetails" - }, - "faces": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/FaceDescription" - } - }, - "requestId": { - "type": "string", - "description": "" - }, - "metadata": { - "description": "Image metadata", - "$ref": "#/definitions/ImageMetadata" - } - } - }, - "ImageUrl": { - "type": "object", - "required": [ - "url" - ], - "properties": { - "url": { - "type": "string" - } - } - }, - "OcrResult": { - "type": "object", - "properties": { - "language": { - "type": "string", - "description": "The BCP-47 language code (user-provided or auto-detected) of the text detected in the image.", - "enum": [ - "unk", - "zh-Hans", - "zh-Hant", - "cs", - "da", - "nl", - "en", - "fi", - "fr", - "de", - "el", - "hu", - "it", - "ja", - "ko", - "nb", - "pl", - "pt", - "ru", - "es", - "sv", - "tr" - ] - }, - "textAngle": { - "type": "number", - "format": "double", - "description": "The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly." - }, - "orientation": { - "type": "string", - "description": "Orientation of the text recognized in the image. The value (up,down,left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property)." - }, - "regions": { - "type": "array", - "description": "An array of objects, where each object represents a region of recognized text.", - "items": { - "$ref": "#/definitions/OcrRegion" - } - } - } - }, - "OcrRegion": { - "type": "object", - "description": "A region consists of multiple lines (e.g. a column of text in a multi-column document).", - "properties": { - "boundingBox": { - "type": "string", - "description": "Bounding box of a recognized region. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." - }, - "lines": { - "type": "array", - "items": { - "$ref": "#/definitions/OcrLine" - } - } - } - }, - "OcrLine": { - "type": "object", - "description": "", - "properties": { - "boundingBox": { - "type": "string", - "description": "Bounding box of a recognized line. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." - }, - "words": { - "type": "array", - "description": "An array of objects, where each object represents a recognized word.", - "items": { - "$ref": "#/definitions/OcrWord" - } - } - } - }, - "OcrWord": { - "type": "object", - "description": "Information on a recognized word.", - "properties": { - "boundingBox": { - "type": "string", - "description": "Bounding box of a recognized word. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down." - }, - "text": { - "type": "string", - "description": "String value of a recognized word." - } - } - }, - "ListModelsResult": { - "type": "object", - "description": "", - "properties": { - "models": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/ModelDescription" - } - } - } - }, - "ModelDescription": { - "type": "object", - "description": "", - "properties": { - "name": { - "type": "string" - }, - "categories": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "DomainModelResults": { - "type": "object", - "description": "", - "properties": { - "result": { - "description": "", - "x-ms-client-flatten": true, - "$ref": "#/definitions/DomainModelResult" - }, - "requestId": { - "type": "string", - "description": "" - }, - "metadata": { - "description": "Image metadata", - "$ref": "#/definitions/ImageMetadata" - } - } - }, - "DomainModelResult": { - "type": "object", - "properties": { - "celebrities": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/CelebritiesModel" - } - } - } - }, - "ImageDescription": { - "type": "object", - "description": "A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.", - "properties": { - "description": { - "description": "", - "x-ms-client-flatten": true, - "$ref": "#/definitions/ImageDescriptionDetails" - } - } - }, - "TagResult": { - "type": "object", - "description": "The results of a image tag operation, including any tags and image metadata.", - "properties": { - "tags": { - "type": "array", - "description": "A list of tags with confidence level.", - "items": { - "$ref": "#/definitions/ImageTag" - } - }, - "requestId": { - "type": "string", - "description": "" - }, - "metadata": { - "description": "Image metadata", - "$ref": "#/definitions/ImageMetadata" - } - } - }, - "ImageDescriptionDetails": { - "type": "object", - "description": "A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.", - "properties": { - "tags": { - "type": "array", - "description": "A collection of image tags.", - "items": { - "type": "string" - } - }, - "captions": { - "type": "array", - "description": "A list of captions, sorted by confidence level.", - "items": { - "$ref": "#/definitions/ImageCaption" - } - }, - "requestId": { - "type": "string", - "description": "" - }, - "metadata": { - "description": "Image metadata", - "$ref": "#/definitions/ImageMetadata" - } - } - }, - "ImageCaption": { - "type": "object", - "description": "An image caption, i.e. a brief description of what the image depicts.", - "properties": { - "text": { - "type": "string", - "description": "The text of the caption" - }, - "confidence": { - "type": "number", - "format": "double", - "description": "The level of confidence the service has in the caption" - } - } - }, - "ImageTag": { - "type": "object", - "description": "An image caption, i.e. a brief description of what the image depicts.", - "properties": { - "name": { - "type": "string", - "description": "The tag value" - }, - "confidence": { - "type": "number", - "format": "double", - "description": "The level of confidence the service has in the caption" - } - } - }, - "ImageMetadata": { - "type": "object", - "description": "Image metadata", - "properties": { - "width": { - "type": "integer", - "format": "int32", - "description": "Image width" - }, - "height": { - "type": "integer", - "format": "int32", - "description": "Image height" - }, - "format": { - "type": "string", - "description": "Image format" - } - } - }, - "CelebritiesModel": { - "type": "object", - "description": "", - "properties": { - "name": { - "type": "string", - "description": "" - }, - "confidence": { - "type": "number", - "format": "double", - "description": "" - }, - "faceRectangle": { - "$ref": "#/definitions/FaceRectangle" - } - } - }, - "FaceRectangle": { - "type": "object", - "description": "", - "properties": { - "left": { - "type": "integer", - "description": "" - }, - "right": { - "type": "integer", - "description": "" - }, - "width": { - "type": "integer", - "description": "" - }, - "height": { - "type": "integer", - "description": "" - } - } - }, - "FaceDescription": { - "type": "object", - "description": "", - "properties": { - "age": { - "type": "integer", - "description": "" - }, - "gender": { - "type": "string", - "description": "", - "enum": [ - "Male", - "Female" - ] - }, - "faceRectangle": { - "$ref": "#/definitions/FaceRectangle" - } - } - }, - "ImageType": { - "type": "object", - "description": "", - "properties": { - "clipArtType": { - "type": "integer", - "description": "" - }, - "lineDrawingType": { - "type": "integer", - "description": "" - } - } - }, - "ColorInfo": { - "type": "object", - "description": "", - "properties": { - "dominantColorForeground": { - "type": "string", - "description": "" - }, - "dominantColorBackground": { - "type": "string", - "description": "" - }, - "dominantColors": { - "type": "array", - "items": { - "type": "string", - "description": "" - } - }, - "accentColor": { - "type": "string", - "description": "" - }, - "isBWImg": { - "type": "boolean", - "description": "" - } - } - }, - "AdultInfo": { - "type": "object", - "description": "", - "properties": { - "isAdultContent": { - "type": "boolean", - "description": "" - }, - "isRacyContent": { - "type": "boolean", - "description": "" - }, - "adultScore": { - "type": "number", - "format": "double", - "description": "" - }, - "racyScore": { - "type": "number", - "format": "double", - "description": "" - } - } - }, - "Category": { - "type": "object", - "description": "", - "properties": { - "name": { - "type": "string", - "description": "" - }, - "score": { - "type": "number", - "format": "double", - "description": "" - }, - "detail": { - "type": "object", - "description": "", - "$ref": "#/definitions/CategoryDetail" - } - } - }, - "CategoryDetail": { - "type": "object", - "description": "", - "properties": { - "celebrities": { - "type": "array", - "description": "", - "items": { - "$ref": "#/definitions/CelebritiesModel" - } - } - } - }, - "ComputerVisionError": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "string", - "description": "The error code.", - "enum": [ - "InvalidImageUrl", - "InvalidImageFormat", - "InvalidImageSize", - "NotSupportedVisualFeature", - "NotSupportedImage", - "InvalidDetails", - "NotSupportedLanguage", - "BadArgument", - "FailedToProcess", - "Timeout", - "InternalServerError", - "Unspecified", - "StorageException" - ], - "x-ms-enum": { - "name": "ComputerVisionErrorCodes", - "modelAsString": false - } - }, - "message": { - "type": "string", - "description": "A message explaining the error reported by the service." - }, - "requestId": { - "type": "string", - "description": "A unique request identifier." - } - } - } - }, - "parameters": { - "AzureRegion": { - "name": "azureRegion", - "description": "Supported Azure regions for Computer Vision endpoints", - "x-ms-parameter-location": "client", - "required": true, - "type": "string", - "in": "path", - "x-ms-skip-url-encoding": true, - "x-ms-enum": { - "name": "AzureRegion", - "modelAsString": true - }, - "enum": [ - "westus", - "westeurope", - "southeastasia", - "eastus2", - "westcentralus" - ] - }, - "SubscriptionKey": { - "name": "Ocp-Apim-Subscription-Key", - "x-ms-client-name": "SubscriptionKey", - "in": "header", - "required": true, - "description": "Subscription key in header", - "type": "string" - }, - "Language": { - "name": "language", - "in": "query", - "description": "The BCP-47 language code of the text to be detected in the image.The default value is "unk", then the service will auto detect the language of the text in the image. Supported languages:
      unk (AutoDetect) zh-Hans (ChineseSimplified) zh-Hant (ChineseTraditional) cs (Czech) da (Danish) nl (Dutch) en (English) fi (Finnish) fr (French) de (German) el (Greek) hu (Hungarian) it (Italian) Ja (Japanese) ko (Korean) nb (Norwegian) pl (Polish) pt (Portuguese, ru (Russian) es (Spanish) sv (Swedish) tr (Turkish) ", - "type": "string", - "required": false, - "x-ms-parameter-location": "method", - "default": "unk", - "enum": [ - "unk", - "zh-Hans", - "zh-Hant", - "cs", - "da", - "nl", - "en", - "fi", - "fr", - "de", - "el", - "hu", - "it", - "ja", - "ko", - "nb", - "pl", - "pt", - "ru", - "es", - "sv", - "tr" - ] - }, - "DetectOrientation": { - "name": "detectOrientation", - "in": "query", - "description": "Whether detect the text orientation in the image. With detectOrientation=true the OCR service tries to detect the image orientation and correct it before further processing (e.g. if it's upside-down). ", - "required": true, - "x-ms-parameter-location": "method", - "type": "boolean", - "default": true - }, - "ImageStream": { - "name": "Image", - "in": "body", - "required": true, - "x-ms-parameter-location": "method", - "description": "An image stream.", - "schema": { - "type": "file" - } - }, - "ImageUrl": { - "name": "ImageUrl", - "in": "body", - "required": true, - "x-ms-parameter-location": "method", - "x-ms-client-flatten": true, - "description": "A JSON document with a URL pointing to the image that is to be analyzed.", - "schema": { - "$ref": "#/definitions/ImageUrl" - } - }, - "HandwritingBoolean": { - "name": "detectHandwriting", - "in": "query", - "description": "If “true” is specified, handwriting recognition is performed. If this parameter is set to “false” or is not specified, printed text recognition is performed.", - "required": false, - "x-ms-parameter-location": "method", - "type": "boolean", - "default": "false", - "enum": [ - "true", - "false" - ] - } - } -} \ No newline at end of file