swagger: '2.0'
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client
  description: An API for face detection, verification, and identification.
securityDefinitions:
  apim_key:
    type: apiKey
    name: Ocp-Apim-Subscription-Key
    in: header
security:
  - apim_key: []
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/face/v1.0-preview'
  useSchemePrefix: false
  parameters:
    - $ref: '#/parameters/Endpoint'
paths:
  /findsimilars:
    post:
      description: >-
        Given query face's faceId, to search the similar-looking faces from a
        faceId array, a face list or a large face list. faceId array contains
        the faces created by [Face - Detect With
        Url](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl) or
        [Face - Detect With
        Stream](https://docs.microsoft.com/rest/api/faceapi/face/detectwithstream),
        which will expire at the time specified by faceIdTimeToLive after
        creation. A "faceListId" is created by [FaceList -
        Create](https://docs.microsoft.com/rest/api/faceapi/facelist/create)
        containing persistedFaceIds that will not expire. And a
        "largeFaceListId" is created by [LargeFaceList -
        Create](https://docs.microsoft.com/rest/api/faceapi/largefacelist/create)
        containing persistedFaceIds that will also not expire. Depending on the
        input the returned similar faces list contains faceIds or
        persistedFaceIds ranked by similarity.<br>Find similar has two working
        modes, "matchPerson" and "matchFace". "matchPerson" is the default mode
        that it tries to find faces of the same person as possible by using
        internal same-person thresholds. It is useful to find a known person's
        other photos. Note that an empty list will be returned if no faces pass
        the internal thresholds. "matchFace" mode ignores same-person thresholds
        and returns ranked similar faces anyway, even the similarity is low. It
        can be used in the cases like searching celebrity-looking faces.<br>The
        'recognitionModel' associated with the query face's faceId should be the
        same as the 'recognitionModel' used by the target faceId array, face
        list or large face list.<br>
      operationId: microsoftAzureFaceFindsimilar
      parameters:
        - name: body
          in: body
          description: Request body for Find Similar.
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/FindSimilarRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of the most similar faces
            represented in faceId if the input parameter is faceIds or
            persistedFaceId if the input parameter is faceListId.
          schema:
            $ref: '#/definitions/SimilarFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Find similar results example:
          $ref: ./examples/FindSimilar.json
      summary: Microsoft Azure Post Findsimilars
      tags:
        - Findsimilars
  /group:
    post:
      description: >-
        Divide candidate faces into groups based on face similarity.<br>* The
        output is one or more disjointed face groups and a messyGroup. A face
        group contains faces that have similar looking, often of the same
        person. Face groups are ranked by group size, i.e. number of faces.
        Notice that faces belonging to a same person might be split into several
        groups in the result.<br>* MessyGroup is a special face group containing
        faces that cannot find any similar counterpart face from original faces.
        The messyGroup will not appear in the result if all faces found their
        counterparts.<br>* Group API needs at least 2 candidate faces and 1000
        at most. We suggest to try [Face -
        Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface)
        when you only have 2 candidate faces.<br>* The 'recognitionModel'
        associated with the query faces' faceIds should be the same.<br>
      operationId: microsoftAzureFaceGroup
      parameters:
        - name: body
          description: Request body for grouping.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/GroupRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns one or more groups of similar faces (rank
            by group size) and a messyGroup.
          schema:
            $ref: '#/definitions/GroupResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Group example:
          $ref: ./examples/Group.json
      summary: Microsoft Azure Post Group
      tags:
        - Group
  /identify:
    post:
      description: >-
        1-to-many identification to find the closest matches of the specific
        query person face from a person group, large person group, person
        directory dynamic person group or person directory personIds array.<br>
        For each face in the faceIds array, Face Identify will compute
        similarities between the query face and all the faces in the person
        group (given by personGroupId) or large person group (given by
        largePersonGroupId), and return candidate person(s) for that face ranked
        by similarity confidence. The person group/large person group should be
        trained to make it ready for identification. See more in [PersonGroup -
        Train](https://docs.microsoft.com/rest/api/faceapi/persongroup/train)
        and [LargePersonGroup -
        Train](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/train).<br><br>
        <br>Remarks:<br>* The algorithm allows more than one face to be
        identified independently at the same request, but no more than 10
        faces.<br>* Each person in the person group/large person group could
        have more than one face, but no more than 248 faces.<br>* Higher face
        image quality means better identification precision. Please consider
        high-quality faces: frontal, clear, and face size is 200x200 pixels (100
        pixels between eyes) or bigger.<br>* Number of candidates returned is
        restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no
        person is identified, the returned candidates will be an empty
        array.<br>* Try [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar)
        when you need to find similar faces from a face list/large face list
        instead of a person group/large person group.<br>* The
        'recognitionModel' associated with the query faces' faceIds should be
        the same as the 'recognitionModel' used by the target person group or
        large person group.<br>
      operationId: microsoftAzureFaceIdentify
      parameters:
        - name: body
          description: Request body for identify operation.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/IdentifyRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns the identified candidate person(s) for
            each query face.
          schema:
            $ref: '#/definitions/IdentifyResults'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Identify example:
          $ref: ./examples/Identify.json
      summary: Microsoft Azure Post Identify
      tags:
        - Identify
  /verify:
    post:
      description: >-
        Verify whether two faces belong to a same person or whether one face
        belongs to a person.<br><br>Remarks:<br>* Higher face image quality
        means better identification precision. Please consider high-quality
        faces: frontal, clear, and face size is 200x200 pixels (100 pixels
        between eyes) or bigger.<br>* For the scenarios that are sensitive to
        accuracy please make your own judgment.<br>* The 'recognitionModel'
        associated with the query faces' faceIds should be the same as the
        'recognitionModel' used by the target face, person group or large person
        group.<br>
      operationId: microsoftAzureFaceVerifyfacetoface
      parameters:
        - name: body
          description: Request body for face to face verification.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/VerifyFaceToFaceRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the verification result.
          schema:
            $ref: '#/definitions/VerifyResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Verify faces example:
          $ref: ./examples/VerifyFaceToFace.json
      summary: Microsoft Azure Post Verify
      tags:
        - Verify
  /persongroups/{personGroupId}/persons:
    post:
      description: Create a new person in a specified person group.
      operationId: microsoftAzurePersongrouppersonCreate
      parameters:
        - $ref: '#/parameters/personGroupId'
        - name: body
          description: Request body for creating new person.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns a new personId created.
          schema:
            $ref: '#/definitions/Person'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new person for person group example:
          $ref: ./examples/CreateNewPersonGroupPerson.json
      summary: Microsoft Azure Post Persongroups Persongroupid Persons
      tags:
        - Persongroups
    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: microsoftAzurePersongrouppersonList
      parameters:
        - $ref: '#/parameters/personGroupId'
        - name: start
          description: Starting person id to return (used to list a range of persons).
          in: query
          required: false
          type: string
        - name: top
          description: >-
            Number of persons to return starting with the person id indicated by
            the 'start' parameter.
          in: query
          required: false
          type: integer
          minimum: 1
          maximum: 1000
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of person information that belong
            to the person group.
          schema:
            $ref: '#/definitions/Persons'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        List persons in person group:
          $ref: ./examples/ListPersonGroupPersons.json
      summary: Microsoft Azure Get Persongroups Persongroupid Persons
      tags:
        - Persongroups
  /persongroups/{personGroupId}/persons/{personId}:
    delete:
      description: >-
        Delete an existing person from a person group. The persistedFaceId,
        userData, person name and face feature in the person entry will all be
        deleted.
      operationId: microsoftAzurePersongrouppersonDelete
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete an existing person example:
          $ref: ./examples/DeletePersonGroupPerson.json
      summary: Microsoft Azure Delete Persongroups Persongroupid Persons Personid
      tags:
        - Persongroups
    get:
      description: >-
        Retrieve a person's information, including registered persisted faces,
        name and userData.
      operationId: microsoftAzurePersongrouppersonGet
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the person's information.
          schema:
            $ref: '#/definitions/Person'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get person example:
          $ref: ./examples/GetPersonGroupPerson.json
      summary: Microsoft Azure Get Persongroups Persongroupid Persons Personid
      tags:
        - Persongroups
    patch:
      description: Update name or userData of a person.
      operationId: microsoftAzurePersongrouppersonUpdate
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - name: body
          description: Request body for person update operation.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update person example:
          $ref: ./examples/UpdatePersonGroupPerson.json
      summary: Microsoft Azure Patch Persongroups Persongroupid Persons Personid
      tags:
        - Persongroups
  /persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}:
    delete:
      description: >-
        Delete a face from a person in a person group by specified
        personGroupId, personId and persistedFaceId.<br> Adding/deleting faces
        to/from a same person will be processed sequentially. Adding/deleting
        faces to/from different persons are processed in parallel.
      operationId: microsoftAzurePersongrouppersonDeleteface
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete face from person example:
          $ref: ./examples/DeletePersonGroupPersonFace.json
      summary: >-
        Microsoft Azure Delete Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Persongroups
    get:
      description: >-
        Retrieve information about a persisted face (specified by
        persistedFaceId, personId and its belonging personGroupId).
      operationId: microsoftAzurePersongrouppersonGetface
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns target persisted face's information
            (persistedFaceId and userData).
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get persisted face example:
          $ref: ./examples/GetPersonGroupPersistedFace.json
      summary: >-
        Microsoft Azure Get Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Persongroups
    patch:
      description: >-
        Add a face to a person into a person group for face identification or
        verification. To deal with an image contains multiple faces, input face
        can be specified as an image with a targetFace rectangle. It returns a
        persistedFaceId representing the added face. No image will be stored.
        Only the extracted face feature will be stored on server until
        [PersonGroup PersonFace -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/deleteface),
        [PersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
        or [PersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
        is called.<br> Note persistedFaceId is different from faceId generated
        by [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*
        Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.<br>* Each person entry can
        hold up to 248 faces.<br>* JPEG, PNG, GIF (the first frame), and BMP
        format are supported. The allowed image file size is from 1KB to
        6MB.<br>* "targetFace" rectangle should contain one face. Zero or
        multiple faces will be regarded as an error. If the provided
        "targetFace" rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.<br>* Out
        of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
        large occlusions will cause failures.<br>* Adding/deleting faces to/from
        a same person will be processed sequentially. Adding/deleting faces
        to/from different persons are processed in parallel.
      operationId: microsoftAzurePersongrouppersonUpdateface
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
        - name: body
          description: Request body for updating persisted face.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/UpdateFaceRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update person face example:
          $ref: ./examples/UpdatePersonGroupPersonFace.json
      summary: >-
        Microsoft Azure Patch Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Persongroups
  /persongroups/{personGroupId}:
    put:
      description: >-
        Create a new person group with specified personGroupId, name,
        user-provided userData and recognitionModel.<br> A person group is the
        container of the uploaded person data, including face recognition
        features.<br> After creation, use [PersonGroup Person -
        Create](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/create)
        to add persons into the group, and then call [PersonGroup -
        Train](https://docs.microsoft.com/rest/api/faceapi/persongroup/train) to
        get this group ready for [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>
        No image will be stored. Only the person's extracted face features and
        userData will be stored on server until [PersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
        or [PersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
        is called.<br>'recognitionModel' should be specified to associate with
        this person group. The default value for 'recognitionModel' is
        'recognition_01', if the latest model needed, please explicitly specify
        the model you need in this parameter. New faces that are added to an
        existing person group will use the recognition model that's already
        associated with the collection. Existing face features in a person group
        can't be updated to features extracted by another version of recognition
        model.<br><br>Person group quota:<br>* Free-tier subscription quota:
        1,000 person groups. Each holds up to 1,000 persons.<br>* S0-tier
        subscription quota: 1,000,000 person groups. Each holds up to 10,000
        persons.<br>* to handle larger scale face identification problem, please
        consider using
        [LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup).
      operationId: microsoftAzurePersongroupCreate
      parameters:
        - $ref: '#/parameters/personGroupId'
        - name: body
          description: Request body for creating new person group.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/MetaDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new person group example:
          $ref: ./examples/CreateNewPersonGroup.json
      summary: Microsoft Azure Put Persongroups Persongroupid
      tags:
        - Persongroups
    delete:
      description: >-
        Delete an existing person group. Persisted face features of all people
        in the person group will also be deleted.
      operationId: microsoftAzurePersongroupDelete
      parameters:
        - $ref: '#/parameters/personGroupId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete a person group example:
          $ref: ./examples/DeletePersonGroup.json
      summary: Microsoft Azure Delete Persongroups Persongroupid
      tags:
        - Persongroups
    get:
      description: >-
        Retrieve person group name, userData and recognitionModel. To get person
        information under this personGroup, use [PersonGroup Person -
        List](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/list).
      operationId: microsoftAzurePersongroupGet
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns the person group's information.
          schema:
            $ref: '#/definitions/PersonGroup'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get person group example:
          $ref: ./examples/GetPersonGroup.json
      summary: Microsoft Azure Get Persongroups Persongroupid
      tags:
        - Persongroups
    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: microsoftAzurePersongroupUpdate
      parameters:
        - $ref: '#/parameters/personGroupId'
        - name: body
          description: Request body for updating person group.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update person group example:
          $ref: ./examples/UpdatePersonGroup.json
      summary: Microsoft Azure Patch Persongroups Persongroupid
      tags:
        - Persongroups
  /persongroups/{personGroupId}/training:
    get:
      description: Retrieve the training status of a person group (completed or ongoing).
      operationId: microsoftAzurePersongroupGettrainingstatus
      parameters:
        - $ref: '#/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns the person group's training status.
          schema:
            $ref: '#/definitions/TrainingStatus'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get person group's training status example:
          $ref: ./examples/GetPersonGroupTrainingStatus.json
      summary: Microsoft Azure Get Persongroups Persongroupid Training
      tags:
        - Persongroups
  /persongroups:
    get:
      description: >-
        List person groups’ personGroupId, name, userData and
        recognitionModel.<br>* Person groups are stored in alphabetical order of
        personGroupId.<br>* "start" parameter (string, optional) is a
        user-provided personGroupId value that returned entries have larger ids
        by string comparison. "start" set to empty to indicate return from the
        first item.<br>* "top" parameter (int, optional) specifies the number of
        entries to return. A maximal of 1000 entries can be returned in one
        call. To fetch more, you can specify "start" with the last returned
        entry’s Id of the current call.<br><br>For example, total 5 person
        groups: "group1", ..., "group5".<br> "start=&top=" will return all 5
        groups.<br> "start=&top=2" will return "group1", "group2".<br>
        "start=group2&top=3" will return "group3", "group4", "group5".<br>
      operationId: microsoftAzurePersongroupList
      parameters:
        - name: start
          in: query
          required: false
          description: >-
            List person groups from the least personGroupId greater than the
            "start".
          type: string
          maxLength: 64
        - name: top
          in: query
          required: false
          description: The number of person groups to list.
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
        - $ref: '#/parameters/returnRecognitionModel'
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of person groups and their
            information.
          schema:
            $ref: '#/definitions/PersonGroups'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        List person groups example:
          $ref: ./examples/ListPersonGroups.json
      summary: Microsoft Azure Get Persongroups
      tags:
        - Persongroups
  /persongroups/{personGroupId}/train:
    post:
      description: >-
        Queue a person group training task, the training task may not be started
        immediately.
      operationId: microsoftAzurePersongroupTrain
      parameters:
        - $ref: '#/parameters/personGroupId'
      produces:
        - application/json
      responses:
        '202':
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Queue person group training:
          $ref: ./examples/QueuePersonGroupTraining.json
      summary: Microsoft Azure Post Persongroups Persongroupid Train
      tags:
        - Persongroups
  /facelists/{faceListId}:
    put:
      description: >-
        Create an empty face list with user-specified faceListId, name, an
        optional userData and recognitionModel. Up to 64 face lists are allowed
        in one subscription.<br> Face list is a list of faces, up to 1,000
        faces, and used by [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).<br>
        After creation, user should use [FaceList - Add
        Face](https://docs.microsoft.com/rest/api/faceapi/facelist/addfacefromurl)
        to import the faces. No image will be stored. Only the extracted face
        features are stored on server until [FaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) is
        called.<br> Find Similar is used for scenario like finding
        celebrity-like faces, similar face filtering, or as a light way face
        identification. But if the actual use is to identify person, please use
        [PersonGroup](https://docs.microsoft.com/rest/api/faceapi/persongroup) /
        [LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup)
        and [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>
        Please consider
        [LargeFaceList](https://docs.microsoft.com/rest/api/faceapi/largefacelist)
        when the face number is large. It can support up to 1,000,000
        faces.<br>'recognitionModel' should be specified to associate with this
        face list. The default value for 'recognitionModel' is 'recognition_01',
        if the latest model needed, please explicitly specify the model you need
        in this parameter. New faces that are added to an existing face list
        will use the recognition model that's already associated with the
        collection. Existing face features in a face list can't be updated to
        features extracted by another version of recognition model.<br>Please
        Refer to [Specify a face recognition
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
      operationId: microsoftAzureFacelistCreate
      parameters:
        - $ref: '#/parameters/faceListId'
        - name: body
          description: Request body for creating a face list.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/MetaDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new face list example:
          $ref: ./examples/CreateNewFaceList.json
      summary: Microsoft Azure Put Facelists Facelistid
      tags:
        - Facelists
    get:
      description: >-
        Retrieve a face list’s faceListId, name, userData, recognitionModel and
        faces in the face list.<br>
      operationId: microsoftAzureFacelistGet
      parameters:
        - $ref: '#/parameters/faceListId'
        - $ref: '#/parameters/returnRecognitionModel'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the face list's information.
          schema:
            $ref: '#/definitions/FaceList'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get Face list example:
          $ref: ./examples/GetFaceList.json
      summary: Microsoft Azure Get Facelists Facelistid
      tags:
        - Facelists
    patch:
      description: Update information of a face list.
      operationId: microsoftAzureFacelistUpdate
      parameters:
        - $ref: '#/parameters/faceListId'
        - name: body
          description: Request body for updating a face list.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update face list example:
          $ref: ./examples/UpdateFaceList.json
      summary: Microsoft Azure Patch Facelists Facelistid
      tags:
        - Facelists
    delete:
      description: Delete a specified face list.
      operationId: microsoftAzureFacelistDelete
      parameters:
        - $ref: '#/parameters/faceListId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete face list example:
          $ref: ./examples/DeleteFaceList.json
      summary: Microsoft Azure Delete Facelists Facelistid
      tags:
        - Facelists
  /facelists:
    get:
      description: >-
        List face lists’ faceListId, name, userData and recognitionModel.  <br>To get face information inside faceList use [FaceList -
        Get](https://docs.microsoft.com/rest/api/faceapi/facelist/get)<br>
      operationId: microsoftAzureFacelistList
      parameters:
        - $ref: '#/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns an array of faceList.
          schema:
            $ref: '#/definitions/FaceLists'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        List Face lists example:
          $ref: ./examples/ListFaceLists.json
      summary: Microsoft Azure Get Facelists
      tags:
        - Facelists
  /facelists/{faceListId}/persistedfaces/{persistedFaceId}:
    delete:
      description: >-
        Delete a face from a face list by specified faceListId and
        persistedFaceId.<br> Adding/deleting faces to/from a same face list are
        processed sequentially and to/from different face lists are in parallel.
      operationId: microsoftAzureFacelistDeleteface
      parameters:
        - $ref: '#/parameters/faceListId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete face in face list example:
          $ref: ./examples/DeleteFaceListFace.json
      summary: Microsoft Azure Delete Facelists Facelistid Persistedfaces Persistedfaceid
      tags:
        - Facelists
  /persongroups/{personGroupId}/persons/{personId}/persistedfaces:
    post:
      description: >-
        Add a face to a person into a person group for face identification or
        verification. To deal with an image contains multiple faces, input face
        can be specified as an image with a targetFace rectangle. It returns a
        persistedFaceId representing the added face. No image will be stored.
        Only the extracted face feature will be stored on server until
        [PersonGroup PersonFace -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/deleteface),
        [PersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
        or [PersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
        is called.<br> Note persistedFaceId is different from faceId generated
        by [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*   Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.<br>*   Each person entry can
        hold up to 248 faces.<br>*   JPEG, PNG, GIF (the first frame), and BMP
        format are supported. The allowed image file size is from 1KB to
        6MB.<br>*   "targetFace" rectangle should contain one face. Zero or
        multiple faces will be regarded as an error. If the provided
        "targetFace" rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.<br>*   Out
        of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
        large occlusions will cause failures.<br>*   Adding/deleting faces
        to/from a same person will be processed sequentially. Adding/deleting
        faces to/from different persons are processed in parallel.<br>* The
        minimum detectable face size is 36x36 pixels in an image no larger than
        1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels
        will need a proportionally larger minimum face size.<br>* Different
        'detectionModel' values can be provided. To use and compare different
        detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).
      operationId: microsoftAzurePersongrouppersonAddfacefromurl
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
        - $ref: '#/parameters/detectionModel'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Add Person face example:
          $ref: ./examples/AddPersonGroupPersonFaceFromUrl.json
      summary: Microsoft Azure Post Persongroups Persongroupid Persons Personid Persistedfaces
      tags:
        - Persongroups
  /detect:
    post:
      description: >-
        Detect human faces in an image, return face rectangles, and optionally
        with faceIds, landmarks, and attributes.<br>* No image will be stored.
        Only the extracted face feature will be stored on server. The faceId is
        an identifier of the face feature and will be used in [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify),
        [Face -
        Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface),
        and [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).
        The stored face feature(s) will expire and be deleted at the time
        specified by faceIdTimeToLive after the original detection call.<br>*
        Optional parameters include faceId, landmarks, and attributes.
        Attributes include age, gender, headPose, smile, facialHair, glasses,
        emotion, hair, makeup, occlusion, accessories, blur, exposure, noise,
        mask, and qualityForRecognition. Some of the results returned for
        specific attributes may not be highly accurate.<br>* JPEG, PNG, GIF (the
        first frame), and BMP format are supported. The allowed image file size
        is from 1KB to 6MB.<br>* Up to 100 faces can be returned for an image.
        Faces are ranked by face rectangle size from large to small.<br>* For
        optimal results when querying [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify),
        [Face -
        Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface),
        and [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar)
        ('returnFaceId' is true), please use faces that are: frontal, clear, and
        with a minimum size of 200x200 pixels (100 pixels between eyes).<br>*
        The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.<br>*
        Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).<br><br>*
        Different 'recognitionModel' values are provided. If follow-up
        operations like Verify, Identify, Find Similar are needed, please
        specify the recognition model with 'recognitionModel' parameter. The
        default value for 'recognitionModel' is 'recognition_01', if latest
        model needed, please explicitly specify the model you need in this
        parameter. Once specified, the detected faceIds will be associated with
        the specified recognition model. More details, please refer to [Specify
        a recognition
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
      operationId: microsoftAzureFaceDetectwithurl
      parameters:
        - $ref: '#/parameters/returnFaceId'
        - $ref: '#/parameters/returnFaceLandmarks'
        - $ref: '#/parameters/returnFaceAttributes'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
        - $ref: '#/parameters/recognitionModel'
        - $ref: '#/parameters/returnRecognitionModel'
        - $ref: '#/parameters/detectionModel'
        - $ref: '#/parameters/faceIdTimeToLive'
      consumes:
        - application/json
      produces:
        - application/json
      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.
          schema:
            $ref: '#/definitions/DetectedFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Detect with url example:
          $ref: ./examples/DetectWithUrl.json
      summary: Microsoft Azure Post Detect
      tags:
        - Detect
  /facelists/{faceListId}/persistedfaces:
    post:
      description: >-
        Add a face to a specified face list, up to 1,000 faces.<br> To deal with
        an image contains multiple faces, input face can be specified as an
        image with a targetFace rectangle. It returns a persistedFaceId
        representing the added face. No image will be stored. Only the extracted
        face feature will be stored on server until [FaceList - Delete
        Face](https://docs.microsoft.com/rest/api/faceapi/facelist/deleteface)
        or [FaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) is
        called.<br> Note persistedFaceId is different from faceId generated by
        [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*
        Higher face image quality means better detection and recognition
        precision. Please consider high-quality faces: frontal, clear, and face
        size is 200x200 pixels (100 pixels between eyes) or bigger.<br>* JPEG,
        PNG, GIF (the first frame), and BMP format are supported. The allowed
        image file size is from 1KB to 6MB.<br>* "targetFace" rectangle should
        contain one face. Zero or multiple faces will be regarded as an error.
        If the provided "targetFace" rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.<br>* Out
        of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
        large occlusions will cause failures.<br>* Adding/deleting faces to/from
        a same face list are processed sequentially and to/from different face
        lists are in parallel.<br>* The minimum detectable face size is 36x36
        pixels in an image no larger than 1920x1080 pixels. Images with
        dimensions higher than 1920x1080 pixels will need a proportionally
        larger minimum face size.<br>* Different 'detectionModel' values can be
        provided. To use and compare different detection models, please refer to
        [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).
      operationId: microsoftAzureFacelistAddfacefromurl
      parameters:
        - $ref: '#/parameters/faceListId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
        - $ref: '#/parameters/detectionModel'
      produces:
        - application/json
      consumes:
        - application/json
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create face list face example:
          $ref: ./examples/AddFaceListFaceFromUrl.json
      summary: Microsoft Azure Post Facelists Facelistid Persistedfaces
      tags:
        - Facelists
  /largepersongroups/{largePersonGroupId}/persons:
    post:
      description: Create a new person in a specified large person group.
      operationId: microsoftAzureLargepersongrouppersonCreate
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - name: body
          description: Request body for creating new person.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns a new personId created.
          schema:
            $ref: '#/definitions/Person'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new person for large person group example:
          $ref: ./examples/CreateNewLargePersonGroupPerson.json
      summary: Microsoft Azure Post Largepersongroups Largepersongroupid Persons
      tags:
        - Largepersongroups
    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: microsoftAzureLargepersongrouppersonList
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - name: start
          description: Starting person id to return (used to list a range of persons).
          in: query
          required: false
          type: string
        - name: top
          description: >-
            Number of persons to return starting with the person id indicated by
            the 'start' parameter.
          in: query
          required: false
          type: integer
          minimum: 1
          maximum: 1000
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of person information that belong
            to the large person group.
          schema:
            $ref: '#/definitions/Persons'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        List persons in person group:
          $ref: ./examples/ListLargePersonGroupPersons.json
      summary: Microsoft Azure Get Largepersongroups Largepersongroupid Persons
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}/persons/{personId}:
    delete:
      description: >-
        Delete an existing person from a large person group. The
        persistedFaceId, userData, person name and face feature in the person
        entry will all be deleted.
      operationId: microsoftAzureLargepersongrouppersonDelete
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete an existing person example:
          $ref: ./examples/DeleteLargePersonGroupPerson.json
      summary: Microsoft Azure Delete Largepersongroups Largepersongroupid Persons Personid
      tags:
        - Largepersongroups
    get:
      description: >-
        Retrieve a person's name and userData, and the persisted faceIds
        representing the registered person face feature.
      operationId: microsoftAzureLargepersongrouppersonGet
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the person's information.
          schema:
            $ref: '#/definitions/Person'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get person example:
          $ref: ./examples/GetLargePersonGroupPerson.json
      summary: Microsoft Azure Get Largepersongroups Largepersongroupid Persons Personid
      tags:
        - Largepersongroups
    patch:
      description: Update name or userData of a person.
      operationId: microsoftAzureLargepersongrouppersonUpdate
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - name: body
          description: Request body for person update operation.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update person example:
          $ref: ./examples/UpdateLargePersonGroupPerson.json
      summary: Microsoft Azure Patch Largepersongroups Largepersongroupid Persons Personid
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}:
    delete:
      description: >-
        Delete a face from a person in a large person group by specified
        largePersonGroupId, personId and persistedFaceId.<br> Adding/deleting
        faces to/from a same person will be processed sequentially.
        Adding/deleting faces to/from different persons are processed in
        parallel.
      operationId: microsoftAzureLargepersongrouppersonDeleteface
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete face from person example:
          $ref: ./examples/DeleteLargePersonGroupPersonFace.json
      summary: >-
        Microsoft Azure Delete Largepersongroups Largepersongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Largepersongroups
    get:
      description: >-
        Retrieve information about a persisted face (specified by
        persistedFaceId, personId and its belonging largePersonGroupId).
      operationId: microsoftAzureLargepersongrouppersonGetface
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns target persisted face's information
            (persistedFaceId and userData).
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get persisted face example:
          $ref: ./examples/GetLargePersonGroupPersistedFace.json
      summary: >-
        Microsoft Azure Get Largepersongroups Largepersongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Largepersongroups
    patch:
      description: Update a person persisted face's userData field.
      operationId: microsoftAzureLargepersongrouppersonUpdateface
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/persistedFaceId'
        - name: body
          description: Request body for updating persisted face.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/UpdateFaceRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update person face example:
          $ref: ./examples/UpdateLargePersonGroupPersonFace.json
      summary: >-
        Microsoft Azure Patch Largepersongroups Largepersongroupid Persons Personid Persistedfaces Persistedfaceid
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}:
    put:
      description: >-
        Create a new large person group with user-specified largePersonGroupId,
        name, an optional userData and recognitionModel.<br> A large person
        group is the container of the uploaded person data, including face
        recognition feature, and up to 1,000,000<br>people.<br> After creation,
        use [LargePersonGroup Person -
        Create](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/create)
        to add person into the group, and call [LargePersonGroup -
        Train](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/train)
        to get this group ready for [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>
        No image will be stored. Only the person's extracted face features and
        userData will be stored on server until [LargePersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/delete)
        or [LargePersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/delete)
        is called.<br>'recognitionModel' should be specified to associate with
        this large person group. The default value for 'recognitionModel' is
        'recognition_01', if the latest model needed, please explicitly specify
        the model you need in this parameter. New faces that are added to an
        existing large person group will use the recognition model that's
        already associated with the collection. Existing face features in a
        large person group can't be updated to features extracted by another
        version of recognition model. Please refer to [Specify a face
        recognition
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).<br><br>Large
        person group quota:<br>* Free-tier subscription quota: 1,000 large
        person groups.<br>* S0-tier subscription quota: 1,000,000 large person
        groups.
      operationId: microsoftAzureLargepersongroupCreate
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - name: body
          description: Request body for creating new large person group.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/MetaDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new large person group example:
          $ref: ./examples/CreateNewLargePersonGroup.json
      summary: Microsoft Azure Put Largepersongroups Largepersongroupid
      tags:
        - Largepersongroups
    delete:
      description: >-
        Delete an existing large person group. Persisted face features of all
        people in the large person group will also be deleted.
      operationId: microsoftAzureLargepersongroupDelete
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete a large person group example:
          $ref: ./examples/DeleteLargePersonGroup.json
      summary: Microsoft Azure Delete Largepersongroups Largepersongroupid
      tags:
        - Largepersongroups
    get:
      description: >-
        Retrieve the information of a large person group, including its name,
        userData and recognitionModel. This API returns large person group
        information only, use [LargePersonGroup Person -
        List](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/list)
        instead to retrieve person information under the large person group.<br>
      operationId: microsoftAzureLargepersongroupGet
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns the large person group's information.
          schema:
            $ref: '#/definitions/LargePersonGroup'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get large person group example:
          $ref: ./examples/GetLargePersonGroup.json
      summary: Microsoft Azure Get Largepersongroups Largepersongroupid
      tags:
        - Largepersongroups
    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: microsoftAzureLargepersongroupUpdate
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - name: body
          description: Request body for updating large person group.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update large person group example:
          $ref: ./examples/UpdateLargePersonGroup.json
      summary: Microsoft Azure Patch Largepersongroups Largepersongroupid
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}/training:
    get:
      description: >-
        Retrieve the training status of a large person group (completed or
        ongoing).
      operationId: microsoftAzureLargepersongroupGettrainingstatus
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
      responses:
        '200':
          description: A successful call returns the large person group's training status.
          schema:
            $ref: '#/definitions/TrainingStatus'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get large person group's training status example:
          $ref: ./examples/GetLargePersonGroupTrainingStatus.json
      summary: Microsoft Azure Get Largepersongroups Largepersongroupid Training
      tags:
        - Largepersongroups
  /largepersongroups:
    get:
      description: >-
        List all existing large person groups’ largePersonGroupId, name,
        userData and recognitionModel.<br>* Large person groups are stored in
        alphabetical order of largePersonGroupId.<br>* "start" parameter
        (string, optional) is a user-provided largePersonGroupId value that
        returned entries have larger ids by string comparison. "start" set to
        empty to indicate return from the first item.<br>* "top" parameter (int,
        optional) specifies the number of entries to return. A maximal of 1000
        entries can be returned in one call. To fetch more, you can specify
        "start" with the last returned entry’s Id of the current
        call.<br><br>For example, total 5 large person groups: "group1", ...,
        "group5".<br> "start=&top=" will return all 5 groups.<br> "start=&top=2"
        will return "group1", "group2".<br> "start=group2&top=3" will return
        "group3", "group4", "group5".<br>
      operationId: microsoftAzureLargepersongroupList
      parameters:
        - name: start
          in: query
          required: false
          description: >-
            List large person groups from the least largePersonGroupId greater
            than the "start".
          type: string
          maxLength: 64
        - name: top
          in: query
          required: false
          description: The number of large person groups to list.
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
        - $ref: '#/parameters/returnRecognitionModel'
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of large person groups and their
            information.
          schema:
            $ref: '#/definitions/LargePersonGroups'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        List large person groups example:
          $ref: ./examples/ListLargePersonGroups.json
      summary: Microsoft Azure Get Largepersongroups
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}/train:
    post:
      description: >-
        Queue a large person group training task, the training task may not be
        started immediately.
      operationId: microsoftAzureLargepersongroupTrain
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
      produces:
        - application/json
      responses:
        '202':
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Queue large person group training:
          $ref: ./examples/QueueLargePersonGroupTraining.json
      summary: Microsoft Azure Post Largepersongroups Largepersongroupid Train
      tags:
        - Largepersongroups
  /largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces:
    post:
      description: >-
        Add a face to a person into a large person group for face identification
        or verification. To deal with an image contains multiple faces, input
        face can be specified as an image with a targetFace rectangle. It
        returns a persistedFaceId representing the added face. No image will be
        stored. Only the extracted face feature will be stored on server until
        [LargePersonGroup PersonFace -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/deleteface),
        [LargePersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/delete)
        or [LargePersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/delete)
        is called.<br> Note persistedFaceId is different from faceId generated
        by [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*
        Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.<br>* Each person entry can
        hold up to 248 faces.<br>* JPEG, PNG, GIF (the first frame), and BMP
        format are supported. The allowed image file size is from 1KB to
        6MB.<br>* "targetFace" rectangle should contain one face. Zero or
        multiple faces will be regarded as an error. If the provided
        "targetFace" rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.<br>* Out
        of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
        large occlusions will cause failures.<br>* Adding/deleting faces to/from
        a same person will be processed sequentially. Adding/deleting faces
        to/from different persons are processed in parallel.<br>* The minimum
        detectable face size is 36x36 pixels in an image no larger than
        1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels
        will need a proportionally larger minimum face size.<br>* Different
        'detectionModel' values can be provided. To use and compare different
        detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
      operationId: microsoftAzureLargepersongrouppersonAddfacefromurl
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
        - $ref: '#/parameters/detectionModel'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Add Person face example:
          $ref: ./examples/AddLargePersonGroupPersonFaceFromUrl.json
      summary: >-
        Microsoft Azure Post Largepersongroups Largepersongroupid Persons Personid Persistedfaces
      tags:
        - Largepersongroups
  /largefacelists/{largeFaceListId}:
    put:
      description: >-
        Create an empty large face list with user-specified largeFaceListId,
        name, an optional userData and recognitionModel.<br> Large face list is
        a list of faces, up to 1,000,000 faces, and used by [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).<br>
        After creation, user should use [LargeFaceList Face -
        Add](https://docs.microsoft.com/rest/api/faceapi/largefacelist/addfacefromurl)
        to import the faces and [LargeFaceList -
        Train](https://docs.microsoft.com/rest/api/faceapi/largefacelist/train)
        to make it ready for [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).
        No image will be stored. Only the extracted face features are stored on
        server until [LargeFaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/delete)
        is called.<br> Find Similar is used for scenario like finding
        celebrity-like faces, similar face filtering, or as a light way face
        identification. But if the actual use is to identify person, please use
        [PersonGroup](https://docs.microsoft.com/rest/api/faceapi/persongroup) /
        [LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup)
        and [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>'recognitionModel'
        should be specified to associate with this large face list. The default
        value for 'recognitionModel' is 'recognition_01', if the latest model
        needed, please explicitly specify the model you need in this parameter.
        New faces that are added to an existing large face list will use the
        recognition model that's already associated with the collection.
        Existing face features in a large face list can't be updated to features
        extracted by another version of recognition model. Please refer to
        [Specify a recognition
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).<br><br>Large
        face list quota:<br>* Free-tier subscription quota: 64 large face
        lists.<br>* S0-tier subscription quota: 1,000,000 large face lists.
      operationId: microsoftAzureLargefacelistCreate
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - name: body
          description: Request body for creating a large face list.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/MetaDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create new large face list example:
          $ref: ./examples/CreateNewLargeFaceList.json
      summary: Microsoft Azure Put Largefacelists Largefacelistid
      tags:
        - Largefacelists
    get:
      description: >-
        Retrieve a large face list’s largeFaceListId, name, userData and
        recognitionModel.
      operationId: microsoftAzureLargefacelistGet
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/returnRecognitionModel'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the large face list's information.
          schema:
            $ref: '#/definitions/LargeFaceList'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get large face list example:
          $ref: ./examples/GetLargeFaceList.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid
      tags:
        - Largefacelists
    patch:
      description: Update information of a large face list.
      operationId: microsoftAzureLargefacelistUpdate
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - name: body
          description: Request body for updating a large face list.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/NameAndUserDataContract'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update large face list example:
          $ref: ./examples/UpdateLargeFaceList.json
      summary: Microsoft Azure Patch Largefacelists Largefacelistid
      tags:
        - Largefacelists
    delete:
      description: Delete a specified large face list.
      operationId: microsoftAzureLargefacelistDelete
      parameters:
        - $ref: '#/parameters/largeFaceListId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete large face list example:
          $ref: ./examples/DeleteLargeFaceList.json
      summary: Microsoft Azure Delete Largefacelists Largefacelistid
      tags:
        - Largefacelists
  /largefacelists/{largeFaceListId}/training:
    get:
      description: >-
        Retrieve the training status of a large face list (completed or
        ongoing).
      operationId: microsoftAzureLargefacelistGettrainingstatus
      parameters:
        - $ref: '#/parameters/largeFaceListId'
      responses:
        '200':
          description: A successful call returns the large face list's training status.
          schema:
            $ref: '#/definitions/TrainingStatus'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get large face list's training status example:
          $ref: ./examples/GetLargeFaceListTrainingStatus.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Training
      tags:
        - Largefacelists
  /largefacelists:
    get:
      description: >-
        List large face lists’ information of largeFaceListId, name, userData
        and recognitionModel.  <br>To get face information inside largeFaceList
        use [LargeFaceList Face -
        Get](https://docs.microsoft.com/rest/api/faceapi/largefacelist/getface)<br>*
        Large face lists are stored in alphabetical order of
        largeFaceListId.<br>* "start" parameter (string, optional) is a
        user-provided largeFaceListId value that returned entries have larger
        ids by string comparison. "start" set to empty to indicate return from
        the first item.<br>* "top" parameter (int, optional) specifies the
        number of entries to return. A maximal of 1000 entries can be returned
        in one call. To fetch more, you can specify "start" with the last
        returned entry’s Id of the current call.<br><br>For example, total 5
        large person lists: "list1", ..., "list5".<br> "start=&top=" will return
        all 5 lists.<br> "start=&top=2" will return "list1", "list2".<br>
        "start=list2&top=3" will return "list3", "list4", "list5".<br>
      operationId: microsoftAzureLargefacelistList
      parameters:
        - $ref: '#/parameters/returnRecognitionModel'
        - name: start
          description: >-
            Starting large face list id to return (used to list a range of large
            face lists).
          in: query
          required: false
          type: string
        - name: top
          description: >-
            Number of large face lists to return starting with the large face
            list id indicated by the 'start' parameter.
          in: query
          required: false
          type: integer
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: A successful call returns an array of largeFaceList.
          schema:
            $ref: '#/definitions/LargeFaceLists'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        List large face lists example:
          $ref: ./examples/ListLargeFaceLists.json
      summary: Microsoft Azure Get Largefacelists
      tags:
        - Largefacelists
  /largefacelists/{largeFaceListId}/train:
    post:
      description: >-
        Queue a large face list training task, the training task may not be
        started immediately.
      operationId: microsoftAzureLargefacelistTrain
      parameters:
        - $ref: '#/parameters/largeFaceListId'
      produces:
        - application/json
      responses:
        '202':
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Queue large face list training:
          $ref: ./examples/QueueLargeFaceListTraining.json
      summary: Microsoft Azure Post Largefacelists Largefacelistid Train
      tags:
        - Largefacelists
  /largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}:
    delete:
      description: >-
        Delete a face from a large face list by specified largeFaceListId and
        persistedFaceId.<br> Adding/deleting faces to/from a same large face
        list are processed sequentially and to/from different large face lists
        are in parallel.
      operationId: microsoftAzureLargefacelistDeleteface
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete face in large face list example:
          $ref: ./examples/DeleteLargeFaceListFace.json
      summary: Microsoft Azure Delete Largefacelists Largefacelistid Persistedfaces Persistedfaceid
      tags:
        - Largefacelists
    get:
      description: >-
        Retrieve information about a persisted face (specified by
        persistedFaceId and its belonging largeFaceListId).
      operationId: microsoftAzureLargefacelistGetface
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/persistedFaceId'
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns target persisted face's information
            (persistedFaceId and userData).
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get persisted face example:
          $ref: ./examples/GetLargeFaceListPersistedFace.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Persistedfaces Persistedfaceid
      tags:
        - Largefacelists
    patch:
      description: Update a persisted face's userData field.
      operationId: microsoftAzureLargefacelistUpdateface
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/persistedFaceId'
        - name: body
          description: Request body for updating persisted face.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/UpdateFaceRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update face example:
          $ref: ./examples/UpdateLargeFaceListFace.json
      summary: Microsoft Azure Patch Largefacelists Largefacelistid Persistedfaces Persistedfaceid
      tags:
        - Largefacelists
  /largefacelists/{largeFaceListId}/persistedfaces:
    post:
      description: >-
        Add a face to a specified large face list, up to 1,000,000 faces.<br> To
        deal with an image contains multiple faces, input face can be specified
        as an image with a targetFace rectangle. It returns a persistedFaceId
        representing the added face. No image will be stored. Only the extracted
        face feature will be stored on server until [LargeFaceList Face -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/deleteface)
        or [LargeFaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/delete)
        is called.<br> Note persistedFaceId is different from faceId generated
        by [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*
        Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.<br>* JPEG, PNG, GIF (the
        first frame), and BMP format are supported. The allowed image file size
        is from 1KB to 6MB.<br>* "targetFace" rectangle should contain one face.
        Zero or multiple faces will be regarded as an error. If the provided
        "targetFace" rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.<br>* Out
        of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
        large occlusions will cause failures.<br>* Adding/deleting faces to/from
        a same face list are processed sequentially and to/from different face
        lists are in parallel.<br>* The minimum detectable face size is 36x36
        pixels in an image no larger than 1920x1080 pixels. Images with
        dimensions higher than 1920x1080 pixels will need a proportionally
        larger minimum face size.<br>* Different 'detectionModel' values can be
        provided. To use and compare different detection models, please refer to
        [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)<br><br>Quota:<br>*
        Free-tier subscription quota: 1,000 faces per large face list.<br>*
        S0-tier subscription quota: 1,000,000 faces per large face list.
      operationId: microsoftAzureLargefacelistAddfacefromurl
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
        - $ref: '#/parameters/detectionModel'
      produces:
        - application/json
      consumes:
        - application/json
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Create large face list face example:
          $ref: ./examples/AddLargeFaceListFaceFromUrl.json
      summary: Microsoft Azure Post Largefacelists Largefacelistid Persistedfaces
      tags:
        - Largefacelists
    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: microsoftAzureLargefacelistListfaces
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - name: start
          description: Starting face id to return (used to list a range of faces).
          in: query
          required: false
          type: string
        - name: top
          description: >-
            Number of faces to return starting with the face id indicated by the
            'start' parameter.
          in: query
          required: false
          type: integer
          minimum: 1
          maximum: 1000
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of face information that belong
            to the large face list.
          schema:
            $ref: '#/definitions/PersistedFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        List faces in large face list:
          $ref: ./examples/ListLargeFaceListFaces.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Persistedfaces
      tags:
        - Largefacelists
  /snapshots:
    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>The 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>Taking 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>Snapshot 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>Snapshots
        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>Taking 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>* Free-tier subscription quota: 100
        take operations per month.<br>* S0-tier subscription quota: 100 take
        operations per day.
      operationId: microsoftAzureSnapshotTake
      parameters:
        - name: body
          description: Request body for taking a snapshot.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/TakeSnapshotRequest'
      consumes:
        - application/json
      produces:
        - application/json
      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.
              type: string
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Take a snapshot example:
          $ref: ./examples/TakeSnapshot.json
      summary: Microsoft Azure Post Snapshots
      tags:
        - 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: microsoftAzureSnapshotList
      parameters:
        - name: type
          description: User specified object type as a search filter.
          in: query
          required: false
          type: string
          x-ms-enum:
            name: SnapshotObjectType
            modelAsString: false
          enum:
            - FaceList
            - LargeFaceList
            - LargePersonGroup
            - PersonGroup
        - $ref: '#/parameters/applyScope'
      responses:
        '200':
          description: >-
            A successful call returns an array of snapshots with snapshot
            information.
          schema:
            $ref: '#/definitions/Snapshots'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        List snapshots example:
          $ref: ./examples/ListSnapshots.json
      summary: Microsoft Azure Get Snapshots
      tags:
        - Snapshots
  /snapshots/{snapshotId}:
    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: microsoftAzureSnapshotGet
      parameters:
        - $ref: '#/parameters/snapshotId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the snapshot's information.
          schema:
            $ref: '#/definitions/Snapshot'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Get snapshot example:
          $ref: ./examples/GetSnapshot.json
      summary: Microsoft Azure Get Snapshots Snapshotid
      tags:
        - Snapshots
    patch:
      description: >-
        Update the information of a snapshot. Only the source subscription who
        took the snapshot can update the snapshot.
      operationId: microsoftAzureSnapshotUpdate
      parameters:
        - $ref: '#/parameters/snapshotId'
        - name: body
          description: Request body for updating a snapshot.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/UpdateSnapshotRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Update snapshot example:
          $ref: ./examples/UpdateSnapshot.json
      summary: Microsoft Azure Patch Snapshots Snapshotid
      tags:
        - Snapshots
    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: microsoftAzureSnapshotDelete
      parameters:
        - $ref: '#/parameters/snapshotId'
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Delete snapshot example:
          $ref: ./examples/DeleteSnapshot.json
      summary: Microsoft Azure Delete Snapshots Snapshotid
      tags:
        - Snapshots
  /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>The 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>Applying 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>Snapshot
        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>Snapshots 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>Applying 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>One 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>*
        Free-tier subscription quota: 100 apply operations per month.<br>*
        S0-tier subscription quota: 100 apply operations per day.
      operationId: microsoftAzureSnapshotApply
      parameters:
        - $ref: '#/parameters/snapshotId'
        - name: body
          description: Request body for applying a snapshot.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/ApplySnapshotRequest'
      consumes:
        - application/json
      produces:
        - application/json
      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.
              type: string
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Apply snapshot example:
          $ref: ./examples/ApplySnapshot.json
      summary: Microsoft Azure Post Snapshots Snapshotid Apply
      tags:
        - Snapshots
  /operations/{operationId}:
    get:
      description: Get status of a long running operation.
      operationId: microsoftAzureSnapshotGetoperationstatus
      parameters:
        - $ref: '#/parameters/operationId'
      responses:
        '200':
          description: A successful call returns the operation's status.
          schema:
            $ref: '#/definitions/OperationStatus'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Get snapshot operation status example:
          $ref: ./examples/GetSnapshotOperationStatus.json
      summary: Microsoft Azure Get Operations Operationid
      tags:
        - Operations
  /persons:
    get:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Retrieve List Of Person Information In Person Directory'
      operationId: microsoftAzurePersondirectoryGetpersons
      produces:
        - application/json
      parameters:
        - in: query
          name: start
          format: uuid
          description: >-
            List persons from the least personId greater than the "start". It
            contains no more than 64 characters. Default is empty.
          type: string
        - in: query
          name: top
          description: >-
            The number of persons to list, ranging in [1, 1000]. Default is
            1000.
          type: string
      responses:
        '200':
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/EnrollmentResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Get person directory persons example:
          $ref: ./examples/GetPersonDirectoryPersons.json
      description: Needs a more full description created.
    post:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Creates A New Person In Person Directory'
      operationId: microsoftAzurePersondirectoryCreateperson
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/EnrollmentRequest'
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
          schema:
            $ref: '#/definitions/PersonCreationResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/CreateNewPersonDirectoryPerson.json
      description: Needs a more full description created.
  /persons/{personId}:
    patch:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Update Name Or Userdata Of A Person'
      operationId: microsoftAzurePersondirectoryUpdateperson
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Person id to update.
          required: true
          format: uuid
          type: string
        - in: body
          name: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/EnrollmentRequest'
      responses:
        '200':
          description: Success
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/UpdatePersonDirectoryPerson.json
      description: Needs a more full description created.
    delete:
      tags:
        - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Person From Person Directory \r\nthe Persistedfaceid, Userdata, Person Name And Face Feature S In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeleteperson
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Person id to delete.
          required: true
          format: uuid
          type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Delete person from person directory example:
          $ref: ./examples/DeletePersonDirectoryPerson.json
      description: Needs a more full description created.
    get:
      tags:
        - PersonDirectory
      summary: >-
        Microsoft Azure Retrieve A Person S Name And Userdata, And The Persisted Faceids Representing The Registered Person Face Feature S
      operationId: microsoftAzurePersondirectoryGetperson
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Person id.
          required: true
          format: uuid
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/EnrolledPerson'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Get person from person directory example:
          $ref: ./examples/GetPersonDirectoryPerson.json
      description: Needs a more full description created.
  /persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces:
    post:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Add A New Face To Person'
      operationId: microsoftAzurePersondirectoryAddpersonfacefromurl
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Person id.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: Recognition model string.
          required: true
          type: string
        - in: query
          name: detectionModel
          description: Detection model string.
          type: string
        - in: query
          name: userData
          description: User data of person face.
          type: string
        - in: query
          name: targetFace
          description: Target face.
          type: string
        - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
          schema:
            $ref: '#/definitions/EnrollmentPrintResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Add face to person in person directory example:
          $ref: ./examples/AddPersonDirectoryPersonFaceFromUrl.json
      description: Needs a more full description created.
    get:
      tags:
        - PersonDirectory
      summary: >-
        Microsoft Azure Retrieve Person Face Information The Persisted Person Face Is Specified By Its Personid And Persistedfaceid
      operationId: microsoftAzurePersondirectoryGetpersonfaces
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Target person to get persistedFaceIds from.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: The 'recognitionModel' associated with this persisted face.
          required: true
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersonResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Get person face in person directory example:
          $ref: ./examples/GetPersonDirectoryPersonFaces.json
      description: Needs a more full description created.
  /persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces/{persistedFaceId}:
    delete:
      tags:
        - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Person Face From Person Directory \r\nthe Persistedfaceid, Userdata, And Face Feature In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeletepersonface
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Person id.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: Recognition model string.
          required: true
          type: string
        - in: path
          name: persistedFaceId
          description: Persisted face id to delete.
          required: true
          format: uuid
          type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Delete face from person directory person example:
          $ref: ./examples/DeletePersonDirectoryPersonFace.json
      description: Needs a more full description created.
    get:
      tags:
        - PersonDirectory
      summary: >-
        Microsoft Azure Retrieve Person Face Information The Persisted Person Face Is Specified By Its Personid And Persistedfaceid
      operationId: microsoftAzurePersondirectoryGetpersonface
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Target person to get face from.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: The 'recognitionModel' associated with this persisted face.
          required: true
          type: string
        - in: path
          name: persistedFaceId
          description: Target person face id to get.
          required: true
          format: uuid
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersistedFaceResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Get person directory person face example:
          $ref: ./examples/GetPersonDirectoryPersonFace.json
      description: Needs a more full description created.
    patch:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Update The Data Of A Person Face'
      operationId: microsoftAzurePersondirectoryUpdatepersonface
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Target person to update face from.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: The 'recognitionModel' associated with this persisted face.
          required: true
          type: string
        - in: path
          name: persistedFaceId
          description: PersistedFaceId created from Person Face Create
          required: true
          format: uuid
          type: string
        - in: body
          name: body
          description: Target person face to update.
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/PersistedFaceWithType'
      responses:
        '200':
          description: Success
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Update face from person directory person example:
          $ref: ./examples/UpdatePersonDirectoryPersonFace.json
      description: Needs a more full description created.
  /dynamicpersongroups/{dynamicPersonGroupId}:
    put:
      tags:
        - PersonDirectory
      summary: "Microsoft Azure Creates A New Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata \r\na Dynamic Person Group Is A Container That References Persons \r\nafter Creation, Use \"dynamicpersongroup  Update\" To Add Remove Persons Into The Search Space \r\ndynamicpersongroup And Userdata Will Be Stored On Server Until Dynamicpersongroup Delete Is Called"
      operationId: microsoftAzurePersondirectoryCreatedynamicpersongroup
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: dynamicPersonGroupId
          description: >-
            User provided dynamic person group Id. Valid format should be a
            string composed by numbers, English letters in lower case, '-', '_',
            and no longer than 64 characters.
          required: true
          type: string
        - in: body
          name: body
          description: ''
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/DynamicPersonGroupCreateRequest'
      responses:
        '200':
          description: Success
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create dynamic person group example:
          $ref: ./examples/CreateNewDynamicPersonGroup.json
      description: Needs a more full description created.
    patch:
      tags:
        - PersonDirectory
      summary: >-
        Microsoft Azure Updates An Existing Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata
      operationId: microsoftAzurePersondirectoryUpdatedynamicpersongroup
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: dynamicPersonGroupId
          description: User provided dynamic person group Id.
          required: true
          type: string
        - in: body
          name: body
          description: ''
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/DynamicPersonGroupUpdateRequest'
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Update dynamic person group example:
          $ref: ./examples/UpdateDynamicPersonGroup.json
      description: Needs a more full description created.
    get:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Get Metadata On A Dynamic Person Group'
      operationId: microsoftAzurePersondirectoryGetdynamicpersongroup
      produces:
        - application/json
      parameters:
        - in: path
          name: dynamicPersonGroupId
          description: User provided dynamic person group id
          required: true
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DynamicPersonGroupGetResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Get dynamic person group example:
          $ref: ./examples/GetDynamicPersonGroup.json
      description: Needs a more full description created.
    delete:
      tags:
        - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Dynamic Person Group \r\nnote That Persons Are Not Deleted With This Operation To Delete Person Call Person Delete"
      operationId: microsoftAzurePersondirectoryDeletedynamicpersongroup
      produces:
        - application/json
      parameters:
        - in: path
          name: dynamicPersonGroupId
          description: User provided dynamic person group Id.
          required: true
          type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Delete dynamic person group example:
          $ref: ./examples/DeleteDynamicPersonGroup.json
      description: Needs a more full description created.
  /dynamicpersongroups/{dynamicPersonGroupId}/persons:
    get:
      tags:
        - PersonDirectory
      summary: >-
        Microsoft Azure Retrieve List Of Persons Referenced In A Given Dynamicpersongroup Person Directory
      operationId: microsoftAzurePersondirectoryListdynamicpersongrouppersons
      produces:
        - application/json
      parameters:
        - in: path
          name: dynamicPersonGroupId
          description: Dynamic person group Id to list persons from
          required: true
          type: string
        - in: query
          name: start
          description: >-
            List persons from the least personId greater than the "start". It
            contains no more than 64 characters. Default is empty.
          format: uuid
          type: string
        - in: query
          name: top
          description: >-
            The number of persons to list, ranging in [1, 1000]. Default is
            1000.
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DynamicPersonGroupListPersonsResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        List dynamic person group persons example:
          $ref: ./examples/ListDynamicPersonGroupPersons.json
      description: Needs a more full description created.
  /dynamicpersongroups:
    get:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure Retrieve List Of Dynamic Person Groups In Person Directory'
      operationId: microsoftAzurePersondirectoryListdynamicpersongroups
      produces:
        - application/json
      parameters:
        - in: query
          name: start
          description: >-
            List dynamicPersonGroupId from the least dynamicPersonGroupId
            greater than the "start". It contains no more than 64 characters.
            Default is empty.
          type: string
        - in: query
          name: top
          description: >-
            The number of dynamicPersonGroups to list, ranging in [1, 1000].
            Default is 1000.
          type: string
      responses:
        '200':
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/DynamicPersonGroupGetResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        List dynamic person groups example:
          $ref: ./examples/ListDynamicPersonGroups.json
      description: Needs a more full description created.
  /persons/{personId}/dynamicPersonGroupReferences:
    get:
      tags:
        - PersonDirectory
      summary: 'Microsoft Azure List The Dynamic Person Groups That A Person Has Been Referenced In'
      operationId: microsoftAzurePersondirectoryListdynamicpersongrouppersonreferences
      produces:
        - application/json
      parameters:
        - in: path
          name: personId
          description: Valid PersonId created from Person Create.
          required: true
          format: uuid
          type: string
        - in: query
          name: start
          description: >-
            List dynamic person group id from the least dynamicPersonGroupId
            greater than the "start". It contains no more than 64 characters.
            Default is empty.
          type: string
        - in: query
          name: top
          description: >-
            The number of dynamicPersonGroupId to list, ranging in [1, 1000].
            Default is 1000.
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersonDynamicPersonGroupReferenceResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        List dynamic person group references example:
          $ref: ./examples/ListDynamicPersonGroupReferences.json
      description: Needs a more full description created.
x-ms-paths:
  /verify?overload=person:
    post:
      description: >-
        Verify whether two faces belong to a same person. Compares a face Id
        with a Person Id
      operationId: Face_VerifyFaceToPerson
      parameters:
        - name: body
          description: Request body for face to person verification.
          in: body
          required: true
          x-ms-client-flatten: true
          schema:
            $ref: '#/definitions/VerifyFaceToPersonRequest'
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: A successful call returns the verification result.
          schema:
            $ref: '#/definitions/VerifyResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Verify face to person example:
          $ref: ./examples/VerifyFaceToPerson.json
  /detect?overload=stream:
    post:
      description: >-
        Detect human faces in an image, return face rectangles, and optionally
        with faceIds, landmarks, and attributes.<br />

        * No image will be stored. Only the extracted face feature will be
        stored on server. The faceId is an identifier of the face feature and
        will be used in [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify),
        [Face -
        Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface),
        and [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).
        The stored face feature(s) will expire and be deleted at the time
        specified by faceIdTimeToLive after the original detection call.

        * Optional parameters include faceId, landmarks, and attributes.
        Attributes include age, gender, headPose, smile, facialHair, glasses,
        emotion, hair, makeup, occlusion, accessories, blur, exposure, noise,
        mask, and qualityForRecognition. Some of the results returned for
        specific attributes may not be highly accurate.

        * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
        allowed image file size is from 1KB to 6MB.

        * Up to 100 faces can be returned for an image. Faces are ranked by face
        rectangle size from large to small.

        * For optimal results when querying [Face -
        Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify),
        [Face -
        Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface),
        and [Face - Find
        Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar)
        ('returnFaceId' is true), please use faces that are: frontal, clear, and
        with a minimum size of 200x200 pixels (100 pixels between eyes).

        * The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.

        * Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)

        * Different 'recognitionModel' values are provided. If follow-up
        operations like Verify, Identify, Find Similar are needed, please
        specify the recognition model with 'recognitionModel' parameter. The
        default value for 'recognitionModel' is 'recognition_01', if latest
        model needed, please explicitly specify the model you need in this
        parameter. Once specified, the detected faceIds will be associated with
        the specified recognition model. More details, please refer to [Specify
        a recognition
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
      operationId: Face_DetectWithStream
      parameters:
        - $ref: '#/parameters/returnFaceId'
        - $ref: '#/parameters/returnFaceLandmarks'
        - $ref: '#/parameters/returnFaceAttributes'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
        - $ref: '#/parameters/recognitionModel'
        - $ref: '#/parameters/returnRecognitionModel'
        - $ref: '#/parameters/detectionModel'
        - $ref: '#/parameters/faceIdTimeToLive'
      consumes:
        - application/octet-stream
      produces:
        - application/json
      responses:
        '200':
          description: >-
            A successful call returns an array of face entries ranked by face
            rectangle size in descending order. An empty response indicates no
            faces detected.
          schema:
            $ref: '#/definitions/DetectedFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Detect with stream example:
          $ref: ./examples/DetectWithStream.json
  /persongroups/{personGroupId}/persons/{personId}/persistedfaces?overload=stream:
    post:
      description: >-
        Add a face to a person into a person group for face identification or
        verification. To deal with an image contains multiple faces, input face
        can be specified as an image with a targetFace rectangle. It returns a
        persistedFaceId representing the added face. No image will be stored.
        Only the extracted face feature will be stored on server until
        [PersonGroup PersonFace -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/deleteface),
        [PersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
        or [PersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
        is called.

        <br /> Note persistedFaceId is different from faceId generated by [Face
        -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).

        *   Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.

        *   Each person entry can hold up to 248 faces.

        *   JPEG, PNG, GIF (the first frame), and BMP format are supported. The
        allowed image file size is from 1KB to 6MB.

        *   "targetFace" rectangle should contain one face. Zero or multiple
        faces will be regarded as an error. If the provided "targetFace"
        rectangle is not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.

        *   Out of detectable face size (36x36 - 4096x4096 pixels), large
        head-pose, or large occlusions will cause failures.

        *   Adding/deleting faces to/from a same person will be processed
        sequentially. Adding/deleting faces to/from different persons are
        processed in parallel.

        * The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.

        * Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).
      operationId: PersonGroupPerson_AddFaceFromStream
      parameters:
        - $ref: '#/parameters/personGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
        - $ref: '#/parameters/detectionModel'
      produces:
        - application/json
      consumes:
        - application/octet-stream
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Add face to person with stream example:
          $ref: ./examples/AddPersonGroupPersonFaceFromStream.json
  /facelists/{faceListId}/persistedfaces?overload=stream:
    post:
      description: >-
        Add a face to a specified face list, up to 1,000 faces.

        <br /> To deal with an image contains multiple faces, input face can be
        specified as an image with a targetFace rectangle. It returns a
        persistedFaceId representing the added face. No image will be stored.
        Only the extracted face feature will be stored on server until [FaceList
        - Delete
        Face](https://docs.microsoft.com/rest/api/faceapi/facelist/deleteface)
        or [FaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) is
        called.

        <br /> Note persistedFaceId is different from faceId generated by [Face
        -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).

        * Higher face image quality means better detection and recognition
        precision. Please consider high-quality faces: frontal, clear, and face
        size is 200x200 pixels (100 pixels between eyes) or bigger.

        * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
        allowed image file size is from 1KB to 6MB.

        * "targetFace" rectangle should contain one face. Zero or multiple faces
        will be regarded as an error. If the provided "targetFace" rectangle is
        not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.

        * Out of detectable face size (36x36 - 4096x4096 pixels), large
        head-pose, or large occlusions will cause failures.

        * Adding/deleting faces to/from a same face list are processed
        sequentially and to/from different face lists are in parallel.

        * The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.

        * Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).
      operationId: FaceList_AddFaceFromStream
      parameters:
        - $ref: '#/parameters/faceListId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
        - $ref: '#/parameters/detectionModel'
      consumes:
        - application/octet-stream
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Add face to face list from stream example:
          $ref: ./examples/AddFaceListFaceFromStream.json
  /largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?overload=stream:
    post:
      description: >-
        Add a face to a person into a large person group for face identification
        or verification. To deal with an image contains multiple faces, input
        face can be specified as an image with a targetFace rectangle. It
        returns a persistedFaceId representing the added face. No image will be
        stored. Only the extracted face feature will be stored on server until
        [LargePersonGroup PersonFace -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/deleteface),
        [LargePersonGroup Person -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroupperson/delete)
        or [LargePersonGroup -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/delete)
        is called.

        <br /> Note persistedFaceId is different from faceId generated by [Face
        -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).

        * Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.

        * Each person entry can hold up to 248 faces.

        * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
        allowed image file size is from 1KB to 6MB.

        * "targetFace" rectangle should contain one face. Zero or multiple faces
        will be regarded as an error. If the provided "targetFace" rectangle is
        not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.

        * Out of detectable face size (36x36 - 4096x4096 pixels), large
        head-pose, or large occlusions will cause failures.

        * Adding/deleting faces to/from a same person will be processed
        sequentially. Adding/deleting faces to/from different persons are
        processed in parallel.

        * The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.

        * Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).
      operationId: LargePersonGroupPerson_AddFaceFromStream
      parameters:
        - $ref: '#/parameters/largePersonGroupId'
        - $ref: '#/parameters/personId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
        - $ref: '#/parameters/detectionModel'
      produces:
        - application/json
      consumes:
        - application/octet-stream
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Add face to person with stream example:
          $ref: ./examples/AddLargePersonGroupPersonFaceFromStream.json
  /largefacelists/{largeFaceListId}/persistedfaces?overload=stream:
    post:
      description: >-
        Add a face to a specified large face list, up to 1,000,000 faces.

        <br /> To deal with an image contains multiple faces, input face can be
        specified as an image with a targetFace rectangle. It returns a
        persistedFaceId representing the added face. No image will be stored.
        Only the extracted face feature will be stored on server until
        [LargeFaceList Face -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/deleteface)
        or [LargeFaceList -
        Delete](https://docs.microsoft.com/rest/api/faceapi/largefacelist/delete)
        is called.

        <br /> Note persistedFaceId is different from faceId generated by [Face
        -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).

        * Higher face image quality means better recognition precision. Please
        consider high-quality faces: frontal, clear, and face size is 200x200
        pixels (100 pixels between eyes) or bigger.

        * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
        allowed image file size is from 1KB to 6MB.

        * "targetFace" rectangle should contain one face. Zero or multiple faces
        will be regarded as an error. If the provided "targetFace" rectangle is
        not returned from [Face -
        Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
        there’s no guarantee to detect and add the face successfully.

        * Out of detectable face size (36x36 - 4096x4096 pixels), large
        head-pose, or large occlusions will cause failures.

        * Adding/deleting faces to/from a same face list are processed
        sequentially and to/from different face lists are in parallel.

        * The minimum detectable face size is 36x36 pixels in an image no larger
        than 1920x1080 pixels. Images with dimensions higher than 1920x1080
        pixels will need a proportionally larger minimum face size.

        * Different 'detectionModel' values can be provided. To use and compare
        different detection models, please refer to [How to specify a detection
        model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).


        Quota:

        * Free-tier subscription quota: 1,000 faces per large face list.

        * S0-tier subscription quota: 1,000,000 faces per large face list.
      operationId: LargeFaceList_AddFaceFromStream
      parameters:
        - $ref: '#/parameters/largeFaceListId'
        - $ref: '#/parameters/faceUserData'
        - $ref: '#/parameters/targetFace'
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
        - $ref: '#/parameters/detectionModel'
      consumes:
        - application/octet-stream
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/definitions/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
        - application/json
      x-ms-examples:
        Add face to large face list from stream example:
          $ref: ./examples/AddLargeFaceListFaceFromStream.json
  /persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces?overload=stream:
    post:
      tags:
        - PersonDirectory
      summary: Add a new face to person.
      operationId: PersonDirectory_AddPersonFaceFromStream
      produces:
        - application/json
      consumes:
        - application/octet-stream
      parameters:
        - in: path
          name: personId
          description: Person id.
          required: true
          format: uuid
          type: string
        - in: path
          name: recognitionModel
          description: Recognition model string.
          required: true
          type: string
        - in: query
          name: detectionModel
          description: Detection model string.
          type: string
        - in: query
          name: userData
          description: User data of person face.
          type: string
        - in: query
          name: targetFace
          description: Target face.
          type: string
        - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: >-
                Operation location with an operation id used to track the
                progress of person creation.
              type: string
          schema:
            $ref: '#/definitions/EnrollmentPrintResponse'
        default:
          description: >-
            Response entity accompanying non-successful responses containing
            additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Add face to person directory person with stream example:
          $ref: ./examples/AddPersonDirectoryPersonFaceFromStream.json
definitions:
  APIError:
    type: object
    description: Error information returned by the API
    properties:
      error:
        $ref: '#/definitions/Error'
  Error:
    type: object
    description: Error body.
    properties:
      code:
        type: string
      message:
        type: string
  DetectedFaces:
    type: array
    items:
      $ref: '#/definitions/DetectedFace'
  DetectedFace:
    type: object
    required:
      - faceRectangle
    description: Detected Face object.
    properties:
      faceId:
        type: string
        format: uuid
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
      faceRectangle:
        $ref: '#/definitions/FaceRectangle'
      faceLandmarks:
        $ref: '#/definitions/FaceLandmarks'
      faceAttributes:
        $ref: '#/definitions/FaceAttributes'
  FaceRectangle:
    type: object
    required:
      - width
      - height
      - left
      - top
    description: A rectangle within which a face can be found
    properties:
      width:
        type: integer
        format: int32
        description: The width of the rectangle, in pixels.
      height:
        type: integer
        format: int32
        description: The height of the rectangle, in pixels.
      left:
        type: integer
        format: int32
        description: >-
          The distance from the left edge if the image to the left edge of the
          rectangle, in pixels.
      top:
        type: integer
        format: int32
        description: >-
          The distance from the top edge if the image to the top edge of the
          rectangle, in pixels.
  Coordinate:
    type: object
    required:
      - x
      - 'y'
    description: Coordinates within an image
    properties:
      x:
        type: number
        description: The horizontal component, in pixels.
      'y':
        type: number
        description: The vertical component, in pixels.
  FaceLandmarks:
    type: object
    description: >-
      A collection of 27-point face landmarks pointing to the important
      positions of face components.
    properties:
      pupilLeft:
        $ref: '#/definitions/Coordinate'
      pupilRight:
        $ref: '#/definitions/Coordinate'
      noseTip:
        $ref: '#/definitions/Coordinate'
      mouthLeft:
        $ref: '#/definitions/Coordinate'
      mouthRight:
        $ref: '#/definitions/Coordinate'
      eyebrowLeftOuter:
        $ref: '#/definitions/Coordinate'
      eyebrowLeftInner:
        $ref: '#/definitions/Coordinate'
      eyeLeftOuter:
        $ref: '#/definitions/Coordinate'
      eyeLeftTop:
        $ref: '#/definitions/Coordinate'
      eyeLeftBottom:
        $ref: '#/definitions/Coordinate'
      eyeLeftInner:
        $ref: '#/definitions/Coordinate'
      eyebrowRightInner:
        $ref: '#/definitions/Coordinate'
      eyebrowRightOuter:
        $ref: '#/definitions/Coordinate'
      eyeRightInner:
        $ref: '#/definitions/Coordinate'
      eyeRightTop:
        $ref: '#/definitions/Coordinate'
      eyeRightBottom:
        $ref: '#/definitions/Coordinate'
      eyeRightOuter:
        $ref: '#/definitions/Coordinate'
      noseRootLeft:
        $ref: '#/definitions/Coordinate'
      noseRootRight:
        $ref: '#/definitions/Coordinate'
      noseLeftAlarTop:
        $ref: '#/definitions/Coordinate'
      noseRightAlarTop:
        $ref: '#/definitions/Coordinate'
      noseLeftAlarOutTip:
        $ref: '#/definitions/Coordinate'
      noseRightAlarOutTip:
        $ref: '#/definitions/Coordinate'
      upperLipTop:
        $ref: '#/definitions/Coordinate'
      upperLipBottom:
        $ref: '#/definitions/Coordinate'
      underLipTop:
        $ref: '#/definitions/Coordinate'
      underLipBottom:
        $ref: '#/definitions/Coordinate'
  FaceAttributes:
    type: object
    description: Face Attributes
    properties:
      age:
        type: number
        description: Age in years
      gender:
        type: string
        description: Possible gender of the face.
        x-ms-enum:
          name: Gender
          modelAsString: false
        enum:
          - male
          - female
      smile:
        description: 'Smile intensity, a number between [0,1] '
        $ref: '#/definitions/Level'
      facialHair:
        description: Properties describing facial hair attributes.
        $ref: '#/definitions/FacialHair'
      glasses:
        type: string
        description: Glasses type if any of the face.
        x-ms-enum:
          name: GlassesType
          modelAsString: false
        enum:
          - noGlasses
          - readingGlasses
          - sunglasses
          - swimmingGoggles
      headPose:
        description: Properties indicating head pose of the face.
        $ref: '#/definitions/HeadPose'
      emotion:
        description: >-
          Properties describing facial emotion in form of confidence ranging
          from 0 to 1.
        $ref: '#/definitions/Emotion'
      hair:
        description: Properties describing hair attributes.
        $ref: '#/definitions/Hair'
      makeup:
        description: Properties describing the presence of makeup on a given face.
        $ref: '#/definitions/Makeup'
      occlusion:
        description: Properties describing occlusions on a given face.
        $ref: '#/definitions/Occlusion'
      accessories:
        description: Properties describing any accessories on a given face.
        $ref: '#/definitions/Accessories'
      blur:
        description: Properties describing any presence of blur within the image.
        $ref: '#/definitions/Blur'
      exposure:
        description: Properties describing exposure level of the image.
        $ref: '#/definitions/Exposure'
      noise:
        description: Properties describing noise level of the image.
        $ref: '#/definitions/Noise'
      mask:
        description: Properties describing the presence of a mask on a given face.
        $ref: '#/definitions/Mask'
      qualityForRecognition:
        type: string
        description: >-
          Properties describing the overall image quality regarding whether the
          image being used in the detection is of sufficient quality to attempt
          face recognition on.
        x-ms-enum:
          name: QualityForRecognition
          modelAsString: false
        enum:
          - Low
          - Medium
          - High
  FacialHair:
    type: object
    description: Properties describing facial hair attributes.
    properties:
      moustache:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      beard:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      sideburns:
        x-nullable: false
        $ref: '#/definitions/Confidence'
  HeadPose:
    type: object
    description: Properties indicating head pose of the face.
    properties:
      roll:
        type: number
        x-nullable: false
      yaw:
        type: number
        x-nullable: false
      pitch:
        type: number
        x-nullable: false
  Emotion:
    type: object
    description: >-
      Properties describing facial emotion in form of confidence ranging from 0
      to 1.
    properties:
      anger:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      contempt:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      disgust:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      fear:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      happiness:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      neutral:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      sadness:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      surprise:
        x-nullable: false
        $ref: '#/definitions/Confidence'
  Hair:
    type: object
    description: Properties describing hair attributes.
    properties:
      bald:
        description: A number describing confidence level of whether the person is bald.
        x-nullable: false
        $ref: '#/definitions/Confidence'
      invisible:
        type: boolean
        description: A boolean value describing whether the hair is visible in the image.
        x-nullable: false
      hairColor:
        description: >-
          An array of candidate colors and confidence level in the presence of
          each.
        $ref: '#/definitions/HairColors'
  HairColors:
    type: array
    items:
      $ref: '#/definitions/HairColor'
  HairColor:
    type: object
    description: Hair color and associated confidence
    properties:
      color:
        type: string
        description: Name of the hair color.
        x-nullable: false
        x-ms-enum:
          name: HairColorType
          modelAsString: false
        enum:
          - unknown
          - white
          - gray
          - blond
          - brown
          - red
          - black
          - other
      confidence:
        x-nullable: false
        description: Confidence level of the color
        $ref: '#/definitions/Confidence'
  Makeup:
    type: object
    description: Properties describing the presence of makeup on a given face.
    properties:
      eyeMakeup:
        type: boolean
        description: A boolean value describing whether eye makeup is present on a face.
        x-nullable: false
      lipMakeup:
        type: boolean
        description: A boolean value describing whether lip makeup is present on a face.
        x-nullable: false
  Occlusion:
    type: object
    description: Properties describing occlusions on a given face.
    properties:
      foreheadOccluded:
        type: boolean
        description: A boolean value indicating whether forehead is occluded.
        x-nullable: false
      eyeOccluded:
        type: boolean
        description: A boolean value indicating whether eyes are occluded.
        x-nullable: false
      mouthOccluded:
        type: boolean
        description: A boolean value indicating whether the mouth is occluded.
        x-nullable: false
  Accessories:
    type: array
    description: Properties describing any accessories on a given face.
    items:
      $ref: '#/definitions/Accessory'
  Accessory:
    type: object
    description: Accessory item and corresponding confidence level.
    properties:
      type:
        type: string
        description: Type of an accessory
        x-nullable: false
        x-ms-enum:
          name: AccessoryType
          modelAsString: false
        enum:
          - headWear
          - glasses
          - mask
      confidence:
        x-nullable: false
        description: Confidence level of an accessory
        $ref: '#/definitions/Confidence'
  Blur:
    type: object
    description: Properties describing any presence of blur within the image.
    properties:
      blurLevel:
        type: string
        description: An enum value indicating level of blurriness.
        x-nullable: false
        x-ms-enum:
          name: BlurLevel
          modelAsString: false
        enum:
          - Low
          - Medium
          - High
      value:
        description: A number indicating level of blurriness ranging from 0 to 1.
        x-nullable: false
        $ref: '#/definitions/Level'
  Exposure:
    type: object
    description: Properties describing exposure level of the image.
    properties:
      exposureLevel:
        type: string
        description: An enum value indicating level of exposure.
        x-nullable: false
        x-ms-enum:
          name: ExposureLevel
          modelAsString: false
        enum:
          - UnderExposure
          - GoodExposure
          - OverExposure
      value:
        description: >-
          A number indicating level of exposure level ranging from 0 to 1. [0,
          0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is
          over exposure.
        x-nullable: false
        $ref: '#/definitions/Level'
  Noise:
    type: object
    description: Properties describing noise level of the image.
    properties:
      noiseLevel:
        type: string
        description: An enum value indicating level of noise.
        x-nullable: false
        x-ms-enum:
          name: NoiseLevel
          modelAsString: false
        enum:
          - Low
          - Medium
          - High
      value:
        description: >-
          A number indicating level of noise level ranging from 0 to 1. [0,
          0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is
          over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise
          level. [0.7, 1] is high noise level.
        x-nullable: false
        $ref: '#/definitions/Level'
  Mask:
    type: object
    description: Properties describing the presence of a mask on a given face.
    properties:
      type:
        type: string
        description: Mask type if any of the face
        x-nullable: false
        x-ms-enum:
          name: MaskType
          modelAsString: false
        enum:
          - noMask
          - faceMask
          - otherMaskOrOcclusion
          - uncertain
      noseAndMouthCovered:
        type: boolean
        description: A boolean value indicating whether nose and mouth are covered.
        x-nullable: false
  FindSimilarRequest:
    type: object
    required:
      - faceId
    description: Request body for find similar operation.
    properties:
      faceId:
        type: string
        format: uuid
        description: >-
          FaceId of the query face. User needs to call Face - Detect first to
          get a valid faceId. Note that this faceId is not persisted and will
          expire at the time specified by faceIdTimeToLive after the detection
          call
      faceListId:
        type: string
        description: >-
          An existing user-specified unique candidate face list, created in Face
          List - Create a Face List. Face list contains a set of
          persistedFaceIds which are persisted and will never expire. Parameter
          faceListId, largeFaceListId and faceIds should not be provided at the
          same time.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      largeFaceListId:
        type: string
        description: >-
          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.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      faceIds:
        type: array
        description: >-
          An array of candidate faceIds. All of them are created by Face -
          Detect and the faceIds will expire at the time specified by
          faceIdTimeToLive 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.
        maxItems: 1000
        items:
          type: string
          format: uuid
      maxNumOfCandidatesReturned:
        type: integer
        description: >-
          The number of top similar faces returned. The valid range is [1,
          1000].
        default: 20
        minimum: 1
        maximum: 1000
      mode:
        type: string
        description: Similar face searching mode. It can be "matchPerson" or "matchFace".
        default: matchPerson
        x-nullable: false
        x-ms-enum:
          name: FindSimilarMatchMode
          modelAsString: false
        enum:
          - matchPerson
          - matchFace
  SimilarFaces:
    type: array
    items:
      $ref: '#/definitions/SimilarFace'
  SimilarFace:
    type: object
    required:
      - confidence
    description: Response body for find similar face operation.
    properties:
      faceId:
        type: string
        format: uuid
        description: >-
          FaceId of candidate face when find by faceIds. faceId is created by
          Face - Detect and will expire at the time specified by
          faceIdTimeToLive after the detection call
      persistedFaceId:
        type: string
        format: uuid
        description: >-
          PersistedFaceId of candidate face when find by faceListId.
          persistedFaceId in face list is persisted and will not expire. As
          showed in below response
      confidence:
        description: >-
          Similarity confidence of the candidate face. The higher confidence,
          the more similar. Range between [0,1].
        $ref: '#/definitions/Confidence'
  GroupRequest:
    type: object
    required:
      - faceIds
    description: Request body for group request.
    properties:
      faceIds:
        type: array
        description: >-
          Array of candidate faceId created by Face - Detect. The maximum is
          1000 faces
        maxItems: 1000
        items:
          type: string
          format: uuid
          x-nullable: false
  GroupResult:
    type: object
    required:
      - groups
    description: An array of face groups based on face similarity.
    properties:
      groups:
        type: array
        description: >-
          A partition of the original faces based on face similarity. Groups are
          ranked by number of faces
        items:
          type: array
          items:
            type: string
            format: uuid
            x-nullable: false
      messyGroup:
        type: array
        description: >-
          Face ids array of faces that cannot find any similar faces from
          original faces.
        items:
          type: string
          format: uuid
          x-nullable: false
  IdentifyRequest:
    type: object
    required:
      - faceIds
    description: Request body for identify face operation.
    properties:
      faceIds:
        type: array
        description: >-
          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].
        maxItems: 10
        items:
          type: string
          format: uuid
          x-nullable: false
      personGroupId:
        description: >-
          PersonGroupId of the target person group, created by PersonGroup -
          Create. Parameter personGroupId, largePersonGroupId,
          dynamicPersonGroupId, or personIds should not be provided at the same
          time.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      largePersonGroupId:
        description: >-
          LargePersonGroupId of the target large person group, created by
          LargePersonGroup - Create. Parameter personGroupId,
          largePersonGroupId, dynamicPersonGroupId, or personIds should not be
          provided at the same time.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      dynamicPersonGroupId:
        description: >-
          DynamicPersonGroupId of the target PersonDirectory dynamic person
          group to match against. Parameter personGroupId, largePersonGroupId,
          dynamicPersonGroupId, or personIds should not be provided at the same
          time.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      personIds:
        description: >-
          Array of personIds created in PersonDirectory - PersonCreate. The
          valid number of personIds is between [1,30]. Providing a single '*' in
          the array identifies against all persons inside the PersonDirectory.
          Parameter personGroupId, largePersonGroupId, dynamicPersonGroupId, or
          personIds should not be provided at the same time.
        type: array
        maxItems: 30
        items:
          type: string
          x-nullable: false
      maxNumOfCandidatesReturned:
        type: integer
        description: >-
          The range of maxNumOfCandidatesReturned is between 1 and 100 (default
          is 1).
        default: 1
        minimum: 1
        maximum: 100
      confidenceThreshold:
        description: >-
          Confidence threshold of identification, used to judge whether one face
          belong to one person. The range of confidenceThreshold is [0, 1]
          (default specified by algorithm).
        $ref: '#/definitions/Confidence'
  IdentifyResults:
    type: array
    items:
      $ref: '#/definitions/IdentifyResult'
  IdentifyResult:
    type: object
    required:
      - faceId
      - candidates
    description: Response body for identify face operation.
    properties:
      faceId:
        type: string
        format: uuid
        description: FaceId of the query face
      candidates:
        type: array
        description: >-
          Identified person candidates for that face (ranked by confidence).
          Array size should be no larger than input maxNumOfCandidatesReturned.
          If no person is identified, will return an empty array.
        items:
          $ref: '#/definitions/IdentifyCandidate'
  IdentifyCandidate:
    type: object
    required:
      - personId
      - confidence
    description: All possible faces that may qualify.
    properties:
      personId:
        type: string
        format: uuid
        description: Id of candidate
      confidence:
        description: >-
          Confidence threshold of identification, used to judge whether one face
          belong to one person. The range of confidenceThreshold is [0, 1]
          (default specified by algorithm).
        $ref: '#/definitions/Confidence'
  VerifyFaceToPersonRequest:
    type: object
    required:
      - faceId
      - personId
    description: Request body for face to person verification.
    properties:
      faceId:
        type: string
        format: uuid
        description: FaceId of the face, comes from Face - Detect
      personGroupId:
        description: >-
          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.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      largePersonGroupId:
        description: >-
          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.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      personId:
        type: string
        format: uuid
        description: >-
          Specify a certain person in a person group, a large person group, or
          person directory (if personGroupId and largePersonGroupId are
          omitted). personId is created in PersonGroup Person - Create or
          LargePersonGroup Person - Create or PersonDirectory - Create.
  VerifyFaceToFaceRequest:
    type: object
    required:
      - faceId1
      - faceId2
    description: Request body for face to face verification.
    properties:
      faceId1:
        type: string
        format: uuid
        description: FaceId of the first face, comes from Face - Detect
      faceId2:
        type: string
        format: uuid
        description: FaceId of the second face, comes from Face - Detect
  VerifyResult:
    type: object
    required:
      - isIdentical
      - confidence
    description: Result of the verify operation.
    properties:
      isIdentical:
        type: boolean
        description: >-
          True if the two faces belong to the same person or the face belongs to
          the person, otherwise false.
      confidence:
        description: >-
          A number indicates the similarity confidence of whether two faces
          belong to the same person, or whether the face belongs to the person.
          By default, isIdentical is set to True if similarity confidence is
          greater than or equal to 0.5. This is useful for advanced users to
          override "isIdentical" and fine-tune the result on their own data.
        $ref: '#/definitions/Confidence'
  FaceList:
    description: Face list object.
    type: object
    required:
      - faceListId
      - name
    properties:
      faceListId:
        type: string
        description: FaceListId of the target face list.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
      persistedFaces:
        description: Persisted faces within the face list.
        $ref: '#/definitions/PersistedFaces'
  FaceLists:
    type: array
    description: >-
      An array of face list results, with fields of faceListId, name and
      userData
    items:
      $ref: '#/definitions/FaceList'
  PersonGroup:
    type: object
    required:
      - personGroupId
      - name
    description: Person group object.
    properties:
      personGroupId:
        description: PersonGroupId of the target person group.
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
  PersonGroups:
    type: array
    description: An array of person groups.
    items:
      $ref: '#/definitions/PersonGroup'
  Person:
    type: object
    required:
      - personId
    description: Person object.
    properties:
      personId:
        type: string
        format: uuid
        description: PersonId of the target face list.
      persistedFaceIds:
        type: array
        description: >-
          PersistedFaceIds of registered faces in the person. These
          persistedFaceIds are returned from Person - Add a Person Face, and
          will not expire.
        items:
          type: string
          format: uuid
          x-nullable: false
    allOf:
      - $ref: '#/definitions/NameAndUserDataContract'
  Persons:
    type: array
    description: An array of Persons.
    items:
      $ref: '#/definitions/Person'
  PersistedFace:
    type: object
    required:
      - persistedFaceId
    description: PersonFace object.
    properties:
      persistedFaceId:
        type: string
        format: uuid
        description: >-
          The persistedFaceId of the target face, which is persisted and will
          not expire. Different from faceId created by Face - Detect and will
          expire in at the time specified by faceIdTimeToLive after the
          detection call.
      userData:
        type: string
        description: User-provided data attached to the face. The size limit is 1KB.
        maxLength: 1024
  PersistedFaces:
    type: array
    description: An array of persisted faces within the face list or large face list.
    items:
      $ref: '#/definitions/PersistedFace'
  LargeFaceList:
    description: Large face list object.
    type: object
    required:
      - largeFaceListId
      - name
    properties:
      largeFaceListId:
        type: string
        description: LargeFaceListId of the target large face list.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
  LargeFaceLists:
    type: array
    description: >-
      An array of large face list results, with fields of largeFaceListId, name
      and userData
    items:
      $ref: '#/definitions/LargeFaceList'
  LargePersonGroup:
    type: object
    required:
      - largePersonGroupId
      - name
    description: Large person group object.
    properties:
      largePersonGroupId:
        description: LargePersonGroupId of the target large person groups
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
  LargePersonGroups:
    type: array
    description: An array of large person groups.
    items:
      $ref: '#/definitions/LargePersonGroup'
  UpdateFaceRequest:
    type: object
    description: Request to update face data.
    properties:
      userData:
        type: string
        description: User-provided data attached to the face. The size limit is 1KB.
        maxLength: 1024
  TrainingStatus:
    type: object
    required:
      - status
      - createdDateTime
    description: Training status object.
    properties:
      status:
        type: string
        description: >-
          Training status: notstarted, running, succeeded, failed. If the
          training process is waiting to perform, the status is notstarted. If
          the training is ongoing, the status is running. Status succeed means
          this person group or large person group is ready for Face - Identify,
          or this large face list is ready for Face - Find Similar. Status
          failed is often caused by no person or no persisted face exist in the
          person group or large person group, or no persisted face exist in the
          large face list.
        x-ms-enum:
          name: TrainingStatusType
          modelAsString: false
        enum:
          - nonstarted
          - running
          - succeeded
          - failed
      createdDateTime:
        type: string
        format: date-time
        description: >-
          A combined UTC date and time string that describes the created time of
          the person group, large person group or large face list.
        x-ms-client-name: created
      lastActionDateTime:
        type: string
        format: date-time
        description: >-
          A combined UTC date and time string that describes the last modify
          time of the person group, large person group or large face list, could
          be null value when the group is not successfully trained.
        x-ms-client-name: lastAction
      lastSuccessfulTrainingDateTime:
        type: string
        format: date-time
        description: >-
          A combined UTC date and time string that describes the last successful
          training time of the person group, large person group or large face
          list.
        x-ms-client-name: lastSuccessfulTraining
      message:
        type: string
        description: >-
          Show failure message when training failed (omitted when training
          succeed).
  Confidence:
    description: >-
      A number ranging from 0 to 1 indicating a level of confidence associated
      with a property.
    type: number
    minimum: 0
    maximum: 1
  Level:
    description: >-
      A number ranging from 0 to 1 indicating the intensity level associated
      with a property.
    type: number
    minimum: 0
    maximum: 1
  NameAndUserDataContractForCreation:
    type: object
    description: >-
      A combination of user defined name and user specified data for the person,
      largePersonGroup/personGroup, and largeFaceList/faceList.
    required:
      - name
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
  NameAndUserDataContract:
    type: object
    description: >-
      A combination of user defined name and user specified data for the person,
      largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
  MetaDataContract:
    type: object
    description: >-
      A combination of user defined name and user specified data and recognition
      model name for largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
    allOf:
      - $ref: '#/definitions/NameAndUserDataContractForCreation'
  RecognitionModel:
    type: string
    description: >-
      Name of recognition model. Recognition model is used when the face
      features are extracted and associated with detected faceIds,
      (Large)FaceList or (Large)PersonGroup. A recognition model name can be
      provided when performing Face - Detect or (Large)FaceList - Create or
      (Large)PersonGroup - Create. The default value is 'recognition_01', if
      latest model needed, please explicitly specify the model you need.
    default: recognition_01
    x-nullable: false
    x-ms-enum:
      name: RecognitionModel
      modelAsString: true
    enum:
      - recognition_01
      - recognition_02
      - recognition_03
      - recognition_04
  ApplyScope:
    type: array
    description: >-
      Array of the target Face subscription ids for the snapshot, specified by
      the user who created the snapshot when calling Snapshot - Take. For each
      snapshot, only subscriptions included in the applyScope of Snapshot - Take
      can apply it.
    items:
      type: string
      format: uuid
      x-nullable: false
  ApplySnapshotRequest:
    type: object
    required:
      - objectId
    description: Request body for applying snapshot operation.
    properties:
      objectId:
        type: string
        description: User specified target object id to be created from the snapshot.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      mode:
        type: string
        description: >-
          Snapshot applying mode. Currently only CreateNew 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.
        default: CreateNew
        x-nullable: false
        x-ms-enum:
          name: SnapshotApplyMode
          modelAsString: false
        enum:
          - CreateNew
  Snapshots:
    type: array
    description: An array of snapshots.
    items:
      $ref: '#/definitions/Snapshot'
  Snapshot:
    type: object
    required:
      - id
      - account
      - type
      - applyScope
      - createdTime
      - lastUpdateTime
    description: >-
      Snapshot object. The Snapshot API will move your data outside the geo you
      select for your resource to West US, West Europe and Southeast Asia.
    properties:
      id:
        type: string
        format: uuid
        description: Snapshot id.
      account:
        type: string
        description: >-
          Azure Cognitive Service Face account id of the subscriber who created
          the snapshot by Snapshot - Take.
      type:
        type: string
        description: >-
          Type of the source object in the snapshot, specified by the subscriber
          who created the snapshot when calling Snapshot - Take. Currently
          FaceList, PersonGroup, LargeFaceList and LargePersonGroup are
          supported.
        x-ms-enum:
          name: SnapshotObjectType
          modelAsString: false
        enum:
          - FaceList
          - LargeFaceList
          - LargePersonGroup
          - PersonGroup
      applyScope:
        description: >-
          Array of the target Face subscription ids for the snapshot, specified
          by the user who created the snapshot when calling Snapshot - Take. For
          each snapshot, only subscriptions included in the applyScope of
          Snapshot - Take can apply it.
        $ref: '#/definitions/ApplyScope'
      userData:
        type: string
        description: >-
          User specified data about the snapshot for any purpose. Length should
          not exceed 16KB.
        maxLength: 16384
      createdTime:
        type: string
        format: date-time
        description: >-
          A combined UTC date and time string that describes the created time of
          the snapshot. E.g. 2018-12-25T11:41:02.2331413Z.
      lastUpdateTime:
        type: string
        format: date-time
        description: >-
          A combined UTC date and time string that describes the last time when
          the snapshot was created or updated by Snapshot - Update. E.g.
          2018-12-25T11:51:27.8705696Z.
  TakeSnapshotRequest:
    type: object
    required:
      - type
      - objectId
      - applyScope
    description: Request body for taking snapshot operation.
    properties:
      type:
        type: string
        description: >-
          User specified type for the source object to take snapshot from.
          Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup
          are supported.
        x-ms-enum:
          name: SnapshotObjectType
          modelAsString: false
        enum:
          - FaceList
          - LargeFaceList
          - LargePersonGroup
          - PersonGroup
      objectId:
        type: string
        description: User specified source object id to take snapshot from.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      applyScope:
        description: >-
          User specified array of target Face subscription ids for the snapshot.
          For each snapshot, only subscriptions included in the applyScope of
          Snapshot - Take can apply it.
        $ref: '#/definitions/ApplyScope'
      userData:
        type: string
        description: >-
          User specified data about the snapshot for any purpose. Length should
          not exceed 16KB.
        maxLength: 16384
  UpdateSnapshotRequest:
    type: object
    description: >-
      Request body for updating a snapshot, with a combination of user defined
      apply scope and user specified data.
    properties:
      applyScope:
        description: >-
          Array of the target Face subscription ids for the snapshot, specified
          by the user who created the snapshot when calling Snapshot - Take. For
          each snapshot, only subscriptions included in the applyScope of
          Snapshot - Take can apply it.
        $ref: '#/definitions/ApplyScope'
      userData:
        type: string
        description: >-
          User specified data about the snapshot for any purpose. Length should
          not exceed 16KB.
        maxLength: 16384
  PersistedFaceResponse:
    type: object
    properties:
      persistedFaceId:
        format: uuid
        type: string
      userData:
        type: string
  AsyncOperationStatus:
    enum:
      - notStarted
      - running
      - succeeded
      - failed
    type: string
    description: >-
      Operation status: notstarted, running, succeeded, failed. If the operation
      is requested and waiting to perform, the status is notstarted. If the
      operation is ongoing in backend, the status is running. Status succeeded
      means the operation is completed successfully, specifically for snapshot
      taking operation, it illustrates the snapshot is well taken and ready to
      apply, and for snapshot applying operation, it presents the target object
      has finished creating by the snapshot and ready to be used. Status failed
      is often caused by editing the source object while taking the snapshot or
      editing the target object while applying the snapshot before completion,
      see the field "message" to check the failure reason.
    x-ms-enum:
      name: OperationStatusType
      modelAsString: false
  OperationStatus:
    type: object
    required:
      - status
      - createdTime
    description: Operation status object. Operation refers to an asynchronous backend task.
    properties:
      status:
        $ref: '#/definitions/AsyncOperationStatus'
      createdTime:
        format: date-time
        type: string
        description: >-
          A combined UTC date and time string that describes the time when the
          operation is requested. E.g. 2018-12-25T11:41:02.2331413Z.
      lastActionTime:
        format: date-time
        type: string
        description: >-
          A combined UTC date and time string that describes the last time the
          operation is actively running. The lastActionTime will keep increasing
          until the operation finishes. E.g. 2018-12-25T11:51:27.8705696Z.
      finishedTime:
        format: date-time
        type: string
        description: >-
          A combined UTC date and time string that describes the time when the
          operation finished. E.g. 2018-12-25T11:41:02.2331413Z.
      resourceLocation:
        type: string
        description: >-
          When the operation succeeds successfully, for snapshot taking
          operation the snapshot id will be included in this field, and for
          snapshot applying operation, the path to get the target object will be
          returned in this field.
      message:
        type: string
        description: >-
          Show failure message when operation fails (omitted when operation
          succeeds).
  EnrollmentResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      name:
        type: string
      userData:
        type: string
  EnrolledPerson:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        description: Person id.
        x-nullable: false
      name:
        type: string
        description: User defined name, maximum length is 128.
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
  PersonCreationResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
  EnrollmentRequest:
    type: object
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
  EnrollmentPrintResponse:
    type: object
    properties:
      persistedFaceId:
        format: uuid
        type: string
        x-nullable: false
      recognitionModel:
        type: string
      userData:
        type: string
  PersonResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      persistedFaceIds:
        type: array
        items:
          format: uuid
          type: string
          x-nullable: false
      name:
        type: string
      userData:
        type: string
  DetectionModel:
    enum:
      - detection_01
      - detection_02
      - detection_03
      - detection_preview_1904
      - ir_detection_01
      - expression_01
    type: string
    description: Detection model used when extracting the face.
  PersistedFaceWithType:
    type: object
    properties:
      detectionModel:
        $ref: '#/definitions/DetectionModel'
      faceFeature:
        format: byte
        type: string
      persistedFaceId:
        format: uuid
        type: string
      userData:
        type: string
  DynamicPersonGroupCreateRequest:
    type: object
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
      addPersonIds:
        type: array
        description: Person ids to add to the dynamic person group.
        items:
          format: uuid
          type: string
          x-nullable: false
  DynamicPersonGroupUpdateRequest:
    type: object
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
      addPersonIds:
        type: array
        description: Person ids to add to the dynamic person group.
        items:
          format: uuid
          type: string
          x-nullable: false
      removePersonIds:
        type: array
        description: Person ids to remove from the dynamic person group.
        items:
          type: string
  DynamicPersonGroupGetResponse:
    type: object
    properties:
      dynamicPersonGroupId:
        type: string
      name:
        type: string
      userData:
        type: string
  DynamicPersonGroupListPersonsResponse:
    type: object
    properties:
      personIds:
        type: array
        items:
          format: uuid
          type: string
          x-nullable: false
  PersonDynamicPersonGroupReferenceResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      dynamicPersonGroupIds:
        type: array
        items:
          type: string
parameters:
  returnFaceAttributes:
    name: returnFaceAttributes
    in: query
    description: >-
      Analyze and return the one or more specified face attributes in the
      comma-separated string like "returnFaceAttributes=age,gender". The
      available attributes depends on the 'detectionModel' specified.
      'detection_01' supports age, gender, headPose, smile, facialHair, glasses,
      emotion, hair, makeup, occlusion, accessories, blur, exposure, noise, and
      qualityForRecognition. While 'detection_02' does not support any
      attributes and 'detection_03' only supports mask and
      qualityForRecognition. Additionally, qualityForRecognition is only
      supported when the 'recognitionModel' is specified as 'recognition_03' or
      'recognition_04'. Note that each face attribute analysis has additional
      computational and time cost.
    type: array
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
    items:
      type: string
      x-nullable: false
      x-ms-enum:
        name: FaceAttributeType
        modelAsString: false
      enum:
        - age
        - gender
        - headPose
        - smile
        - facialHair
        - glasses
        - emotion
        - hair
        - makeup
        - occlusion
        - accessories
        - blur
        - exposure
        - noise
        - mask
        - qualityForRecognition
  targetFace:
    name: targetFace
    in: query
    description: >-
      A face rectangle to specify the target face to be added to a person in the
      format of "targetFace=left,top,width,height". E.g.
      "targetFace=10,10,100,100". If there is more than one face in the image,
      targetFace is required to specify which face to add. No targetFace means
      there is only one face detected in the entire image.
    type: array
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
    items:
      type: integer
      format: int32
      x-nullable: false
      maxItems: 4
      minItems: 4
  faceUserData:
    name: userData
    in: query
    description: >-
      User-specified data about the face for any purpose. The maximum length is
      1KB.
    type: string
    maxLength: 1024
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
  faceListId:
    name: faceListId
    in: path
    description: Id referencing a particular face list.
    required: true
    type: string
    x-ms-parameter-location: method
    collectionFormat: csv
    maxLength: 64
    pattern: ^[a-z0-9-_]+$
  personGroupId:
    name: personGroupId
    in: path
    description: Id referencing a particular person group.
    required: true
    type: string
    x-ms-parameter-location: method
    collectionFormat: csv
    maxLength: 64
    pattern: ^[a-z0-9-_]+$
  largeFaceListId:
    name: largeFaceListId
    in: path
    description: Id referencing a particular large face list.
    required: true
    type: string
    x-ms-parameter-location: method
    collectionFormat: csv
    maxLength: 64
    pattern: ^[a-z0-9-_]+$
  largePersonGroupId:
    name: largePersonGroupId
    in: path
    description: Id referencing a particular large person group.
    required: true
    type: string
    x-ms-parameter-location: method
    collectionFormat: csv
    maxLength: 64
    pattern: ^[a-z0-9-_]+$
  personId:
    name: personId
    in: path
    description: Id referencing a particular person.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
    collectionFormat: csv
  persistedFaceId:
    name: persistedFaceId
    in: path
    description: Id referencing a particular persistedFaceId of an existing face.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
    collectionFormat: csv
  applyScope:
    name: applyScope
    description: >-
      User specified snapshot apply scopes as a search filter. ApplyScope is an
      array of the target Azure subscription ids for the snapshot, specified by
      the user who created the snapshot by Snapshot - Take.
    in: query
    required: false
    type: array
    x-ms-parameter-location: method
    collectionFormat: csv
    items:
      type: string
      format: uuid
      x-nullable: false
  operationId:
    name: operationId
    in: path
    description: Id referencing a particular take/apply snapshot operation.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
    collectionFormat: csv
  snapshotId:
    name: snapshotId
    in: path
    description: Id referencing a particular snapshot.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
    collectionFormat: csv
  Endpoint:
    name: Endpoint
    description: >-
      Supported Cognitive Services endpoints (protocol and hostname, for
      example: https://westus.api.cognitive.microsoft.com).
    x-ms-parameter-location: client
    required: true
    type: string
    in: path
    x-ms-skip-url-encoding: true
  recognitionModel:
    name: recognitionModel
    description: >-
      Name of recognition model. Recognition model is used when the face
      features are extracted and associated with detected faceIds,
      (Large)FaceList or (Large)PersonGroup. A recognition model name can be
      provided when performing Face - Detect or (Large)FaceList - Create or
      (Large)PersonGroup - Create. The default value is 'recognition_01', if
      latest model needed, please explicitly specify the model you need.
    default: recognition_01
    required: false
    type: string
    in: query
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: RecognitionModel
      modelAsString: true
    enum:
      - recognition_01
      - recognition_02
      - recognition_03
      - recognition_04
  returnRecognitionModel:
    name: returnRecognitionModel
    description: >-
      A value indicating whether the operation should return 'recognitionModel'
      in response.
    default: false
    required: false
    type: boolean
    in: query
    x-ms-parameter-location: method
  detectionModel:
    name: detectionModel
    description: >-
      Name of detection model. Detection model is used to detect faces in the
      submitted image. A detection model name can be provided when performing
      Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add
      Face. The default value is 'detection_01', if another model is needed,
      please explicitly specify it.
    default: detection_01
    required: false
    type: string
    in: query
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: DetectionModel
      modelAsString: true
    enum:
      - detection_01
      - detection_02
      - detection_03
  returnFaceId:
    name: returnFaceId
    in: query
    x-ms-parameter-location: method
    description: >-
      A value indicating whether the operation should return faceIds of detected
      faces. Detecting with this value set to true requires additional access
      approvals at https://aka.ms/facerecognition.
    type: boolean
  returnFaceLandmarks:
    name: returnFaceLandmarks
    in: query
    x-ms-parameter-location: method
    description: >-
      A value indicating whether the operation should return landmarks of the
      detected faces.
    type: boolean
    default: false
  faceIdTimeToLive:
    name: faceIdTimeToLive
    in: query
    x-ms-parameter-location: method
    description: >-
      The number of seconds for the faceId being cached. Supported range from 60
      seconds up to 86400 seconds. The default value is 86400 (24 hours).
    type: integer
    default: 86400
    minimum: 60
    maximum: 86400
tags:
  - name: Detect
  - name: Facelists
  - name: Findsimilars
  - name: Group
  - name: Identify
  - name: Largefacelists
  - name: Largepersongroups
  - name: Operations
  - name: PersonDirectory
  - name: Persongroups
  - name: Snapshots
  - name: Verify