openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Persongroups API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
tags:
- name: Person Groups
paths:
  /persongroups/{personGroupId}/persons:
    post:
      description: Create a new person in a specified person group.
      operationId: microsoftAzurePersongrouppersonCreate
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns a new personId created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Create new person for person group example:
          $ref: ./examples/CreateNewPersonGroupPerson.json
      summary: Microsoft Azure Post Persongroups Persongroupid Persons
      tags:
      - Person Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameAndUserDataContract'
        description: Request body for creating new person.
        required: true
    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: '#/components/parameters/personGroupId'
      - name: start
        description: Starting person id to return (used to list a range of persons).
        in: query
        required: false
        schema:
          type: string
      - name: top
        description: Number of persons to return starting with the person id indicated by the 'start' parameter.
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      responses:
        '200':
          description: A successful call returns an array of person information that belong to the person group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persons'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        List persons in person group:
          $ref: ./examples/ListPersonGroupPersons.json
      summary: Microsoft Azure Get Persongroups Persongroupid Persons
      tags:
      - Person Groups
  /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: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Delete an existing person example:
          $ref: ./examples/DeletePersonGroupPerson.json
      summary: Microsoft Azure Delete Persongroups Persongroupid Persons Personid
      tags:
      - Person Groups
    get:
      description: Retrieve a person's information, including registered persisted faces, name and userData.
      operationId: microsoftAzurePersongrouppersonGet
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      responses:
        '200':
          description: A successful call returns the person's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get person example:
          $ref: ./examples/GetPersonGroupPerson.json
      summary: Microsoft Azure Get Persongroups Persongroupid Persons Personid
      tags:
      - Person Groups
    patch:
      description: Update name or userData of a person.
      operationId: microsoftAzurePersongrouppersonUpdate
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Update person example:
          $ref: ./examples/UpdatePersonGroupPerson.json
      summary: Microsoft Azure Patch Persongroups Persongroupid Persons Personid
      tags:
      - Person Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameAndUserDataContract'
        description: Request body for person update operation.
        required: true
  /persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}:
    delete:
      description: 'Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId.

        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: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/persistedFaceId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Delete face from person example:
          $ref: ./examples/DeletePersonGroupPersonFace.json
      summary: Microsoft Azure Delete Persongroups Persongroupid Persons Personid…
      tags:
      - Person Groups
    get:
      description: Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).
      operationId: microsoftAzurePersongrouppersonGetface
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/persistedFaceId'
      responses:
        '200':
          description: A successful call returns target persisted face's information (persistedFaceId and userData).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get persisted face example:
          $ref: ./examples/GetPersonGroupPersistedFace.json
      summary: Microsoft Azure Get Persongroups Persongroupid Persons Personid Persistedfaces…
      tags:
      - Person Groups
    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, PersonGroup Person - Delete or PersonGroup - Delete is called.

        Note persistedFaceId is different from faceId generated by Face - Detect.

        * 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, 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.'
      operationId: microsoftAzurePersongrouppersonUpdateface
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/persistedFaceId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Update person face example:
          $ref: ./examples/UpdatePersonGroupPersonFace.json
      summary: Microsoft Azure Patch Persongroups Persongroupid Persons Personid…
      tags:
      - Person Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFaceRequest'
        description: Request body for updating persisted face.
        required: true
  /persongroups/{personGroupId}:
    put:
      description: 'Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel.

        A person group is the container of the uploaded person data, including face recognition features.

        After creation, use PersonGroup Person - Create to add persons into the group, and then call PersonGroup - Train to get this group ready for Face - Identify.

        No image will be stored. Only the person''s extracted face features and userData will be stored on server until PersonGroup Person - Delete or PersonGroup - Delete is called.

        ''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.


        Person group quota:

        * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.

        * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.

        * to handle larger scale face identification problem, please consider using LargePersonGroup.'
      operationId: microsoftAzurePersongroupCreate
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Create new person group example:
          $ref: ./examples/CreateNewPersonGroup.json
      summary: Microsoft Azure Put Persongroups Persongroupid
      tags:
      - Person Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaDataContract'
        description: Request body for creating new person group.
        required: true
    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: '#/components/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Delete a person group example:
          $ref: ./examples/DeletePersonGroup.json
      summary: Microsoft Azure Delete Persongroups Persongroupid
      tags:
      - Person Groups
    get:
      description: Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use PersonGroup Person - List.
      operationId: microsoftAzurePersongroupGet
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns the person group's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonGroup'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get person group example:
          $ref: ./examples/GetPersonGroup.json
      summary: Microsoft Azure Get Persongroups Persongroupid
      tags:
      - Person Groups
    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: '#/components/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Update person group example:
          $ref: ./examples/UpdatePersonGroup.json
      summary: Microsoft Azure Patch Persongroups Persongroupid
      tags:
      - Person Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameAndUserDataContract'
        description: Request body for updating person group.
        required: true
  /persongroups/{personGroupId}/training:
    get:
      description: Retrieve the training status of a person group (completed or ongoing).
      operationId: microsoftAzurePersongroupGettrainingstatus
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      responses:
        '200':
          description: A successful call returns the person group's training status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingStatus'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get person group's training status example:
          $ref: ./examples/GetPersonGroupTrainingStatus.json
      summary: Microsoft Azure Get Persongroups Persongroupid Training
      tags:
      - Person Groups
  /persongroups:
    get:
      description: 'List person groups’ personGroupId, name, userData and recognitionModel.

        * Person groups are stored in alphabetical order of personGroupId.

        * "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.

        * "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.


        For example, total 5 person groups: "group1", ..., "group5".

        "start=&top=" will return all 5 groups.

        "start=&top=2" will return "group1", "group2".

        "start=group2&top=3" will return "group3", "group4", "group5".'
      operationId: microsoftAzurePersongroupList
      parameters:
      - name: start
        in: query
        required: false
        description: List person groups from the least personGroupId greater than the "start".
        schema:
          type: string
          maxLength: 64
      - name: top
        in: query
        required: false
        description: The number of person groups to list.
        schema:
          type: integer
          default: 1000
          maximum: 1000
          minimum: 1
      - $ref: '#/components/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns an array of person groups and their information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonGroups'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        List person groups example:
          $ref: ./examples/ListPersonGroups.json
      summary: Microsoft Azure Get Persongroups
      tags:
      - Person Groups
  /persongroups/{personGroupId}/train:
    post:
      description: Queue a person group training task, the training task may not be started immediately.
      operationId: microsoftAzurePersongroupTrain
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      responses:
        '202':
          description: The training task was queued successfully.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Queue person group training:
          $ref: ./examples/QueuePersonGroupTraining.json
      summary: Microsoft Azure Post Persongroups Persongroupid Train
      tags:
      - Person Groups
  /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, PersonGroup Person - Delete or PersonGroup - Delete is called.

        Note persistedFaceId is different from faceId generated by Face - Detect.

        * 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, 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.'
      operationId: microsoftAzurePersongrouppersonAddfacefromurl
      parameters:
      - $ref: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      - $ref: '#/components/parameters/detectionModel'
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Add Person face example:
          $ref: ./examples/AddPersonGroupPersonFaceFromUrl.json
      summary: Microsoft Azure Post Persongroups Persongroupid Persons Personid Persistedfaces
      tags:
      - Person Groups
components:
  parameters:
    returnRecognitionModel:
      name: returnRecognitionModel
      description: A value indicating whether the operation should return 'recognitionModel' in response.
      required: false
      in: query
      x-ms-parameter-location: method
      schema:
        type: boolean
        default: false
    personId:
      name: personId
      in: path
      description: Id referencing a particular person.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    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.
      required: false
      in: query
      x-ms-parameter-location: method
      x-ms-enum:
        name: DetectionModel
        modelAsString: true
      schema:
        type: string
        enum:
        - detection_01
        - detection_02
        - detection_03
        default: detection_01
    personGroupId:
      name: personGroupId
      in: path
      description: Id referencing a particular person group.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
    faceUserData:
      name: userData
      in: query
      description: User-specified data about the face for any purpose. The maximum length is 1KB.
      x-ms-parameter-location: method
      required: false
      style: form
      explode: false
      schema:
        type: string
        maxLength: 1024
    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.
      x-ms-parameter-location: method
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
          format: int32
          maxItems: 4
          minItems: 4
    persistedFaceId:
      name: persistedFaceId
      in: path
      description: Id referencing a particular persistedFaceId of an existing face.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      description: Error body.
      properties:
        code:
          type: string
        message:
          type: string
    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: '#/components/schemas/RecognitionModel'
      allOf:
      - $ref: '#/components/schemas/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-ms-enum:
        name: RecognitionModel
        modelAsString: true
      enum:
      - recognition_01
      - recognition_02
      - recognition_03
      - recognition_04
    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: '#/components/schemas/RecognitionModel'
    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
    PersonGroups:
      type: array
      description: An array of person groups.
      items:
        $ref: '#/components/schemas/PersonGroup'
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Persons:
      type: array
      description: An array of Persons.
      items:
        $ref: '#/components/schemas/Person'
    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
    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
    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).
    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
    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
      allOf:
      - $ref: '#/components/schemas/NameAndUserDataContract'
  securitySchemes:
    apim_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/face/v1.0-preview'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'
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: '#/components/schemas/VerifyFaceToPersonRequest'
      consumes:
      - application/json
      produces:
      - application/json
      responses:
        '200':
          description: A successful call returns the verification result.
          schema:
            $ref: '#/components/schemas/VerifyResult'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/parameters/returnFaceId'
      - $ref: '#/components/parameters/returnFaceLandmarks'
      - $ref: '#/components/parameters/returnFaceAttributes'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      - $ref: '#/components/parameters/recognitionModel'
      - $ref: '#/components/parameters/returnRecognitionModel'
      - $ref: '#/components/parameters/detectionModel'
      - $ref: '#/components/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: '#/components/schemas/DetectedFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/parameters/personGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      - $ref: '#/components/parameters/detectionModel'
      produces:
      - application/json
      consumes:
      - application/octet-stream
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/parameters/faceListId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      - $ref: '#/components/parameters/detectionModel'
      consumes:
      - application/octet-stream
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/parameters/largePersonGroupId'
      - $ref: '#/components/parameters/personId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      - $ref: '#/components/parameters/detectionModel'
      produces:
      - application/json
      consumes:
      - application/octet-stream
      responses:
        '200':
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/parameters/largeFaceListId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageStream
      - $ref: '#/components/parameters/detectionModel'
      consumes:
      - application/octet-stream
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          schema:
            $ref: '#/components/schemas/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: '#/components/schemas/EnrollmentPrintResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/components/schemas/Error'
      x-ms-examples:
        Add face to person directory person with stream example:
          $ref: ./examples/AddPersonDirectoryPersonFaceFromStream.json