Microsoft Azure Findsimilars API

openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Findsimilars API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
tags:
- name: Findsimilars
paths:
  /findsimilars:
    post:
      description: 'Given query face''s faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by Face - Detect With Url or Face - Detect With Stream, which will expire at the time specified by faceIdTimeToLive after creation. A "faceListId" is created by FaceList - Create containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by LargeFaceList - Create containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity.

        Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person''s other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces.

        The ''recognitionModel'' associated with the query face''s faceId should be the same as the ''recognitionModel'' used by the target faceId array, face list or large face list.'
      operationId: microsoftAzureFaceFindsimilar
      responses:
        '200':
          description: A successful call returns an array of the most similar faces represented in faceId if the input parameter is faceIds or persistedFaceId if the input parameter is faceListId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarFaces'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Find similar results example:
          $ref: ./examples/FindSimilar.json
      summary: Microsoft Azure Post Findsimilars
      tags:
      - Findsimilars
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindSimilarRequest'
        description: Request body for Find Similar.
        required: true
components:
  schemas:
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    SimilarFace:
      type: object
      required:
      - confidence
      description: Response body for find similar face operation.
      properties:
        faceId:
          type: string
          format: uuid
          description: FaceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire at the time specified by faceIdTimeToLive after the detection call
        persistedFaceId:
          type: string
          format: uuid
          description: PersistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response
        confidence:
          description: Similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1].
          $ref: '#/components/schemas/Confidence'
    FindSimilarRequest:
      type: object
      required:
      - faceId
      description: Request body for find similar operation.
      properties:
        faceId:
          type: string
          format: uuid
          description: FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire at the time specified by faceIdTimeToLive after the detection call
        faceListId:
          type: string
          description: An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time.
          maxLength: 64
          pattern: ^[a-z0-9-_]+$
        largeFaceListId:
          type: string
          description: An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time.
          maxLength: 64
          pattern: ^[a-z0-9-_]+$
        faceIds:
          type: array
          description: An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire at the time specified by faceIdTimeToLive after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time.
          maxItems: 1000
          items:
            type: string
            format: uuid
        maxNumOfCandidatesReturned:
          type: integer
          description: The number of top similar faces returned. The valid range is [1, 1000].
          default: 20
          minimum: 1
          maximum: 1000
        mode:
          type: string
          description: Similar face searching mode. It can be "matchPerson" or "matchFace".
          default: matchPerson
          x-ms-enum:
            name: FindSimilarMatchMode
            modelAsString: false
          enum:
          - matchPerson
          - matchFace
    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
    SimilarFaces:
      type: array
      items:
        $ref: '#/components/schemas/SimilarFace'
  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