Microsoft Azure Identify API

openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Identify API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
tags:
- name: Identify
paths:
  /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.

        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 and LargePersonGroup - Train.


        Remarks:

        * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces.

        * Each person in the person group/large person group could have more than one face, but no more than 248 faces.

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

        * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array.

        * Try Face - Find Similar when you need to find similar faces from a face list/large face list instead of a person group/large person group.

        * 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.'
      operationId: microsoftAzureFaceIdentify
      responses:
        '200':
          description: A successful call returns the identified candidate person(s) for each query face.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifyResults'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Identify example:
          $ref: ./examples/Identify.json
      summary: Microsoft Azure Post Identify
      tags:
      - Identify
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
        description: Request body for identify operation.
        required: true
components:
  schemas:
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    IdentifyResults:
      type: array
      items:
        $ref: '#/components/schemas/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: '#/components/schemas/IdentifyCandidate'
    Error:
      type: object
      description: Error body.
      properties:
        code:
          type: string
        message:
          type: string
    Confidence:
      description: A number ranging from 0 to 1 indicating a level of confidence associated with a property.
      type: number
      minimum: 0
      maximum: 1
    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
        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
        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: '#/components/schemas/Confidence'
    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: '#/components/schemas/Confidence'
  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