openapi-directory/api/azure.com/cognitiveservices-Face.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","info":{"description":"An API for face detection, verification, and identification.","title":"Face Client","version":"1.0","x-apisguru-categories":["cloud"],"x-logo":{"url":"https://assets.onestore.ms/cdnfiles/onestorerolling-1606-01000/shell/v3/images/logo/microsoft.png"},"x-origin":[{"format":"swagger","url":"https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json","version":"2.0"}],"x-providerName":"azure.com","x-serviceName":"cognitiveservices-Face","x-tags":["Azure","Microsoft"]},"security":[{"apim_key":[]}],"paths":{"/detect":{"post":{"description":"Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.","operationId":"Face_DetectWithUrl","parameters":[{"description":"A value indicating whether the operation should return faceIds of detected faces.","in":"query","name":"returnFaceId","schema":{"type":"boolean","default":true}},{"description":"A value indicating whether the operation should return landmarks of the detected faces.","in":"query","name":"returnFaceLandmarks","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/returnFaceAttributes"}],"requestBody":{"$ref":"#/components/requestBodies/Face_DetectWithUrlImageurl"},"responses":{"200":{"description":"A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectedFaces"},"examples":{"Detect with url example":{"$ref":"#/components/examples/Detect_with_url_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/facelists":{"get":{"description":"Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.","operationId":"FaceList_List","responses":{"200":{"description":"A successful call returns an array of faceList.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceLists"},"examples":{"List Face lists example":{"$ref":"#/components/examples/List_Face_lists_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/facelists/{faceListId}":{"delete":{"description":"Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.","operationId":"FaceList_Delete","parameters":[{"$ref":"#/components/parameters/faceListId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve a face list's information.","operationId":"FaceList_Get","parameters":[{"$ref":"#/components/parameters/faceListId"}],"responses":{"200":{"description":"A successful call returns the face list's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceList"},"examples":{"Get Face list example":{"$ref":"#/components/examples/Get_Face_list_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update information of a face list.","operationId":"FaceList_Update","parameters":[{"$ref":"#/components/parameters/faceListId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for updating a face list.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"put":{"description":"Create an empty face list. Up to 64 face lists are allowed to exist in one subscription.","operationId":"FaceList_Create","parameters":[{"$ref":"#/components/parameters/faceListId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for creating a face list.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/facelists/{faceListId}/persistedfaces":{"post":{"description":"Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire.","operationId":"FaceList_AddFaceFromUrl","parameters":[{"$ref":"#/components/parameters/faceListId"},{"$ref":"#/components/parameters/faceUserData"},{"$ref":"#/components/parameters/targetFace"}],"requestBody":{"$ref":"#/components/requestBodies/Face_DetectWithUrlImageurl"},"responses":{"200":{"description":"A successful call returns a new persistedFaceId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Create face list face example":{"$ref":"#/components/examples/Create_face_list_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/facelists/{faceListId}/persistedfaces/{persistedFaceId}":{"delete":{"description":"Delete an existing face from a face list (given by a persistedFaceId and a faceListId). Persisted image related to the face will also be deleted.","operationId":"FaceList_DeleteFace","parameters":[{"$ref":"#/components/parameters/faceListId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/findsimilars":{"post":{"description":"Given query face's faceId, find the similar-looking faces from a faceId array, a face list or a large face list.","operationId":"Face_FindSimilar","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindSimilarRequest"}}},"description":"Request body for Find Similar.","required":true,"x-ms-client-flatten":true},"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarFaces"},"examples":{"Find similar results example":{"$ref":"#/components/examples/Find_similar_results_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/group":{"post":{"description":"Divide candidate faces into groups based on face similarity.","operationId":"Face_Group","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupRequest"}}},"description":"Request body for grouping.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupResult"},"examples":{"Group example":{"$ref":"#/components/examples/Group_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/identify":{"post":{"description":"1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.","operationId":"Face_Identify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyRequest"}}},"description":"Request body for identify operation.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns the identified candidate person(s) for each query face.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyResults"},"examples":{"Identify example":{"$ref":"#/components/examples/Identify_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists":{"get":{"description":"Retrieve information about all existing large face lists. Only largeFaceListId, name and userData will be returned.","operationId":"LargeFaceList_List","responses":{"200":{"description":"A successful call returns an array of largeFaceList.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LargeFaceLists"},"examples":{"List large face lists example":{"$ref":"#/components/examples/List_large_face_lists_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists/{largeFaceListId}":{"delete":{"description":"Delete an existing large face list according to faceListId. Persisted face images in the large face list will also be deleted.","operationId":"LargeFaceList_Delete","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve a large face list's information.","operationId":"LargeFaceList_Get","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"responses":{"200":{"description":"A successful call returns the large face list's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LargeFaceList"},"examples":{"Get large face list example":{"$ref":"#/components/examples/Get_large_face_list_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update information of a large face list.","operationId":"LargeFaceList_Update","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for updating a large face list.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"put":{"description":"Create an empty large face list. Up to 64 large face lists are allowed to exist in one subscription.","operationId":"LargeFaceList_Create","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for creating a large face list.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists/{largeFaceListId}/persistedfaces":{"get":{"description":"List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face).","operationId":"LargeFaceList_ListFaces","parameters":[{"$ref":"#/components/parameters/largeFaceListId"},{"description":"Starting face id to return (used to list a range of faces).","in":"query","name":"start","required":false,"schema":{"type":"string"},"examples":{"List faces in large face list":{"value":"25985303-c537-4467-b41d-bdb45cd95ca1"}}},{"description":"Number of faces to return starting with the face id indicated by the 'start' parameter.","in":"query","name":"top","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"examples":{"List faces in large face list":{"value":2}}}],"responses":{"200":{"description":"A successful call returns an array of face information that belong to the large face list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFaces"},"examples":{"List faces in large face list":{"$ref":"#/components/examples/List_faces_in_large_face_list"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"post":{"description":"Add a face to a large 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":"LargeFaceList_AddFaceFromUrl","parameters":[{"$ref":"#/components/parameters/largeFaceListId"},{"$ref":"#/components/parameters/faceUserData"},{"$ref":"#/components/parameters/targetFace"}],"requestBody":{"$ref":"#/components/requestBodies/Face_DetectWithUrlImageurl"},"responses":{"200":{"description":"A successful call returns a new persistedFaceId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Create large face list face example":{"$ref":"#/components/examples/Create_large_face_list_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}":{"delete":{"description":"Delete an existing face from a large face list (given by a persistedFaceId and a largeFaceListId). Persisted image related to the face will also be deleted.","operationId":"LargeFaceList_DeleteFace","parameters":[{"$ref":"#/components/parameters/largeFaceListId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).","operationId":"LargeFaceList_GetFace","parameters":[{"$ref":"#/components/parameters/largeFaceListId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns target persisted face's information (persistedFaceId and userData).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Get persisted face example":{"$ref":"#/components/examples/Get_persisted_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update a persisted face's userData field.","operationId":"LargeFaceList_UpdateFace","parameters":[{"$ref":"#/components/parameters/largeFaceListId"},{"$ref":"#/components/parameters/persistedFaceId"}],"requestBody":{"$ref":"#/components/requestBodies/UpdateFaceRequest"},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists/{largeFaceListId}/train":{"post":{"description":"Queue a large face list training task, the training task may not be started immediately.","operationId":"LargeFaceList_Train","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"responses":{"202":{"description":"The training task was queued successfully."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largefacelists/{largeFaceListId}/training":{"get":{"description":"Retrieve the training status of a large face list (completed or ongoing).","operationId":"LargeFaceList_GetTrainingStatus","parameters":[{"$ref":"#/components/parameters/largeFaceListId"}],"responses":{"200":{"description":"A successful call returns the large face list's training status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingStatus"},"examples":{"Get large face list's training status example":{"$ref":"#/components/examples/Get_large_face_list_s_training_status_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups":{"get":{"description":"List large person groups and their information.","operationId":"LargePersonGroup_List","parameters":[{"description":"List large person groups from the least largePersonGroupId greater than the \"start\".","in":"query","name":"start","required":false,"schema":{"type":"string","maxLength":64},"examples":{"List large person groups example":{"value":"sample_group"}}},{"description":"The number of large person groups to list.","in":"query","name":"top","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"examples":{"List large person groups example":{"value":2}}}],"responses":{"200":{"description":"A successful call returns an array of large person groups and their information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LargePersonGroups"},"examples":{"List large person groups example":{"$ref":"#/components/examples/List_large_person_groups_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}":{"delete":{"description":"Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted.","operationId":"LargePersonGroup_Delete","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve the information of a large person group, including its name and userData.","operationId":"LargePersonGroup_Get","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"responses":{"200":{"description":"A successful call returns the large person group's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LargePersonGroup"},"examples":{"Get large person group example":{"$ref":"#/components/examples/Get_large_person_group_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated.","operationId":"LargePersonGroup_Update","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for updating large person group.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"put":{"description":"Create a new large person group with specified largePersonGroupId, name and user-provided userData.","operationId":"LargePersonGroup_Create","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for creating new large person group.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/persons":{"get":{"description":"List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).","operationId":"LargePersonGroupPerson_List","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"description":"Starting person id to return (used to list a range of persons).","in":"query","name":"start","required":false,"schema":{"type":"string"},"examples":{"List persons in person group":{"value":"25985303-c537-4467-b41d-bdb45cd95ca1"}}},{"description":"Number of persons to return starting with the person id indicated by the 'start' parameter.","in":"query","name":"top","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"examples":{"List persons in person group":{"value":2}}}],"responses":{"200":{"description":"A successful call returns an array of person information that belong to the large person group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persons"},"examples":{"List persons in person group":{"$ref":"#/components/examples/List_persons_in_person_group"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"post":{"description":"Create a new person in a specified large person group.","operationId":"LargePersonGroupPerson_Create","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"requestBody":{"$ref":"#/components/requestBodies/NameAndUserDataContract2"},"responses":{"200":{"description":"A successful call returns a new personId created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"},"examples":{"Create new person for large person group example":{"$ref":"#/components/examples/Create_new_person_for_large_person_group_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/persons/{personId}":{"delete":{"description":"Delete an existing person from a large person group. All stored person data, and face features in the person entry will be deleted.","operationId":"LargePersonGroupPerson_Delete","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve a person's information, including registered persisted faces, name and userData.","operationId":"LargePersonGroupPerson_Get","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"}],"responses":{"200":{"description":"A successful call returns the person's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"},"examples":{"Get person example":{"$ref":"#/components/examples/Get_person_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update name or userData of a person.","operationId":"LargePersonGroupPerson_Update","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"}],"requestBody":{"$ref":"#/components/requestBodies/NameAndUserDataContract"},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces":{"post":{"description":"Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.","operationId":"LargePersonGroupPerson_AddFaceFromUrl","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/faceUserData"},{"$ref":"#/components/parameters/targetFace"}],"requestBody":{"$ref":"#/components/requestBodies/Face_DetectWithUrlImageurl"},"responses":{"200":{"description":"A successful call returns the new persistedFaceId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Add Person face example":{"$ref":"#/components/examples/Add_Person_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}":{"delete":{"description":"Delete a face from a person. Relative feature for the persisted face will also be deleted.","operationId":"LargePersonGroupPerson_DeleteFace","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId).","operationId":"LargePersonGroupPerson_GetFace","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns target persisted face's information (persistedFaceId and userData).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Get persisted face example":{"$ref":"#/components/examples/Get_persisted_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update a person persisted face's userData field.","operationId":"LargePersonGroupPerson_UpdateFace","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"requestBody":{"$ref":"#/components/requestBodies/UpdateFaceRequest"},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/train":{"post":{"description":"Queue a large person group training task, the training task may not be started immediately.","operationId":"LargePersonGroup_Train","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"responses":{"202":{"description":"The training task was queued successfully."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/largepersongroups/{largePersonGroupId}/training":{"get":{"description":"Retrieve the training status of a large person group (completed or ongoing).","operationId":"LargePersonGroup_GetTrainingStatus","parameters":[{"$ref":"#/components/parameters/largePersonGroupId"}],"responses":{"200":{"description":"A successful call returns the large person group's training status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingStatus"},"examples":{"Get large person group's training status example":{"$ref":"#/components/examples/Get_large_person_group_s_training_status_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/operations/{operationId}":{"get":{"description":"Retrieve the status of a take/apply snapshot operation.","operationId":"Snapshot_GetOperationStatus","parameters":[{"$ref":"#/components/parameters/operationId"}],"responses":{"200":{"description":"A successful call returns the snapshot operation's status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationStatus"},"examples":{"Get snapshot operation status example":{"$ref":"#/components/examples/Get_snapshot_operation_status_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups":{"get":{"description":"List person groups and their information.","operationId":"PersonGroup_List","parameters":[{"description":"List person groups from the least personGroupId greater than the \"start\".","in":"query","name":"start","required":false,"schema":{"type":"string","maxLength":64},"examples":{"List person groups example":{"value":"sample_group"}}},{"description":"The number of person groups to list.","in":"query","name":"top","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"examples":{"List person groups example":{"value":2}}}],"responses":{"200":{"description":"A successful call returns an array of person groups and their information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonGroups"},"examples":{"List person groups example":{"$ref":"#/components/examples/List_person_groups_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}":{"delete":{"description":"Delete an existing person group. Persisted face features of all people in the person group will also be deleted.","operationId":"PersonGroup_Delete","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve the information of a person group, including its name and userData.","operationId":"PersonGroup_Get","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"responses":{"200":{"description":"A successful call returns the person group's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonGroup"},"examples":{"Get person group example":{"$ref":"#/components/examples/Get_person_group_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update an existing person group's display name and userData. The properties which does not appear in request body will not be updated.","operationId":"PersonGroup_Update","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for updating person group.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"put":{"description":"Create a new person group with specified personGroupId, name and user-provided userData.","operationId":"PersonGroup_Create","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameAndUserDataContract"}}},"description":"Request body for creating new person group.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/persons":{"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":"PersonGroupPerson_List","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"description":"Starting person id to return (used to list a range of persons).","in":"query","name":"start","required":false,"schema":{"type":"string"},"examples":{"List persons in person group":{"value":"25985303-c537-4467-b41d-bdb45cd95ca1"}}},{"description":"Number of persons to return starting with the person id indicated by the 'start' parameter.","in":"query","name":"top","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000},"examples":{"List persons in person group":{"value":2}}}],"responses":{"200":{"description":"A successful call returns an array of person information that belong to the person group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persons"},"examples":{"List persons in person group":{"$ref":"#/components/examples/List_persons_in_person_group"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"post":{"description":"Create a new person in a specified person group.","operationId":"PersonGroupPerson_Create","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"requestBody":{"$ref":"#/components/requestBodies/NameAndUserDataContract2"},"responses":{"200":{"description":"A successful call returns a new personId created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"},"examples":{"Create new person for person group example":{"$ref":"#/components/examples/Create_new_person_for_person_group_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/persons/{personId}":{"delete":{"description":"Delete an existing person from a person group. All stored person data, and face features in the person entry will be deleted.","operationId":"PersonGroupPerson_Delete","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve a person's information, including registered persisted faces, name and userData.","operationId":"PersonGroupPerson_Get","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"}],"responses":{"200":{"description":"A successful call returns the person's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"},"examples":{"Get person example":{"$ref":"#/components/examples/Get_person_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update name or userData of a person.","operationId":"PersonGroupPerson_Update","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"}],"requestBody":{"$ref":"#/components/requestBodies/NameAndUserDataContract"},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/persons/{personId}/persistedfaces":{"post":{"description":"Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.","operationId":"PersonGroupPerson_AddFaceFromUrl","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/faceUserData"},{"$ref":"#/components/parameters/targetFace"}],"requestBody":{"$ref":"#/components/requestBodies/Face_DetectWithUrlImageurl"},"responses":{"200":{"description":"A successful call returns the new persistedFaceId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Add Person face example":{"$ref":"#/components/examples/Add_Person_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}":{"delete":{"description":"Delete a face from a person. Relative feature for the persisted face will also be deleted.","operationId":"PersonGroupPerson_DeleteFace","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).","operationId":"PersonGroupPerson_GetFace","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"responses":{"200":{"description":"A successful call returns target persisted face's information (persistedFaceId and userData).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedFace"},"examples":{"Get persisted face example":{"$ref":"#/components/examples/Get_persisted_face_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update a person persisted face's userData field.","operationId":"PersonGroupPerson_UpdateFace","parameters":[{"$ref":"#/components/parameters/personGroupId"},{"$ref":"#/components/parameters/personId"},{"$ref":"#/components/parameters/persistedFaceId"}],"requestBody":{"$ref":"#/components/requestBodies/UpdateFaceRequest"},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/train":{"post":{"description":"Queue a person group training task, the training task may not be started immediately.","operationId":"PersonGroup_Train","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"responses":{"202":{"description":"The training task was queued successfully."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/persongroups/{personGroupId}/training":{"get":{"description":"Retrieve the training status of a person group (completed or ongoing).","operationId":"PersonGroup_GetTrainingStatus","parameters":[{"$ref":"#/components/parameters/personGroupId"}],"responses":{"200":{"description":"A successful call returns the person group's training status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingStatus"},"examples":{"Get person group's training status example":{"$ref":"#/components/examples/Get_person_group_s_training_status_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/snapshots":{"get":{"description":"List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take).","operationId":"Snapshot_List","parameters":[{"description":"User specified object type as a search filter.","in":"query","name":"type","required":false,"x-ms-enum":{"modelAsString":false,"name":"SnapshotObjectType"},"schema":{"type":"string","enum":["FaceList","LargeFaceList","LargePersonGroup","PersonGroup"]},"examples":{"List snapshots example":{"value":"FaceList"}}},{"$ref":"#/components/parameters/applyScope"}],"responses":{"200":{"description":"A successful call returns an array of snapshots with snapshot information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshots"},"examples":{"List snapshots example":{"$ref":"#/components/examples/List_snapshots_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"post":{"description":"Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br />\nThe snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br />\nTaking snapshot is an asynchronous operation. An operation id can be obtained from the \"Operation-Location\" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the \"resourceLocation\" field in OperationStatus - Get response when the operation status is \"succeeded\".<br />\nSnapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br />\nSnapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br />\nTaking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br />\n* Free-tier subscription quota: 100 take operations per month.\n* S0-tier subscription quota: 100 take operations per day.","operationId":"Snapshot_Take","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeSnapshotRequest"}}},"description":"Request body for taking a snapshot.","required":true,"x-ms-client-flatten":true},"responses":{"202":{"description":"The snapshot taking task was queued successfully.","headers":{"Operation-Location":{"description":"Operation location with an operation id used to track the progress of taking snapshot. The returned id is the operation id, rather than snapshot id. Snapshot id can be obtained only when the operation status becomes \"succeeded\" in OperationStatus - Get.","schema":{"type":"string"}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/snapshots/{snapshotId}":{"delete":{"description":"Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation.","operationId":"Snapshot_Delete","parameters":[{"$ref":"#/components/parameters/snapshotId"}],"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"get":{"description":"Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take.","operationId":"Snapshot_Get","parameters":[{"$ref":"#/components/parameters/snapshotId"}],"responses":{"200":{"description":"A successful call returns the snapshot's information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"},"examples":{"Get snapshot example":{"$ref":"#/components/examples/Get_snapshot_example"}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}},"patch":{"description":"Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot.","operationId":"Snapshot_Update","parameters":[{"$ref":"#/components/parameters/snapshotId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSnapshotRequest"}}},"description":"Request body for updating a snapshot.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns an empty response body."},"default":{"description":"Error response.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/snapshots/{snapshotId}/apply":{"post":{"description":"Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br />\nThe snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br />\nApplying snapshot is an asynchronous operation. An operation id can be obtained from the \"Operation-Location\" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the \"resourceLocation\" field in OperationStatus - Get response when the operation status is \"succeeded\".<br />\nSnapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br />\nSnapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br />\nApplying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br />\nOne snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the \"objectId\" in request body to avoid such conflicts.<br />\n* Free-tier subscription quota: 100 apply operations per month.\n* S0-tier subscription quota: 100 apply operations per day.","operationId":"Snapshot_Apply","parameters":[{"$ref":"#/components/parameters/snapshotId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplySnapshotRequest"}}},"description":"Request body for applying a snapshot.","required":true,"x-ms-client-flatten":true},"responses":{"202":{"description":"The snapshot applying task was queued successfully.","headers":{"Operation-Location":{"description":"Operation location with an operation id used to track the progress of applying the snapshot by OperationStatus - Get.","schema":{"type":"string"}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}},"/verify":{"post":{"description":"Verify whether two faces belong to a same person or whether one face belongs to a person.","operationId":"Face_VerifyFaceToFace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyFaceToFaceRequest"}}},"description":"Request body for face to face verification.","required":true,"x-ms-client-flatten":true},"responses":{"200":{"description":"A successful call returns the verificati