azure.cognitiveservices.vision.face.operations module

class azure.cognitiveservices.vision.face.operations.FaceOperations(client, config, serializer, deserializer)[source]

Bases: object

FaceOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
detect_with_stream(image, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, custom_headers=None, raw=False, callback=None, **operation_config)[source]

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:
  • image (Generator) – An image stream.
  • return_face_id (bool) – A value indicating whether the operation should return faceIds of detected faces.
  • return_face_landmarks (bool) – A value indicating whether the operation should return landmarks of the detected faces.
  • return_face_attributes (list[str or FaceAttributeType]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • callback (Callable[Bytes, response=None]) – When specified, will be called with each chunk of data that is streamed. The callback should take two arguments, the bytes of the current chunk of data and the response object. If the data is uploading, response will be None.
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[DetectedFace] or ClientRawResponse

Raises:

APIErrorException

detect_with_url(url, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, custom_headers=None, raw=False, **operation_config)[source]

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:
  • url (str) – Publicly reachable URL of an image
  • return_face_id (bool) – A value indicating whether the operation should return faceIds of detected faces.
  • return_face_landmarks (bool) – A value indicating whether the operation should return landmarks of the detected faces.
  • return_face_attributes (list[str or FaceAttributeType]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[DetectedFace] or ClientRawResponse

Raises:

APIErrorException

find_similar(face_id, face_list_id=None, large_face_list_id=None, face_ids=None, max_num_of_candidates_returned=20, mode='matchPerson', custom_headers=None, raw=False, **operation_config)[source]

Given query face’s faceId, find the similar-looking faces from a faceId array, a face list or a large face list.

Parameters:
  • face_id (str) – 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
  • face_list_id (str) – 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, largeFaceListId and faceIds should not be provided at the same time。
  • large_face_list_id (str) – An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time.
  • face_ids (list[str]) – 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, largeFaceListId and faceIds should not be provided at the same time.
  • max_num_of_candidates_returned (int) – The number of top similar faces returned. The valid range is [1, 1000].
  • mode (str or FindSimilarMatchMode) – Similar face searching mode. It can be “matchPerson” or “matchFace”. Possible values include: ‘matchPerson’, ‘matchFace’
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[SimilarFace] or ClientRawResponse

Raises:

APIErrorException

group(face_ids, custom_headers=None, raw=False, **operation_config)[source]

Divide candidate faces into groups based on face similarity.

Parameters:
  • face_ids (list[str]) – Array of candidate faceId created by Face - Detect. The maximum is 1000 faces
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

GroupResult or ClientRawResponse if raw=true

Return type:

GroupResult or ClientRawResponse

Raises:

APIErrorException

identify(face_ids, person_group_id=None, large_person_group_id=None, max_num_of_candidates_returned=1, confidence_threshold=None, custom_headers=None, raw=False, **operation_config)[source]

1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.

Parameters:
  • face_ids (list[str]) – Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10].
  • person_group_id (str) – PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
  • large_person_group_id (str) – LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
  • max_num_of_candidates_returned (int) – The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1).
  • confidence_threshold (float) – 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).
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[IdentifyResult] or ClientRawResponse

Raises:

APIErrorException

verify_face_to_face(face_id1, face_id2, custom_headers=None, raw=False, **operation_config)[source]

Verify whether two faces belong to a same person or whether one face belongs to a person.

Parameters:
  • face_id1 (str) – FaceId of the first face, comes from Face - Detect
  • face_id2 (str) – FaceId of the second face, comes from Face - Detect
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

VerifyResult or ClientRawResponse if raw=true

Return type:

VerifyResult or ClientRawResponse

Raises:

APIErrorException

verify_face_to_person(face_id, person_id, person_group_id=None, large_person_group_id=None, custom_headers=None, raw=False, **operation_config)[source]

Verify whether two faces belong to a same person. Compares a face Id with a Person Id.

Parameters:
  • face_id (str) – FaceId of the face, comes from Face - Detect
  • person_id (str) – Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create.
  • person_group_id (str) – Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
  • large_person_group_id (str) – Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

VerifyResult or ClientRawResponse if raw=true

Return type:

VerifyResult or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.PersonGroupPersonOperations(client, config, serializer, deserializer)[source]

Bases: object

PersonGroupPersonOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
add_face_from_stream(person_group_id, person_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config)[source]

Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • image (Generator) – An image stream.
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • callback (Callable[Bytes, response=None]) – When specified, will be called with each chunk of data that is streamed. The callback should take two arguments, the bytes of the current chunk of data and the response object. If the data is uploading, response will be None.
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

add_face_from_url(person_group_id, person_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config)[source]

Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • url (str) – Publicly reachable URL of an image
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

create(person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create a new person in a specified person group.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

Person or ClientRawResponse if raw=true

Return type:

Person or ClientRawResponse

Raises:

APIErrorException

delete(person_group_id, person_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing person from a person group. All stored person data, and face features in the person entry will be deleted.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete_face(person_group_id, person_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Delete a face from a person. Relative feature for the persisted face will also be deleted.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(person_group_id, person_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve a person’s information, including registered persisted faces, name and userData.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

Person or ClientRawResponse if raw=true

Return type:

Person or ClientRawResponse

Raises:

APIErrorException

get_face(person_group_id, person_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

list(person_group_id, start=None, top=None, custom_headers=None, raw=False, **operation_config)[source]

List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • start (str) – Starting person id to return (used to list a range of persons).
  • top (int) – Number of persons to return starting with the person id indicated by the ‘start’ parameter.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[Person] or ClientRawResponse

Raises:

APIErrorException

update(person_group_id, person_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update name or userData of a person.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update_face(person_group_id, person_id, persisted_face_id, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update a person persisted face’s userData field.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • user_data (str) – User-provided data attached to the face. The size limit is 1KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.PersonGroupOperations(client, config, serializer, deserializer)[source]

Bases: object

PersonGroupOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
create(person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create a new person group with specified personGroupId, name and user-provided userData.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete(person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing person group. Persisted face features of all people in the person group will also be deleted.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve the information of a person group, including its name and userData.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersonGroup or ClientRawResponse if raw=true

Return type:

PersonGroup or ClientRawResponse

Raises:

APIErrorException

get_training_status(person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve the training status of a person group (completed or ongoing).

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

TrainingStatus or ClientRawResponse if raw=true

Return type:

TrainingStatus or ClientRawResponse

Raises:

APIErrorException

list(start=None, top=1000, custom_headers=None, raw=False, **operation_config)[source]

List person groups and their information.

Parameters:
  • start (str) – List person groups from the least personGroupId greater than the “start”.
  • top (int) – The number of person groups to list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[PersonGroup] or ClientRawResponse

Raises:

APIErrorException

train(person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Queue a person group training task, the training task may not be started immediately.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update(person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update an existing person group’s display name and userData. The properties which does not appear in request body will not be updated.

Parameters:
  • person_group_id (str) – Id referencing a particular person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.FaceListOperations(client, config, serializer, deserializer)[source]

Bases: object

FaceListOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
add_face_from_stream(face_list_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config)[source]

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.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • image (Generator) – An image stream.
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • callback (Callable[Bytes, response=None]) – When specified, will be called with each chunk of data that is streamed. The callback should take two arguments, the bytes of the current chunk of data and the response object. If the data is uploading, response will be None.
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

add_face_from_url(face_list_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config)[source]

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.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • url (str) – Publicly reachable URL of an image
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

create(face_list_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create an empty face list. Up to 64 face lists are allowed to exist in one subscription.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete(face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete_face(face_list_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

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.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve a face list’s information.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

FaceList or ClientRawResponse if raw=true

Return type:

FaceList or ClientRawResponse

Raises:

APIErrorException

list(custom_headers=None, raw=False, **operation_config)[source]

Retrieve information about all existing face lists. Only faceListId, name and userData will be returned.

Parameters:
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[FaceList] or ClientRawResponse

Raises:

APIErrorException

update(face_list_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update information of a face list.

Parameters:
  • face_list_id (str) – Id referencing a particular face list.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.LargePersonGroupPersonOperations(client, config, serializer, deserializer)[source]

Bases: object

LargePersonGroupPersonOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
add_face_from_stream(large_person_group_id, person_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config)[source]

Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • image (Generator) – An image stream.
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • callback (Callable[Bytes, response=None]) – When specified, will be called with each chunk of data that is streamed. The callback should take two arguments, the bytes of the current chunk of data and the response object. If the data is uploading, response will be None.
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

add_face_from_url(large_person_group_id, person_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config)[source]

Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • url (str) – Publicly reachable URL of an image
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

create(large_person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create a new person in a specified large person group.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

Person or ClientRawResponse if raw=true

Return type:

Person or ClientRawResponse

Raises:

APIErrorException

delete(large_person_group_id, person_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing person from a large person group. All stored person data, and face features in the person entry will be deleted.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete_face(large_person_group_id, person_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Delete a face from a person. Relative feature for the persisted face will also be deleted.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(large_person_group_id, person_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve a person’s information, including registered persisted faces, name and userData.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

Person or ClientRawResponse if raw=true

Return type:

Person or ClientRawResponse

Raises:

APIErrorException

get_face(large_person_group_id, person_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId).

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

list(large_person_group_id, start=None, top=None, custom_headers=None, raw=False, **operation_config)[source]

List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • start (str) – Starting person id to return (used to list a range of persons).
  • top (int) – Number of persons to return starting with the person id indicated by the ‘start’ parameter.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[Person] or ClientRawResponse

Raises:

APIErrorException

update(large_person_group_id, person_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update name or userData of a person.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update_face(large_person_group_id, person_id, persisted_face_id, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update a person persisted face’s userData field.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • person_id (str) – Id referencing a particular person.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • user_data (str) – User-provided data attached to the face. The size limit is 1KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.LargePersonGroupOperations(client, config, serializer, deserializer)[source]

Bases: object

LargePersonGroupOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
create(large_person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create a new large person group with specified largePersonGroupId, name and user-provided userData.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete(large_person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(large_person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve the information of a large person group, including its name and userData.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

LargePersonGroup or ClientRawResponse if raw=true

Return type:

LargePersonGroup or ClientRawResponse

Raises:

APIErrorException

get_training_status(large_person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve the training status of a large person group (completed or ongoing).

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

TrainingStatus or ClientRawResponse if raw=true

Return type:

TrainingStatus or ClientRawResponse

Raises:

APIErrorException

list(start=None, top=1000, custom_headers=None, raw=False, **operation_config)[source]

List large person groups and their information.

Parameters:
  • start (str) – List large person groups from the least largePersonGroupId greater than the “start”.
  • top (int) – The number of large person groups to list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[LargePersonGroup] or ClientRawResponse

Raises:

APIErrorException

train(large_person_group_id, custom_headers=None, raw=False, **operation_config)[source]

Queue a large person group training task, the training task may not be started immediately.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update(large_person_group_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update an existing large person group’s display name and userData. The properties which does not appear in request body will not be updated.

Parameters:
  • large_person_group_id (str) – Id referencing a particular large person group.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>
class azure.cognitiveservices.vision.face.operations.LargeFaceListOperations(client, config, serializer, deserializer)[source]

Bases: object

LargeFaceListOperations operations.

Parameters:
  • client – Client for service requests.
  • config – Configuration of service client.
  • serializer – An object model serializer.
  • deserializer – An object model deserializer.
add_face_from_stream(large_face_list_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config)[source]

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.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • image (Generator) – An image stream.
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • callback (Callable[Bytes, response=None]) – When specified, will be called with each chunk of data that is streamed. The callback should take two arguments, the bytes of the current chunk of data and the response object. If the data is uploading, response will be None.
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

add_face_from_url(large_face_list_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config)[source]

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.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • url (str) – Publicly reachable URL of an image
  • user_data (str) – User-specified data about the face for any purpose. The maximum length is 1KB.
  • target_face (list[int]) – 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.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

create(large_face_list_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Create an empty large face list. Up to 64 large face lists are allowed to exist in one subscription.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete(large_face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing large face list according to faceListId. Persisted face images in the large face list will also be deleted.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

delete_face(large_face_list_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Delete an existing face from a large face list (given by a persisitedFaceId and a largeFaceListId). Persisted image related to the face will also be deleted.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

get(large_face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve a large face list’s information.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

LargeFaceList or ClientRawResponse if raw=true

Return type:

LargeFaceList or ClientRawResponse

Raises:

APIErrorException

get_face(large_face_list_id, persisted_face_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

PersistedFace or ClientRawResponse if raw=true

Return type:

PersistedFace or ClientRawResponse

Raises:

APIErrorException

get_training_status(large_face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Retrieve the training status of a large face list (completed or ongoing).

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

TrainingStatus or ClientRawResponse if raw=true

Return type:

TrainingStatus or ClientRawResponse

Raises:

APIErrorException

list(custom_headers=None, raw=False, **operation_config)[source]

Retrieve information about all existing large face lists. Only largeFaceListId, name and userData will be returned.

Parameters:
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[LargeFaceList] or ClientRawResponse

Raises:

APIErrorException

list_faces(large_face_list_id, start=None, top=None, custom_headers=None, raw=False, **operation_config)[source]

List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face).

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • start (str) – Starting face id to return (used to list a range of faces).
  • top (int) – Number of faces to return starting with the face id indicated by the ‘start’ parameter.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

list or ClientRawResponse if raw=true

Return type:

list[PersistedFace] or ClientRawResponse

Raises:

APIErrorException

train(large_face_list_id, custom_headers=None, raw=False, **operation_config)[source]

Queue a large face list training task, the training task may not be started immediately.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update(large_face_list_id, name=None, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update information of a large face list.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • name (str) – User defined name, maximum length is 128.
  • user_data (str) – User specified data. Length should not exceed 16KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

update_face(large_face_list_id, persisted_face_id, user_data=None, custom_headers=None, raw=False, **operation_config)[source]

Update a persisted face’s userData field.

Parameters:
  • large_face_list_id (str) – Id referencing a particular large face list.
  • persisted_face_id (str) – Id referencing a particular persistedFaceId of an existing face.
  • user_data (str) – User-provided data attached to the face. The size limit is 1KB.
  • custom_headers (dict) – headers that will be added to the request
  • raw (bool) – returns the direct response alongside the deserialized response
  • operation_configOperation configuration overrides.
Returns:

None or ClientRawResponse if raw=true

Return type:

None or ClientRawResponse

Raises:

APIErrorException

models = <module 'azure.cognitiveservices.vision.face.models' from '/usr/lib/python3/dist-packages/azure/cognitiveservices/vision/face/models/__init__.py'>