Microsoft Azure Verify API

openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Verify API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
tags:
- name: Verify
paths:
  /verify:
    post:
      description: 'Verify whether two faces belong to a same person or whether one face belongs to a person.


        Remarks:

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

        * For the scenarios that are sensitive to accuracy please make your own judgment.

        * 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.'
      operationId: microsoftAzureFaceVerifyfacetoface
      responses:
        '200':
          description: A successful call returns the verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResult'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Verify faces example:
          $ref: ./examples/VerifyFaceToFace.json
      summary: Microsoft Azure Post Verify
      tags:
      - Verify
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyFaceToFaceRequest'
        description: Request body for face to face verification.
        required: true
components:
  schemas:
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    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
    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
    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: '#/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