swagger: "2.0"
schemes:
  - https
host: azure.local
info:
  description: An API for face detection, verification, and identification.
  title: Face Client
  version: "1.0"
  x-apisguru-categories:
    - cloud
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_assets.onestore.ms_cdnfiles_onestorerolling-1606-01000_shell_v3_images_logo_microsoft.png
  x-origin:
    - format: swagger
      url: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json
      version: "2.0"
  x-providerName: azure.com
  x-serviceName: cognitiveservices-Face
  x-tags:
    - Azure
    - Microsoft
securityDefinitions:
  apim_key:
    in: header
    name: Ocp-Apim-Subscription-Key
    type: apiKey
security:
  - apim_key: []
parameters:
  Endpoint:
    description: "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com)."
    in: path
    name: Endpoint
    required: true
    type: string
    x-ms-parameter-location: client
    x-ms-skip-url-encoding: true
  applyScope:
    collectionFormat: csv
    description: User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take.
    in: query
    items:
      format: uuid
      type: string
      x-nullable: false
    name: applyScope
    required: false
    type: array
    x-ms-parameter-location: method
  detectionModel:
    default: detection_01
    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.
    enum:
      - detection_01
      - detection_02
    in: query
    name: detectionModel
    required: false
    type: string
    x-ms-enum:
      modelAsString: true
      name: DetectionModel
    x-ms-parameter-location: method
    x-nullable: false
  faceListId:
    description: Id referencing a particular face list.
    in: path
    maxLength: 64
    name: faceListId
    pattern: ^[a-z0-9-_]+$
    required: true
    type: string
    x-ms-parameter-location: method
  faceUserData:
    description: User-specified data about the face for any purpose. The maximum length is 1KB.
    in: query
    maxLength: 1024
    name: userData
    required: false
    type: string
    x-ms-parameter-location: method
  largeFaceListId:
    description: Id referencing a particular large face list.
    in: path
    maxLength: 64
    name: largeFaceListId
    pattern: ^[a-z0-9-_]+$
    required: true
    type: string
    x-ms-parameter-location: method
  largePersonGroupId:
    description: Id referencing a particular large person group.
    in: path
    maxLength: 64
    name: largePersonGroupId
    pattern: ^[a-z0-9-_]+$
    required: true
    type: string
    x-ms-parameter-location: method
  operationId:
    description: Id referencing a particular take/apply snapshot operation.
    format: uuid
    in: path
    name: operationId
    required: true
    type: string
    x-ms-parameter-location: method
  persistedFaceId:
    description: Id referencing a particular persistedFaceId of an existing face.
    format: uuid
    in: path
    name: persistedFaceId
    required: true
    type: string
    x-ms-parameter-location: method
  personGroupId:
    description: Id referencing a particular person group.
    in: path
    maxLength: 64
    name: personGroupId
    pattern: ^[a-z0-9-_]+$
    required: true
    type: string
    x-ms-parameter-location: method
  personId:
    description: Id referencing a particular person.
    format: uuid
    in: path
    name: personId
    required: true
    type: string
    x-ms-parameter-location: method
  recognitionModel:
    default: recognition_01
    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.
    enum:
      - recognition_01
      - recognition_02
    in: query
    name: recognitionModel
    required: false
    type: string
    x-ms-enum:
      modelAsString: true
      name: RecognitionModel
    x-ms-parameter-location: method
    x-nullable: false
  returnFaceAttributes:
    collectionFormat: csv
    description: Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost.
    in: query
    items:
      enum:
        - age
        - gender
        - headPose
        - smile
        - facialHair
        - glasses
        - emotion
        - hair
        - makeup
        - occlusion
        - accessories
        - blur
        - exposure
        - noise
      type: string
      x-ms-enum:
        modelAsString: false
        name: FaceAttributeType
      x-nullable: false
    name: returnFaceAttributes
    required: false
    type: array
    x-ms-parameter-location: method
  returnRecognitionModel:
    default: false
    description: A value indicating whether the operation should return 'recognitionModel' in response.
    in: query
    name: returnRecognitionModel
    required: false
    type: boolean
    x-ms-parameter-location: method
  snapshotId:
    description: Id referencing a particular snapshot.
    format: uuid
    in: path
    name: snapshotId
    required: true
    type: string
    x-ms-parameter-location: method
  targetFace:
    collectionFormat: csv
    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.
    in: query
    items:
      format: int32
      maxItems: 4
      minItems: 4
      type: integer
      x-nullable: false
    name: targetFace
    required: false
    type: array
    x-ms-parameter-location: method
paths:
  /detect:
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). The stored face feature(s) will expire and be deleted 24 hours 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 and noise. 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) ('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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |

        * 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 [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'recognition_01': | The default recognition model for [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). All those faceIds created before 2019 March are bonded with this recognition model. |
          | 'recognition_02': | Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. |
      operationId: Face_DetectWithUrl
      parameters:
        - default: true
          description: A value indicating whether the operation should return faceIds of detected faces.
          in: query
          name: returnFaceId
          type: boolean
        - default: false
          description: A value indicating whether the operation should return landmarks of the detected faces.
          in: query
          name: returnFaceLandmarks
          type: boolean
        - $ref: "#/parameters/returnFaceAttributes"
        - description: A JSON document with a URL pointing to the image that is to be analyzed.
          in: body
          name: ImageUrl
          required: true
          schema:
            properties:
              url:
                description: Publicly reachable URL of an image
                type: string
            required:
              - url
            type: object
          x-ms-client-flatten: true
          x-ms-parameter-location: method
        - $ref: "#/parameters/recognitionModel"
        - $ref: "#/parameters/returnRecognitionModel"
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected.
          schema:
            $ref: "#/definitions/DetectedFaces"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Detect with url example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            ImageUrl: "{Image Url here}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            recognitionModel: recognition_01
            returnFaceAttributes:
              - age
              - gender
              - headPose
              - smile
              - facialHair
              - glasses
              - emotion
              - hair
              - makeup
              - occlusion
              - accessories
              - blur
              - exposure
              - noise
            returnRecognitionModel: true
          responses:
            "200":
              body:
                - faceAttributes:
                    accessories:
                      - confidence: 0.99
                        type: headWear
                      - confidence: 1
                        type: glasses
                      - confidence: 0.87
                        type: mask
                    age: 71
                    blur:
                      blurLevel: Medium
                      value: 0.51
                    emotion:
                      anger: 0.575
                      contempt: 0
                      disgust: 0.006
                      fear: 0.008
                      happiness: 0.394
                      neutral: 0.013
                      sadness: 0
                      surprise: 0.004
                    exposure:
                      exposureLevel: GoodExposure
                      value: 0.55
                    facialHair:
                      beard: 0.1
                      moustache: 0.8
                      sideburns: 0.02
                    gender: male
                    glasses: sunglasses
                    hair:
                      bald: 0
                      hairColor:
                        - color: brown
                          confidence: 1
                        - color: blond
                          confidence: 0.88
                        - color: black
                          confidence: 0.48
                        - color: other
                          confidence: 0.11
                        - color: gray
                          confidence: 0.07
                        - color: red
                          confidence: 0.03
                      invisible: false
                    headPose:
                      pitch: 1.6
                      roll: 2.1
                      yaw: 3
                    makeup:
                      eyeMakeup: true
                      lipMakeup: false
                    noise:
                      noiseLevel: Low
                      value: 0.12
                    occlusion:
                      eyeOccluded: false
                      foreheadOccluded: false
                      mouthOccluded: false
                    smile: 0.88
                  faceId: c5c24a82-6845-4031-9d5d-978df9175426
                  faceLandmarks:
                    eyeLeftBottom:
                      x: 413
                      y: 80.1
                    eyeLeftInner:
                      x: 418.9
                      y: 78
                    eyeLeftOuter:
                      x: 406.7
                      y: 80.6
                    eyeLeftTop:
                      x: 412.2
                      y: 76.2
                    eyeRightBottom:
                      x: 447
                      y: 75.3
                    eyeRightInner:
                      x: 441.5
                      y: 75
                    eyeRightOuter:
                      x: 451.7
                      y: 73.4
                    eyeRightTop:
                      x: 446.4
                      y: 71.7
                    eyebrowLeftInner:
                      x: 425.4
                      y: 70.5
                    eyebrowLeftOuter:
                      x: 397.9
                      y: 78.5
                    eyebrowRightInner:
                      x: 4.8
                      y: 69.7
                    eyebrowRightOuter:
                      x: 5.5
                      y: 68.5
                    mouthLeft:
                      x: 417.8
                      y: 114.4
                    mouthRight:
                      x: 451.3
                      y: 109.3
                    noseLeftAlarOutTip:
                      x: 424.3
                      y: 96.4
                    noseLeftAlarTop:
                      x: 428.3
                      y: 89.7
                    noseRightAlarOutTip:
                      x: 446.6
                      y: 92.5
                    noseRightAlarTop:
                      x: 442.2
                      y: 87
                    noseRootLeft:
                      x: 428
                      y: 77.1
                    noseRootRight:
                      x: 435.8
                      y: 75.6
                    noseTip:
                      x: 437.7
                      y: 92.4
                    pupilLeft:
                      x: 412.7
                      y: 78.4
                    pupilRight:
                      x: 446.8
                      y: 74.2
                    underLipBottom:
                      x: 437.3
                      y: 114.5
                    underLipTop:
                      x: 436.8
                      y: 111.4
                    upperLipBottom:
                      x: 437.6
                      y: 108.2
                    upperLipTop:
                      x: 437.6
                      y: 105.9
                  faceRectangle:
                    height: 78
                    left: 394
                    top: 54
                    width: 78
                  recognitionModel: recognition_01
  /facelists:
    get:
      description: |
        List face lists’ faceListId, name, userData and recognitionModel. <br /> 
        To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c)
      operationId: FaceList_List
      parameters:
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of faceList.
          schema:
            $ref: "#/definitions/FaceLists"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List Face lists example:
          parameters:
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            returnRecognitionModel: true
          responses:
            "200":
              body:
                - faceListId: sample_face_list
                  name: list1
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the face list.
  "/facelists/{faceListId}":
    delete:
      description: Delete a specified face list.
      operationId: FaceList_Delete
      parameters:
        - $ref: "#/parameters/faceListId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            faceListId: sample_face_list
          responses:
            "200": {}
    get:
      description: |
        Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.
      operationId: FaceList_Get
      parameters:
        - $ref: "#/parameters/faceListId"
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the face list's information.
          schema:
            $ref: "#/definitions/FaceList"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get Face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            faceListId: sample_face_list
            returnRecognitionModel: true
          responses:
            "200":
              body:
                faceListId: sample_list
                name: list1
                persistedFaces:
                  - persistedFaceId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBD
                    userData: User-provided data attached to the face.
                recognitionModel: recognition_01
                userData: User-provided data attached to the face list.
    patch:
      consumes:
        - application/json
      description: Update information of a face list.
      operationId: FaceList_Update
      parameters:
        - $ref: "#/parameters/faceListId"
        - description: Request body for updating a face list.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: list1
              userData: User-provided data attached to the face list.
            faceListId: sample_face_list
          responses:
            "200": {}
    put:
      consumes:
        - application/json
      description: |-
        Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription.
        <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
        <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called.
        <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
        <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces.
        <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model.
        * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model.
        * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.
      operationId: FaceList_Create
      parameters:
        - $ref: "#/parameters/faceListId"
        - description: Request body for creating a face list.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/MetaDataContract"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: sample_list
              recognitionModel: recognition_01
              userData: User-provided data attached to the face list.
            faceListId: sample_face_list
          responses:
            "200": {}
  "/facelists/{faceListId}/persistedfaces":
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: FaceList_AddFaceFromUrl
      parameters:
        - $ref: "#/parameters/faceListId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: A JSON document with a URL pointing to the image that is to be analyzed.
          in: body
          name: ImageUrl
          required: true
          schema:
            properties:
              url:
                description: Publicly reachable URL of an image
                type: string
            required:
              - url
            type: object
          x-ms-client-flatten: true
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create face list face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            ImageUrl: "{Image url}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            faceListId: sample_face_list
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{Customized user data}"
          responses:
            "200":
              body:
                persistedFaceId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA
  "/facelists/{faceListId}/persistedfaces/{persistedFaceId}":
    delete:
      description: |-
        Delete a face from a face list by specified faceListId and persistedFaceId.
        <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
      operationId: FaceList_DeleteFace
      parameters:
        - $ref: "#/parameters/faceListId"
        - $ref: "#/parameters/persistedFaceId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete face in face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            faceListId: sample_face_list
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
          responses:
            "200": {}
  /findsimilars:
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity.
        <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces.
        <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list.
      operationId: Face_FindSimilar
      parameters:
        - description: Request body for Find Similar.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/FindSimilarRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of the most similar faces represented in faceId if the input parameter is faceIds or persistedFaceId if the input parameter is faceListId.
          schema:
            $ref: "#/definitions/SimilarFaces"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Find similar results example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              faceId: c5c24a82-6845-4031-9d5d-978df9175426
              largeFaceListId: sample_list
              maxNumOfCandidatesReturned: 1
              mode: matchPerson
          responses:
            "200":
              body:
                - confidence: 0.82
                  persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
  /group:
    post:
      consumes:
        - application/json
      description: |
        Divide candidate faces into groups based on face similarity.<br />
        * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result.
        * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts.
        * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces.
        * The 'recognitionModel' associated with the query faces' faceIds should be the same.
      operationId: Face_Group
      parameters:
        - description: Request body for grouping.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/GroupRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.
          schema:
            $ref: "#/definitions/GroupResult"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              faceIds:
                - c5c24a82-6845-4031-9d5d-978df9175426
                - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                - 65d083d4-9447-47d1-af30-b626144bf0fb
                - fce92aed-d578-4d2e-8114-068f8af4492e
                - 30ea1073-cc9e-4652-b1e3-d08fb7b95315
                - be386ab3-af91-4104-9e6d-4dae4c9fddb7
                - fbd2a038-dbff-452c-8e79-2ee81b1aa84e
                - b64d5e15-8257-4af2-b20a-5a750f8940e7
          responses:
            "200":
              body:
                groups:
                  - - c5c24a82-6845-4031-9d5d-978df9175426
                    - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                    - fce92aed-d578-4d2e-8114-068f8af4492e
                    - b64d5e15-8257-4af2-b20a-5a750f8940e7
                  - - 65d083d4-9447-47d1-af30-b626144bf0fb
                    - 30ea1073-cc9e-4652-b1e3-d08fb7b95315
                messyGroup:
                  - be386ab3-af91-4104-9e6d-4dae4c9fddb7
  /identify:
    post:
      consumes:
        - application/json
      description: |
        1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.
        <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4).
        <br/>
         
        Remarks:<br />
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) 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: Face_Identify
      parameters:
        - description: Request body for identify operation.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/IdentifyRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the identified candidate person(s) for each query face.
          schema:
            $ref: "#/definitions/IdentifyResults"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Identify example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              confidenceThreshold: 0.5
              faceIds:
                - c5c24a82-6845-4031-9d5d-978df9175426
                - 65d083d4-9447-47d1-af30-b626144bf0fb
              largePersonGroupId: sample_group
              maxNumOfCandidatesReturned: 1
          responses:
            "200":
              body:
                - candidates:
                    - confidence: 0.92
                      personId: 25985303-c537-4467-b41d-bdb45cd95ca1
                  faceId: c5c24a82-6845-4031-9d5d-978df9175426
                - candidates:
                    - confidence: 0.89
                      personId: 2ae4935b-9659-44c3-977f-61fac20d0538
                  faceId: 65d083d4-9447-47d1-af30-b626144bf0fb
  /largefacelists:
    get:
      description: |
        List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> 
        To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br />
        * Large face lists are stored in alphabetical order of largeFaceListId.
        * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item.
        * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call.
        <br />
        For example, total 5 large person lists: "list1", ..., "list5".
        <br /> "start=&top=" will return all 5 lists.
        <br /> "start=&top=2" will return "list1", "list2".
        <br /> "start=list2&top=3" will return "list3", "list4", "list5".
      operationId: LargeFaceList_List
      parameters:
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of largeFaceList.
          schema:
            $ref: "#/definitions/LargeFaceLists"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List large face lists example:
          parameters:
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            returnRecognitionModel: true
          responses:
            "200":
              body:
                - largeFaceListId: f92f6f1b-3258-4444-8fa2-c2df505cc7ac
                  name: large-face-list-name1
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the large face list.
                - largeFaceListId: c76f7f13-0ed3-4d00-8a3e-2ad3d78f6c37
                  name: large-face-list-name2
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the large face list.
  "/largefacelists/{largeFaceListId}":
    delete:
      description: Delete a specified large face list.
      operationId: LargeFaceList_Delete
      parameters:
        - $ref: "#/parameters/largeFaceListId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete large face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: sample_face_list
          responses:
            "200": {}
    get:
      description: Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
      operationId: LargeFaceList_Get
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the large face list's information.
          schema:
            $ref: "#/definitions/LargeFaceList"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get large face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: f92f6f1b-3258-4444-8fa2-c2df505cc7ac
            returnRecognitionModel: true
          responses:
            "200":
              body:
                largeFaceListId: f92f6f1b-3258-4444-8fa2-c2df505cc7ac
                name: large-face-list-name
                recognitionModel: recognition_01
                userData: User-provided data attached to the large face list.
    patch:
      consumes:
        - application/json
      description: Update information of a large face list.
      operationId: LargeFaceList_Update
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - description: Request body for updating a large face list.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update large face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: large-face-list-name
              userData: User-provided data attached to the large face list.
            largeFaceListId: sample_face_list
          responses:
            "200": {}
    put:
      consumes:
        - application/json
      description: |-
        Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel.
        <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
        <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called.
        <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
        <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model.
        * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model.
        * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.

        Large face list quota:
        * Free-tier subscription quota: 64 large face lists.
        * S0-tier subscription quota: 1,000,000 large face lists.
      operationId: LargeFaceList_Create
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - description: Request body for creating a large face list.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/MetaDataContract"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new large face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: large-face-list-name
              recognitionModel: recognition_01
              userData: User-provided data attached to the large face list.
            largeFaceListId: sample_face_list
          responses:
            "200": {}
  "/largefacelists/{largeFaceListId}/persistedfaces":
    get:
      description: List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face).
      operationId: LargeFaceList_ListFaces
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - description: Starting face id to return (used to list a range of faces).
          in: query
          name: start
          required: false
          type: string
        - description: Number of faces to return starting with the face id indicated by the 'start' parameter.
          in: query
          maximum: 1000
          minimum: 1
          name: top
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of face information that belong to the large face list.
          schema:
            $ref: "#/definitions/PersistedFaces"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List faces in large face list:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: abc
            start: 25985303-c537-4467-b41d-bdb45cd95ca1
            top: 2
          responses:
            "200":
              body:
                - persistedFaceId: 8a887ac2-53fd-4f55-9024-1ec77eecd08e
                  userData: User-provided data attached to the large face list face.
                - persistedFaceId: f92f6f1b-3258-4444-8fa2-c2df505cc7ac
                  userData: User-provided data attached to the large face list face.
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [LargeFaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |

        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_AddFaceFromUrl
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: A JSON document with a URL pointing to the image that is to be analyzed.
          in: body
          name: ImageUrl
          required: true
          schema:
            properties:
              url:
                description: Publicly reachable URL of an image
                type: string
            required:
              - url
            type: object
          x-ms-client-flatten: true
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create large face list face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            ImageUrl: "{Image url}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            largeFaceListId: sample_face_list
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{Customized user data}"
          responses:
            "200":
              body:
                persistedFaceId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA
  "/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}":
    delete:
      description: |-
        Delete a face from a large face list by specified largeFaceListId and persistedFaceId.
        <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel.
      operationId: LargeFaceList_DeleteFace
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/persistedFaceId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete face in large face list example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: sample_face_list
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
          responses:
            "200": {}
    get:
      description: Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).
      operationId: LargeFaceList_GetFace
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/persistedFaceId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns target persisted face's information (persistedFaceId and userData).
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get persisted face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: abc
            persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
          responses:
            "200":
              body:
                persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                userData: User-provided data attached to the face.
    patch:
      consumes:
        - application/json
      description: Update a persisted face's userData field.
      operationId: LargeFaceList_UpdateFace
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/persistedFaceId"
        - description: Request body for updating persisted face.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/UpdateFaceRequest"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              userData: User-provided data attached to the face.
            largeFaceListId: abc
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
          responses:
            "200": {}
  "/largefacelists/{largeFaceListId}/train":
    post:
      description: Queue a large face list training task, the training task may not be started immediately.
      operationId: LargeFaceList_Train
      parameters:
        - $ref: "#/parameters/largeFaceListId"
      produces:
        - application/json
      responses:
        "202":
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Queue large face list training:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: abc
          responses:
            "202": {}
  "/largefacelists/{largeFaceListId}/training":
    get:
      description: Retrieve the training status of a large face list (completed or ongoing).
      operationId: LargeFaceList_GetTrainingStatus
      parameters:
        - $ref: "#/parameters/largeFaceListId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the large face list's training status.
          schema:
            $ref: "#/definitions/TrainingStatus"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get large face list's training status example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largeFaceListId: abc
          responses:
            "200":
              body:
                createdDateTime: 2017-12-21T12:57:27.00Z
                lastActionDateTime: 2017-12-21T12:57:30.00Z
                lastSuccessfulTrainingDateTime: 2017-12-21T12:57:30.00Z
                message: null
                status: succeeded
  /largepersongroups:
    get:
      description: |
        List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br />
        * Large person groups are stored in alphabetical order of largePersonGroupId.
        * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item.
        * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call.
        <br />
        For example, total 5 large person groups: "group1", ..., "group5".
        <br /> "start=&top=" will return all 5 groups.
        <br /> "start=&top=2" will return "group1", "group2".
        <br /> "start=group2&top=3" will return "group3", "group4", "group5".
      operationId: LargePersonGroup_List
      parameters:
        - description: List large person groups from the least largePersonGroupId greater than the "start".
          in: query
          maxLength: 64
          name: start
          required: false
          type: string
        - default: 1000
          description: The number of large person groups to list.
          in: query
          maximum: 1000
          minimum: 1
          name: top
          required: false
          type: integer
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of large person groups and their information.
          schema:
            $ref: "#/definitions/LargePersonGroups"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List large person groups example:
          parameters:
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            returnRecognitionModel: true
            start: sample_group
            top: 2
          responses:
            "200":
              body:
                - largePersonGroupId: f92f6f1b-3258-4444-8fa2-c2df505cc7ac
                  name: large-person-group-name1
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the large person group.
                - largePersonGroupId: c76f7f13-0ed3-4d00-8a3e-2ad3d78f6c37
                  name: large-person-group-name2
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the large person group.
  "/largepersongroups/{largePersonGroupId}":
    delete:
      description: Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted.
      operationId: LargePersonGroup_Delete
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete a large person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
          responses:
            "200": {}
    get:
      description: |
        Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group.
      operationId: LargePersonGroup_Get
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the large person group's information.
          schema:
            $ref: "#/definitions/LargePersonGroup"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get large person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            returnRecognitionModel: true
          responses:
            "200":
              body:
                largePersonGroupId: d408cb4e-2f5f-4b4d-b99e-f0b72870e5b5
                name: large-person-group-name
                recognitionModel: recognition_01
                userData: User-provided data attached to the large person group.
    patch:
      consumes:
        - application/json
      description: Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated.
      operationId: LargePersonGroup_Update
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - description: Request body for updating large person group.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update large person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: group1
              userData: user-provided data attached to the large person group.
            largePersonGroupId: abc
          responses:
            "200": {}
    put:
      consumes:
        - application/json
      description: |-
        Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel.
        <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000
        people.
        <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
        <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called.
        <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model.
        * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model.
        * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.

        Large person group quota:
        * Free-tier subscription quota: 1,000 large person groups.
        * S0-tier subscription quota: 1,000,000 large person groups.
      operationId: LargePersonGroup_Create
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - description: Request body for creating new large person group.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/MetaDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new large person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: large-person-group-name
              recognitionModel: recognition_01
              userData: User-provided data attached to the large person group.
            largePersonGroupId: abc
          responses:
            "200": {}
  "/largepersongroups/{largePersonGroupId}/persons":
    get:
      description: List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
      operationId: LargePersonGroupPerson_List
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - description: Starting person id to return (used to list a range of persons).
          in: query
          name: start
          required: false
          type: string
        - description: Number of persons to return starting with the person id indicated by the 'start' parameter.
          in: query
          maximum: 1000
          minimum: 1
          name: top
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of person information that belong to the large person group.
          schema:
            $ref: "#/definitions/Persons"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List persons in person group:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            start: 25985303-c537-4467-b41d-bdb45cd95ca1
            top: 2
          responses:
            "200":
              body:
                - name: person-name1
                  persistedFaceIds:
                    - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                    - fce92aed-d578-4d2e-8114-068f8af4492e
                    - b64d5e15-8257-4af2-b20a-5a750f8940e7
                  personId: 25985303-c537-4467-b41d-bdb45cd95ca1
                  userData: User-provided data attached to the person.
                - name: person-name2
                  persistedFaceIds:
                    - 30ea1073-cc9e-4652-b1e3-d08fb7b95315
                    - fbd2a038-dbff-452c-8e79-2ee81b1aa84e
                  personId: 2ae4935b-9659-44c3-977f-61fac20d0538
                  userData: User-provided data attached to the person.
    post:
      consumes:
        - application/json
      description: Create a new person in a specified large person group.
      operationId: LargePersonGroupPerson_Create
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - description: Request body for creating new person.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new personId created.
          schema:
            $ref: "#/definitions/Person"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new person for large person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: mike
              userData: "{additional data associated with mike}"
            largePersonGroupId: abc
          responses:
            "200":
              body:
                personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
  "/largepersongroups/{largePersonGroupId}/persons/{personId}":
    delete:
      description: Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted.
      operationId: LargePersonGroupPerson_Delete
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete an existing person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
    get:
      description: Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature.
      operationId: LargePersonGroupPerson_Get
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the person's information.
          schema:
            $ref: "#/definitions/Person"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200":
              body:
                name: person-name
                persistedFaceIds:
                  - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                  - fce92aed-d578-4d2e-8114-068f8af4492e
                  - b64d5e15-8257-4af2-b20a-5a750f8940e7
                personId: 25985303-c537-4467-b41d-bdb45cd95ca1
                userData: User-provided data attached to the person.
    patch:
      consumes:
        - application/json
      description: Update name or userData of a person.
      operationId: LargePersonGroupPerson_Update
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - description: Request body for person update operation.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: mike
              userData: "{additional data associated with mike}"
            largePersonGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
  "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces":
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [LargePersonGroup Person - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: LargePersonGroupPerson_AddFaceFromUrl
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: A JSON document with a URL pointing to the image that is to be analyzed.
          in: body
          name: ImageUrl
          required: true
          schema:
            properties:
              url:
                description: Publicly reachable URL of an image
                type: string
            required:
              - url
            type: object
          x-ms-client-flatten: true
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add Person face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            ImageUrl: "{Image url}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            largePersonGroupId: abc
            personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{customized User data}"
          responses:
            "200":
              body:
                persistedFaceId: 6e04c175-219e-42a2-9d26-0e7b790e1ef4
  "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}":
    delete:
      description: |-
        Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId.
        <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
      operationId: LargePersonGroupPerson_DeleteFace
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete face from person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
    get:
      description: Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId).
      operationId: LargePersonGroupPerson_GetFace
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns target persisted face's information (persistedFaceId and userData).
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get persisted face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
            persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
            personId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA
          responses:
            "200":
              body:
                persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                userData: User-provided data attached to the person face.
    patch:
      consumes:
        - application/json
      description: Update a person persisted face's userData field.
      operationId: LargePersonGroupPerson_UpdateFace
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
        - description: Request body for updating persisted face.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/UpdateFaceRequest"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update person face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              userData: User-provided data attached to the face.
            largePersonGroupId: abc
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
  "/largepersongroups/{largePersonGroupId}/train":
    post:
      description: Queue a large person group training task, the training task may not be started immediately.
      operationId: LargePersonGroup_Train
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
      produces:
        - application/json
      responses:
        "202":
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Queue large person group training:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
          responses:
            "202": {}
  "/largepersongroups/{largePersonGroupId}/training":
    get:
      description: Retrieve the training status of a large person group (completed or ongoing).
      operationId: LargePersonGroup_GetTrainingStatus
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the large person group's training status.
          schema:
            $ref: "#/definitions/TrainingStatus"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get large person group's training status example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            largePersonGroupId: abc
          responses:
            "200":
              body:
                createdDateTime: 2017-12-21T12:57:27.00Z
                lastActionDateTime: 2017-12-21T12:57:30.00Z
                lastSuccessfulTrainingDateTime: 2017-12-21T12:57:30.00Z
                message: null
                status: succeeded
  "/operations/{operationId}":
    get:
      description: Retrieve the status of a take/apply snapshot operation.
      operationId: Snapshot_GetOperationStatus
      parameters:
        - $ref: "#/parameters/operationId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the snapshot operation's status.
          schema:
            $ref: "#/definitions/OperationStatus"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get snapshot operation status example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            operationId: a63a3bdd-a1db-4d05-87b8-dbad6850062a
          responses:
            "200":
              body:
                createdTime: 2018-12-25T11:41:02.2331413Z
                lastActionTime: 2018-12-25T11:51:27.8705696Z
                message: null
                resourceLocation: /snapshots/e58b3f08-1e8b-4165-81df-aa9858f233dc
                status: succeeded
  /persongroups:
    get:
      description: |
        List person groups’ personGroupId, name, userData and recognitionModel.<br />
        * 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.
        <br />
        For example, total 5 person groups: "group1", ..., "group5".
        <br /> "start=&top=" will return all 5 groups.
        <br /> "start=&top=2" will return "group1", "group2".
        <br /> "start=group2&top=3" will return "group3", "group4", "group5".
      operationId: PersonGroup_List
      parameters:
        - description: List person groups from the least personGroupId greater than the "start".
          in: query
          maxLength: 64
          name: start
          required: false
          type: string
        - default: 1000
          description: The number of person groups to list.
          in: query
          maximum: 1000
          minimum: 1
          name: top
          required: false
          type: integer
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of person groups and their information.
          schema:
            $ref: "#/definitions/PersonGroups"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List person groups example:
          parameters:
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            returnRecognitionModel: true
            start: sample_group
            top: 2
          responses:
            "200":
              body:
                - name: group1
                  personGroupId: sample_group
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the person group.
                - name: group2
                  personGroupId: sample_group2
                  recognitionModel: recognition_01
                  userData: User-provided data attached to the person group.
  "/persongroups/{personGroupId}":
    delete:
      description: Delete an existing person group. Persisted face features of all people in the person group will also be deleted.
      operationId: PersonGroup_Delete
      parameters:
        - $ref: "#/parameters/personGroupId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete a person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
          responses:
            "200": {}
    get:
      description: Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241).
      operationId: PersonGroup_Get
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/returnRecognitionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the person group's information.
          schema:
            $ref: "#/definitions/PersonGroup"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
            returnRecognitionModel: true
          responses:
            "200":
              body:
                name: group1
                personGroupId: sample_group
                recognitionModel: recognition_01
                userData: User-provided data attached to the person group.
    patch:
      consumes:
        - application/json
      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: PersonGroup_Update
      parameters:
        - $ref: "#/parameters/personGroupId"
        - description: Request body for updating person group.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: group1
              userData: user-provided data attached to the person group.
            personGroupId: abc
          responses:
            "200": {}
    put:
      consumes:
        - application/json
      description: |-
        Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel.
        <br /> A person group is the container of the uploaded person data, including face recognition features.
        <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
        <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
        <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model.
        * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model.
        * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.

        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](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d).
      operationId: PersonGroup_Create
      parameters:
        - $ref: "#/parameters/personGroupId"
        - description: Request body for creating new person group.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/MetaDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: group1
              recognitionModel: recognition_01
              userData: user-provided data attached to the person group.
            personGroupId: abc
          responses:
            "200": {}
  "/persongroups/{personGroupId}/persons":
    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: PersonGroupPerson_List
      parameters:
        - $ref: "#/parameters/personGroupId"
        - description: Starting person id to return (used to list a range of persons).
          in: query
          name: start
          required: false
          type: string
        - description: Number of persons to return starting with the person id indicated by the 'start' parameter.
          in: query
          maximum: 1000
          minimum: 1
          name: top
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of person information that belong to the person group.
          schema:
            $ref: "#/definitions/Persons"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List persons in person group:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
            start: 25985303-c537-4467-b41d-bdb45cd95ca1
            top: 2
          responses:
            "200":
              body:
                - name: Ryan
                  persistedFaceIds:
                    - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                    - fce92aed-d578-4d2e-8114-068f8af4492e
                    - b64d5e15-8257-4af2-b20a-5a750f8940e7
                  personId: 25985303-c537-4467-b41d-bdb45cd95ca1
                  userData: User-provided data attached to the person
                - name: David
                  persistedFaceIds:
                    - 30ea1073-cc9e-4652-b1e3-d08fb7b95315
                    - fbd2a038-dbff-452c-8e79-2ee81b1aa84e
                  personId: 2ae4935b-9659-44c3-977f-61fac20d0538
                  userData: User-provided data attached to the person
    post:
      consumes:
        - application/json
      description: Create a new person in a specified person group.
      operationId: PersonGroupPerson_Create
      parameters:
        - $ref: "#/parameters/personGroupId"
        - description: Request body for creating new person.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new personId created.
          schema:
            $ref: "#/definitions/Person"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Create new person for person group example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: mike
              userData: "{additional data associated with mike}"
            personGroupId: abc
          responses:
            "200":
              body:
                personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
  "/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: PersonGroupPerson_Delete
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete an existing person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
    get:
      description: Retrieve a person's information, including registered persisted faces, name and userData.
      operationId: PersonGroupPerson_Get
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the person's information.
          schema:
            $ref: "#/definitions/Person"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200":
              body:
                name: Ryan
                persistedFaceIds:
                  - 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                  - fce92aed-d578-4d2e-8114-068f8af4492e
                  - b64d5e15-8257-4af2-b20a-5a750f8940e7
                personId: 25985303-c537-4467-b41d-bdb45cd95ca1
                userData: User-provided data attached to the person.
    patch:
      consumes:
        - application/json
      description: Update name or userData of a person.
      operationId: PersonGroupPerson_Update
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - description: Request body for person update operation.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/NameAndUserDataContract"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              name: mike
              userData: "{additional data associated with mike}"
            personGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
  "/persongroups/{personGroupId}/persons/{personId}/persistedfaces":
    post:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        *   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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [PersonGroup Person - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: PersonGroupPerson_AddFaceFromUrl
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: A JSON document with a URL pointing to the image that is to be analyzed.
          in: body
          name: ImageUrl
          required: true
          schema:
            properties:
              url:
                description: Publicly reachable URL of an image
                type: string
            required:
              - url
            type: object
          x-ms-client-flatten: true
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add Person face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            ImageUrl: "{Image url}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            personGroupId: abc
            personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{customized User data}"
          responses:
            "200":
              body:
                persistedFaceId: 6e04c175-219e-42a2-9d26-0e7b790e1ef4
  "/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}":
    delete:
      description: |-
        Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId.
        <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
      operationId: PersonGroupPerson_DeleteFace
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete face from person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
            personGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
    get:
      description: Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).
      operationId: PersonGroupPerson_GetFace
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns target persisted face's information (persistedFaceId and userData).
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get persisted face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            persistedFaceId: asd
            personGroupId: abc
            personId: foobar
          responses:
            "200":
              body:
                persistedFaceId: 015839fb-fbd9-4f79-ace9-7675fc2f1dd9
                userData: User-provided data attached to the person face.
    patch:
      consumes:
        - application/json
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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: PersonGroupPerson_UpdateFace
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/persistedFaceId"
        - description: Request body for updating persisted face.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/UpdateFaceRequest"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update person face example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              userData: User-provided data attached to the face.
            persistedFaceId: 62004fa7-1ac0-478e-9d5a-b38f9e7fbc68
            personGroupId: abc
            personId: 25985303-c537-4467-b41d-bdb45cd95ca1
          responses:
            "200": {}
  "/persongroups/{personGroupId}/train":
    post:
      description: Queue a person group training task, the training task may not be started immediately.
      operationId: PersonGroup_Train
      parameters:
        - $ref: "#/parameters/personGroupId"
      produces:
        - application/json
      responses:
        "202":
          description: The training task was queued successfully.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Queue person group training:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
          responses:
            "202": {}
  "/persongroups/{personGroupId}/training":
    get:
      description: Retrieve the training status of a person group (completed or ongoing).
      operationId: PersonGroup_GetTrainingStatus
      parameters:
        - $ref: "#/parameters/personGroupId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the person group's training status.
          schema:
            $ref: "#/definitions/TrainingStatus"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get person group's training status example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            personGroupId: abc
          responses:
            "200":
              body:
                createdDateTime: 2017-12-21T12:57:27.00Z
                lastActionDateTime: 2017-12-21T12:57:30.00Z
                message: null
                status: succeeded
  /snapshots:
    get:
      description: List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take).
      operationId: Snapshot_List
      parameters:
        - description: User specified object type as a search filter.
          enum:
            - FaceList
            - LargeFaceList
            - LargePersonGroup
            - PersonGroup
          in: query
          name: type
          required: false
          type: string
          x-ms-enum:
            modelAsString: false
            name: SnapshotObjectType
        - $ref: "#/parameters/applyScope"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of snapshots with snapshot information.
          schema:
            $ref: "#/definitions/Snapshots"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        List snapshots example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            applyScope:
              - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
            type: FaceList
          responses:
            "200":
              body:
                - account: /subscriptions/f9b96b36-1f5e-4021-8959-51527e26e6d3/resourceGroups/TestRG/providers/Microsoft.CognitiveServices/accounts/FaceTest01
                  applyScope:
                    - 35230F59-AA9C-45E0-AB5E-C859BF1A5429
                    - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
                  createdTime: 2018-12-25T11:41:02.2331413Z
                  id: e58b3f08-1e8b-4165-81df-aa9858f233dc
                  lastUpdateTime: 2018-12-25T11:51:27.8705696Z
                  type: FaceList
                  userData: User-provided data attached to the snapshot1.
                - account: /subscriptions/6622996e-0149-4b22-9703-4216dc948d52/resourceGroups/TestRG/providers/Microsoft.CognitiveServices/accounts/FaceTest01
                  applyScope:
                    - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
                  createdTime: 2018-12-29T17:09:32.3298483Z
                  id: a61e61e4-c3d1-4d33-8ae8-676e6104757d
                  lastUpdateTime: 2018-12-29T17:14:34.5645877Z
                  type: FaceList
                  userData: User-provided data attached to the snapshot2.
    post:
      consumes:
        - application/json
      description: |-
        Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br />
        The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br />
        Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br />
        Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br />
        Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br />
        Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br />
        * Free-tier subscription quota: 100 take operations per month.
        * S0-tier subscription quota: 100 take operations per day.
      operationId: Snapshot_Take
      parameters:
        - description: Request body for taking a snapshot.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/TakeSnapshotRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "202":
          description: The snapshot taking task was queued successfully.
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of taking snapshot. The returned id is the operation id, rather than snapshot id. Snapshot id can be obtained only when the operation status becomes "succeeded" in OperationStatus - Get.
              type: string
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Take a snapshot example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              applyScope:
                - 35230F59-AA9C-45E0-AB5E-C859BF1A5429
                - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
              objectId: source-face-list-id
              type: FaceList
              userData: User-provided data attached to the snapshot.
          responses:
            "202":
              header:
                Operation-Location: /operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a
  "/snapshots/{snapshotId}":
    delete:
      description: Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation.
      operationId: Snapshot_Delete
      parameters:
        - $ref: "#/parameters/snapshotId"
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Delete snapshot example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            snapshotId: e58b3f08-1e8b-4165-81df-aa9858f233dc
          responses:
            "200": {}
    get:
      description: Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take.
      operationId: Snapshot_Get
      parameters:
        - $ref: "#/parameters/snapshotId"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the snapshot's information.
          schema:
            $ref: "#/definitions/Snapshot"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Get snapshot example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            snapshotId: e58b3f08-1e8b-4165-81df-aa9858f233dc
          responses:
            "200":
              body:
                account: /subscriptions/f9b96b36-1f5e-4021-8959-51527e26e6d3/resourceGroups/TestRG/providers/Microsoft.CognitiveServices/accounts/FaceTest01
                applyScope:
                  - 35230F59-AA9C-45E0-AB5E-C859BF1A5429
                  - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
                createdTime: 2018-12-25T11:41:02.2331413Z
                id: e58b3f08-1e8b-4165-81df-aa9858f233dc
                lastUpdateTime: 2018-12-25T11:51:27.8705696Z
                type: FaceList
                userData: User-provided data attached to the snapshot.
    patch:
      consumes:
        - application/json
      description: Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot.
      operationId: Snapshot_Update
      parameters:
        - $ref: "#/parameters/snapshotId"
        - description: Request body for updating a snapshot.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/UpdateSnapshotRequest"
          x-ms-client-flatten: true
      responses:
        "200":
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Update snapshot example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              applyScope:
                - 64084E07-9B7F-4A98-BEA4-9986D3A1EDEB
              userData: User-provided data attached to the snapshot.
            snapshotId: e58b3f08-1e8b-4165-81df-aa9858f233dc
          responses:
            "200": {}
  "/snapshots/{snapshotId}/apply":
    post:
      consumes:
        - application/json
      description: |-
        Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br />
        The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br />
        Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br />
        Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br />
        Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br />
        Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br />
        One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br />
        * Free-tier subscription quota: 100 apply operations per month.
        * S0-tier subscription quota: 100 apply operations per day.
      operationId: Snapshot_Apply
      parameters:
        - $ref: "#/parameters/snapshotId"
        - description: Request body for applying a snapshot.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/ApplySnapshotRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "202":
          description: The snapshot applying task was queued successfully.
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of applying the snapshot by OperationStatus - Get.
              type: string
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Apply snapshot example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              mode: CreateNew
              objectId: target-face-list-id
            snapshotId: e58b3f08-1e8b-4165-81df-aa9858f233dc
          responses:
            "202":
              header:
                Operation-Location: /operations/84276574-2a2a-4540-a1b0-f65d834d225b
  /verify:
    post:
      consumes:
        - application/json
      description: |
        Verify whether two faces belong to a same person or whether one face belongs to a person.
        <br/>
        Remarks:<br />
        * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
        * 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: Face_VerifyFaceToFace
      parameters:
        - description: Request body for face to face verification.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/VerifyFaceToFaceRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the verification result.
          schema:
            $ref: "#/definitions/VerifyResult"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Verify faces example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              faceId1: c5c24a82-6845-4031-9d5d-978df9175426
              faceId2: 815df99c-598f-4926-930a-a734b3fd651c
          responses:
            "200":
              body:
                confidence: 0.9
                isIdentical: true
definitions:
  APIError:
    description: Error information returned by the API
    properties:
      error:
        $ref: "#/definitions/Error"
    type: object
  Accessories:
    description: Properties describing any accessories on a given face.
    items:
      $ref: "#/definitions/Accessory"
    type: array
  Accessory:
    description: Accessory item and corresponding confidence level.
    properties:
      confidence:
        $ref: "#/definitions/Confidence"
        description: Confidence level of an accessory
        x-nullable: false
      type:
        description: Type of an accessory
        enum:
          - headWear
          - glasses
          - mask
        type: string
        x-ms-enum:
          modelAsString: false
          name: AccessoryType
        x-nullable: false
    type: object
  ApplyScope:
    description: Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.
    items:
      format: uuid
      type: string
      x-nullable: false
    type: array
  ApplySnapshotRequest:
    description: Request body for applying snapshot operation.
    properties:
      mode:
        default: CreateNew
        description: Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.
        enum:
          - CreateNew
        type: string
        x-ms-enum:
          modelAsString: false
          name: SnapshotApplyMode
        x-nullable: false
      objectId:
        description: User specified target object id to be created from the snapshot.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
    required:
      - objectId
    type: object
  Blur:
    description: Properties describing any presence of blur within the image.
    properties:
      blurLevel:
        description: An enum value indicating level of blurriness.
        enum:
          - Low
          - Medium
          - High
        type: string
        x-ms-enum:
          modelAsString: false
          name: BlurLevel
        x-nullable: false
      value:
        $ref: "#/definitions/Level"
        description: A number indicating level of blurriness ranging from 0 to 1.
        x-nullable: false
    type: object
  Confidence:
    description: A number ranging from 0 to 1 indicating a level of confidence associated with a property.
    maximum: 1
    minimum: 0
    type: number
  Coordinate:
    description: Coordinates within an image
    properties:
      x:
        description: The horizontal component, in pixels.
        type: number
      y:
        description: The vertical component, in pixels.
        type: number
    required:
      - x
      - y
    type: object
  DetectedFace:
    description: Detected Face object.
    properties:
      faceAttributes:
        $ref: "#/definitions/FaceAttributes"
      faceId:
        format: uuid
        type: string
      faceLandmarks:
        $ref: "#/definitions/FaceLandmarks"
      faceRectangle:
        $ref: "#/definitions/FaceRectangle"
      recognitionModel:
        $ref: "#/definitions/RecognitionModel"
    required:
      - faceRectangle
    type: object
  DetectedFaces:
    items:
      $ref: "#/definitions/DetectedFace"
    type: array
  Emotion:
    description: Properties describing facial emotion in form of confidence ranging from 0 to 1.
    properties:
      anger:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      contempt:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      disgust:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      fear:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      happiness:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      neutral:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      sadness:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      surprise:
        $ref: "#/definitions/Confidence"
        x-nullable: false
    type: object
  Error:
    description: Error body.
    properties:
      code:
        type: string
      message:
        type: string
    type: object
  Exposure:
    description: Properties describing exposure level of the image.
    properties:
      exposureLevel:
        description: An enum value indicating level of exposure.
        enum:
          - UnderExposure
          - GoodExposure
          - OverExposure
        type: string
        x-ms-enum:
          modelAsString: false
          name: ExposureLevel
        x-nullable: false
      value:
        $ref: "#/definitions/Level"
        description: A number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure.
        x-nullable: false
    type: object
  FaceAttributes:
    description: Face Attributes
    properties:
      accessories:
        $ref: "#/definitions/Accessories"
        description: Properties describing any accessories on a given face.
      age:
        description: Age in years
        type: number
      blur:
        $ref: "#/definitions/Blur"
        description: Properties describing any presence of blur within the image.
      emotion:
        $ref: "#/definitions/Emotion"
        description: Properties describing facial emotion in form of confidence ranging from 0 to 1.
      exposure:
        $ref: "#/definitions/Exposure"
        description: Properties describing exposure level of the image.
      facialHair:
        $ref: "#/definitions/FacialHair"
        description: Properties describing facial hair attributes.
      gender:
        description: Possible gender of the face.
        enum:
          - male
          - female
        type: string
        x-ms-enum:
          modelAsString: false
          name: Gender
      glasses:
        description: Glasses type if any of the face.
        enum:
          - noGlasses
          - readingGlasses
          - sunglasses
          - swimmingGoggles
        type: string
        x-ms-enum:
          modelAsString: false
          name: GlassesType
      hair:
        $ref: "#/definitions/Hair"
        description: Properties describing hair attributes.
      headPose:
        $ref: "#/definitions/HeadPose"
        description: Properties indicating head pose of the face.
      makeup:
        $ref: "#/definitions/Makeup"
        description: Properties describing present makeups on a given face.
      noise:
        $ref: "#/definitions/Noise"
        description: Properties describing noise level of the image.
      occlusion:
        $ref: "#/definitions/Occlusion"
        description: Properties describing occlusions on a given face.
      smile:
        $ref: "#/definitions/Level"
        description: "Smile intensity, a number between [0,1] "
    type: object
  FaceLandmarks:
    description: A collection of 27-point face landmarks pointing to the important positions of face components.
    properties:
      eyeLeftBottom:
        $ref: "#/definitions/Coordinate"
      eyeLeftInner:
        $ref: "#/definitions/Coordinate"
      eyeLeftOuter:
        $ref: "#/definitions/Coordinate"
      eyeLeftTop:
        $ref: "#/definitions/Coordinate"
      eyeRightBottom:
        $ref: "#/definitions/Coordinate"
      eyeRightInner:
        $ref: "#/definitions/Coordinate"
      eyeRightOuter:
        $ref: "#/definitions/Coordinate"
      eyeRightTop:
        $ref: "#/definitions/Coordinate"
      eyebrowLeftInner:
        $ref: "#/definitions/Coordinate"
      eyebrowLeftOuter:
        $ref: "#/definitions/Coordinate"
      eyebrowRightInner:
        $ref: "#/definitions/Coordinate"
      eyebrowRightOuter:
        $ref: "#/definitions/Coordinate"
      mouthLeft:
        $ref: "#/definitions/Coordinate"
      mouthRight:
        $ref: "#/definitions/Coordinate"
      noseLeftAlarOutTip:
        $ref: "#/definitions/Coordinate"
      noseLeftAlarTop:
        $ref: "#/definitions/Coordinate"
      noseRightAlarOutTip:
        $ref: "#/definitions/Coordinate"
      noseRightAlarTop:
        $ref: "#/definitions/Coordinate"
      noseRootLeft:
        $ref: "#/definitions/Coordinate"
      noseRootRight:
        $ref: "#/definitions/Coordinate"
      noseTip:
        $ref: "#/definitions/Coordinate"
      pupilLeft:
        $ref: "#/definitions/Coordinate"
      pupilRight:
        $ref: "#/definitions/Coordinate"
      underLipBottom:
        $ref: "#/definitions/Coordinate"
      underLipTop:
        $ref: "#/definitions/Coordinate"
      upperLipBottom:
        $ref: "#/definitions/Coordinate"
      upperLipTop:
        $ref: "#/definitions/Coordinate"
    type: object
  FaceList:
    allOf:
      - $ref: "#/definitions/MetaDataContract"
    description: Face list object.
    properties:
      faceListId:
        description: FaceListId of the target face list.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
      persistedFaces:
        $ref: "#/definitions/PersistedFaces"
        description: Persisted faces within the face list.
    required:
      - faceListId
    type: object
  FaceLists:
    description: An array of face list results, with fields of faceListId, name and userData
    items:
      $ref: "#/definitions/FaceList"
    type: array
  FaceRectangle:
    description: A rectangle within which a face can be found
    properties:
      height:
        description: The height of the rectangle, in pixels.
        format: int32
        type: integer
      left:
        description: The distance from the left edge if the image to the left edge of the rectangle, in pixels.
        format: int32
        type: integer
      top:
        description: The distance from the top edge if the image to the top edge of the rectangle, in pixels.
        format: int32
        type: integer
      width:
        description: The width of the rectangle, in pixels.
        format: int32
        type: integer
    required:
      - width
      - height
      - left
      - top
    type: object
  FacialHair:
    description: Properties describing facial hair attributes.
    properties:
      beard:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      moustache:
        $ref: "#/definitions/Confidence"
        x-nullable: false
      sideburns:
        $ref: "#/definitions/Confidence"
        x-nullable: false
    type: object
  FindSimilarRequest:
    description: Request body for find similar operation.
    properties:
      faceId:
        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 24 hours after the detection call
        format: uuid
        type: string
      faceIds:
        description: An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours 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.
        items:
          format: uuid
          type: string
        maxItems: 1000
        type: array
      faceListId:
        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-_]+$
        type: string
      largeFaceListId:
        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-_]+$
        type: string
      maxNumOfCandidatesReturned:
        default: 20
        description: The number of top similar faces returned. The valid range is [1, 1000].
        maximum: 1000
        minimum: 1
        type: integer
      mode:
        default: matchPerson
        description: Similar face searching mode. It can be "matchPerson" or "matchFace".
        enum:
          - matchPerson
          - matchFace
        type: string
        x-ms-enum:
          modelAsString: false
          name: FindSimilarMatchMode
        x-nullable: false
    required:
      - faceId
    type: object
  GroupRequest:
    description: Request body for group request.
    properties:
      faceIds:
        description: Array of candidate faceId created by Face - Detect. The maximum is 1000 faces
        items:
          format: uuid
          type: string
          x-nullable: false
        maxItems: 1000
        type: array
    required:
      - faceIds
    type: object
  GroupResult:
    description: An array of face groups based on face similarity.
    properties:
      groups:
        description: A partition of the original faces based on face similarity. Groups are ranked by number of faces
        items:
          items:
            format: uuid
            type: string
            x-nullable: false
          type: array
        type: array
      messyGroup:
        description: Face ids array of faces that cannot find any similar faces from original faces.
        items:
          format: uuid
          type: string
          x-nullable: false
        type: array
    required:
      - groups
    type: object
  Hair:
    description: Properties describing hair attributes.
    properties:
      bald:
        $ref: "#/definitions/Confidence"
        description: A number describing confidence level of whether the person is bald.
        x-nullable: false
      hairColor:
        $ref: "#/definitions/HairColors"
        description: An array of candidate colors and confidence level in the presence of each.
      invisible:
        description: A boolean value describing whether the hair is visible in the image.
        type: boolean
        x-nullable: false
    type: object
  HairColor:
    description: Hair color and associated confidence
    properties:
      color:
        description: Name of the hair color.
        enum:
          - unknown
          - white
          - gray
          - blond
          - brown
          - red
          - black
          - other
        type: string
        x-ms-enum:
          modelAsString: false
          name: HairColorType
        x-nullable: false
      confidence:
        $ref: "#/definitions/Confidence"
        description: Confidence level of the color
        x-nullable: false
    type: object
  HairColors:
    items:
      $ref: "#/definitions/HairColor"
    type: array
  HeadPose:
    description: Properties indicating head pose of the face.
    properties:
      pitch:
        type: number
        x-nullable: false
      roll:
        type: number
        x-nullable: false
      yaw:
        type: number
        x-nullable: false
    type: object
  IdentifyCandidate:
    description: All possible faces that may qualify.
    properties:
      confidence:
        $ref: "#/definitions/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).
      personId:
        description: Id of candidate
        format: uuid
        type: string
    required:
      - personId
      - confidence
    type: object
  IdentifyRequest:
    description: Request body for identify face operation.
    properties:
      confidenceThreshold:
        $ref: "#/definitions/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).
      faceIds:
        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].
        items:
          format: uuid
          type: string
          x-nullable: false
        maxItems: 10
        type: array
      largePersonGroupId:
        description: LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
      maxNumOfCandidatesReturned:
        default: 1
        description: The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1).
        maximum: 5
        minimum: 1
        type: integer
      personGroupId:
        description: PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
    required:
      - faceIds
    type: object
  IdentifyResult:
    description: Response body for identify face operation.
    properties:
      candidates:
        description: Identified person candidates for that face (ranked by confidence). Array size should be no larger than input maxNumOfCandidatesReturned. If no person is identified, will return an empty array.
        items:
          $ref: "#/definitions/IdentifyCandidate"
        type: array
      faceId:
        description: FaceId of the query face
        format: uuid
        type: string
    required:
      - faceId
      - candidates
    type: object
  IdentifyResults:
    items:
      $ref: "#/definitions/IdentifyResult"
    type: array
  LargeFaceList:
    allOf:
      - $ref: "#/definitions/MetaDataContract"
    description: Large face list object.
    properties:
      largeFaceListId:
        description: LargeFaceListId of the target large face list.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
    required:
      - largeFaceListId
    type: object
  LargeFaceLists:
    description: An array of large face list results, with fields of largeFaceListId, name and userData
    items:
      $ref: "#/definitions/LargeFaceList"
    type: array
  LargePersonGroup:
    allOf:
      - $ref: "#/definitions/MetaDataContract"
    description: Large person group object.
    properties:
      largePersonGroupId:
        description: LargePersonGroupId of the target large person groups
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
    required:
      - largePersonGroupId
    type: object
  LargePersonGroups:
    description: An array of large person groups.
    items:
      $ref: "#/definitions/LargePersonGroup"
    type: array
  Level:
    description: A number ranging from 0 to 1 indicating the intensity level associated with a property.
    maximum: 1
    minimum: 0
    type: number
  Makeup:
    description: Properties describing present makeups on a given face.
    properties:
      eyeMakeup:
        description: A boolean value describing whether eye makeup is present on a face.
        type: boolean
        x-nullable: false
      lipMakeup:
        description: A boolean value describing whether lip makeup is present on a face.
        type: boolean
        x-nullable: false
    type: object
  MetaDataContract:
    allOf:
      - $ref: "#/definitions/NameAndUserDataContract"
    description: A combination of user defined name and user specified data and recognition model name for largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      recognitionModel:
        $ref: "#/definitions/RecognitionModel"
    type: object
  NameAndUserDataContract:
    description: A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      name:
        description: User defined name, maximum length is 128.
        maxLength: 128
        type: string
      userData:
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
        type: string
    type: object
  Noise:
    description: Properties describing noise level of the image.
    properties:
      noiseLevel:
        description: An enum value indicating level of noise.
        enum:
          - Low
          - Medium
          - High
        type: string
        x-ms-enum:
          modelAsString: false
          name: NoiseLevel
        x-nullable: false
      value:
        $ref: "#/definitions/Level"
        description: A number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level.
        x-nullable: false
    type: object
  Occlusion:
    description: Properties describing occlusions on a given face.
    properties:
      eyeOccluded:
        description: A boolean value indicating whether eyes are occluded.
        type: boolean
        x-nullable: false
      foreheadOccluded:
        description: A boolean value indicating whether forehead is occluded.
        type: boolean
        x-nullable: false
      mouthOccluded:
        description: A boolean value indicating whether the mouth is occluded.
        type: boolean
        x-nullable: false
    type: object
  OperationStatus:
    description: Operation status object. Operation refers to the asynchronous backend task including taking a snapshot and applying a snapshot.
    properties:
      createdTime:
        description: A combined UTC date and time string that describes the time when the operation (take or apply a snapshot) is requested. E.g. 2018-12-25T11:41:02.2331413Z.
        format: date-time
        type: string
      lastActionTime:
        description: A combined UTC date and time string that describes the last time the operation (take or apply a snapshot) is actively migrating data. The lastActionTime will keep increasing until the operation finishes. E.g. 2018-12-25T11:51:27.8705696Z.
        format: date-time
        type: string
      message:
        description: Show failure message when operation fails (omitted when operation succeeds).
        type: string
      resourceLocation:
        description: When the operation succeeds successfully, for snapshot taking operation the snapshot id will be included in this field, and for snapshot applying operation, the path to get the target object will be returned in this field.
        type: string
      status:
        description: 'Operation status: notstarted, running, succeeded, failed. If the operation is requested and waiting to perform, the status is notstarted. If the operation is ongoing in backend, the status is running. Status succeeded means the operation is completed successfully, specifically for snapshot taking operation, it illustrates the snapshot is well taken and ready to apply, and for snapshot applying operation, it presents the target object has finished creating by the snapshot and ready to be used. Status failed is often caused by editing the source object while taking the snapshot or editing the target object while applying the snapshot before completion, see the field "message" to check the failure reason.'
        enum:
          - notstarted
          - running
          - succeeded
          - failed
        type: string
        x-ms-enum:
          modelAsString: false
          name: OperationStatusType
    required:
      - status
      - createdTime
    type: object
  PersistedFace:
    description: PersonFace object.
    properties:
      persistedFaceId:
        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 24 hours after the detection call.
        format: uuid
        type: string
      userData:
        description: User-provided data attached to the face. The size limit is 1KB.
        maxLength: 1024
        type: string
    required:
      - persistedFaceId
    type: object
  PersistedFaces:
    description: An array of persisted faces within the face list or large face list.
    items:
      $ref: "#/definitions/PersistedFace"
    type: array
  Person:
    allOf:
      - $ref: "#/definitions/NameAndUserDataContract"
    description: Person object.
    properties:
      persistedFaceIds:
        description: PersistedFaceIds of registered faces in the person. These persistedFaceIds are returned from Person - Add a Person Face, and will not expire.
        items:
          format: uuid
          type: string
          x-nullable: false
        type: array
      personId:
        description: PersonId of the target face list.
        format: uuid
        type: string
    required:
      - personId
    type: object
  PersonGroup:
    allOf:
      - $ref: "#/definitions/MetaDataContract"
    description: Person group object.
    properties:
      personGroupId:
        description: PersonGroupId of the target person group.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
    required:
      - personGroupId
    type: object
  PersonGroups:
    description: An array of person groups.
    items:
      $ref: "#/definitions/PersonGroup"
    type: array
  Persons:
    description: An array of Persons.
    items:
      $ref: "#/definitions/Person"
    type: array
  RecognitionModel:
    default: recognition_01
    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.
    enum:
      - recognition_01
      - recognition_02
    type: string
    x-ms-enum:
      modelAsString: true
      name: RecognitionModel
    x-nullable: false
  SimilarFace:
    description: Response body for find similar face operation.
    properties:
      confidence:
        $ref: "#/definitions/Confidence"
        description: Similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1].
      faceId:
        description: FaceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call
        format: uuid
        type: string
      persistedFaceId:
        description: PersistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response
        format: uuid
        type: string
    required:
      - confidence
    type: object
  SimilarFaces:
    items:
      $ref: "#/definitions/SimilarFace"
    type: array
  Snapshot:
    description: Snapshot object.
    properties:
      account:
        description: Azure Cognitive Service Face account id of the subscriber who created the snapshot by Snapshot - Take.
        type: string
      applyScope:
        $ref: "#/definitions/ApplyScope"
        description: Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.
      createdTime:
        description: A combined UTC date and time string that describes the created time of the snapshot. E.g. 2018-12-25T11:41:02.2331413Z.
        format: date-time
        type: string
      id:
        description: Snapshot id.
        format: uuid
        type: string
      lastUpdateTime:
        description: A combined UTC date and time string that describes the last time when the snapshot was created or updated by Snapshot - Update. E.g. 2018-12-25T11:51:27.8705696Z.
        format: date-time
        type: string
      type:
        description: Type of the source object in the snapshot, specified by the subscriber who created the snapshot when calling Snapshot - Take. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.
        enum:
          - FaceList
          - LargeFaceList
          - LargePersonGroup
          - PersonGroup
        type: string
        x-ms-enum:
          modelAsString: false
          name: SnapshotObjectType
      userData:
        description: User specified data about the snapshot for any purpose. Length should not exceed 16KB.
        maxLength: 16384
        type: string
    required:
      - id
      - account
      - type
      - applyScope
      - createdTime
      - lastUpdateTime
    type: object
  Snapshots:
    description: An array of snapshots.
    items:
      $ref: "#/definitions/Snapshot"
    type: array
  TakeSnapshotRequest:
    description: Request body for taking snapshot operation.
    properties:
      applyScope:
        $ref: "#/definitions/ApplyScope"
        description: User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.
      objectId:
        description: User specified source object id to take snapshot from.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
      type:
        description: User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.
        enum:
          - FaceList
          - LargeFaceList
          - LargePersonGroup
          - PersonGroup
        type: string
        x-ms-enum:
          modelAsString: false
          name: SnapshotObjectType
      userData:
        description: User specified data about the snapshot for any purpose. Length should not exceed 16KB.
        maxLength: 16384
        type: string
    required:
      - type
      - objectId
      - applyScope
    type: object
  TrainingStatus:
    description: Training status object.
    properties:
      createdDateTime:
        description: A combined UTC date and time string that describes the created time of the person group, large person group or large face list.
        format: date-time
        type: string
        x-ms-client-name: created
      lastActionDateTime:
        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.
        format: date-time
        type: string
        x-ms-client-name: lastAction
      lastSuccessfulTrainingDateTime:
        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.
        format: date-time
        type: string
        x-ms-client-name: lastSuccessfulTraining
      message:
        description: Show failure message when training failed (omitted when training succeed).
        type: string
      status:
        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."
        enum:
          - nonstarted
          - running
          - succeeded
          - failed
        type: string
        x-ms-enum:
          modelAsString: false
          name: TrainingStatusType
    required:
      - status
      - createdDateTime
    type: object
  UpdateFaceRequest:
    description: Request to update face data.
    properties:
      userData:
        description: User-provided data attached to the face. The size limit is 1KB.
        maxLength: 1024
        type: string
    type: object
  UpdateSnapshotRequest:
    description: Request body for updating a snapshot, with a combination of user defined apply scope and user specified data.
    properties:
      applyScope:
        $ref: "#/definitions/ApplyScope"
        description: Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.
      userData:
        description: User specified data about the snapshot for any purpose. Length should not exceed 16KB.
        maxLength: 16384
        type: string
    type: object
  VerifyFaceToFaceRequest:
    description: Request body for face to face verification.
    properties:
      faceId1:
        description: FaceId of the first face, comes from Face - Detect
        format: uuid
        type: string
      faceId2:
        description: FaceId of the second face, comes from Face - Detect
        format: uuid
        type: string
    required:
      - faceId1
      - faceId2
    type: object
  VerifyFaceToPersonRequest:
    description: Request body for face to person verification.
    properties:
      faceId:
        description: FaceId of the face, comes from Face - Detect
        format: uuid
        type: string
      largePersonGroupId:
        description: Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
      personGroupId:
        description: Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
        type: string
      personId:
        description: Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create.
        format: uuid
        type: string
    required:
      - faceId
      - personId
    type: object
  VerifyResult:
    description: Result of the verify operation.
    properties:
      confidence:
        $ref: "#/definitions/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.
      isIdentical:
        description: True if the two faces belong to the same person or the face belongs to the person, otherwise false.
        type: boolean
    required:
      - isIdentical
      - confidence
    type: object
x-ms-parameterized-host:
  hostTemplate: "{Endpoint}/face/v1.0"
  parameters:
    - $ref: "#/parameters/Endpoint"
  useSchemePrefix: false
x-ms-paths:
  /detect?overload=stream:
    post:
      consumes:
        - application/octet-stream
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). The stored face feature(s) will expire and be deleted 24 hours 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 and noise. 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) ('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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |

        * 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 [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'recognition_01': | The default recognition model for [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). All those faceIds created before 2019 March are bonded with this recognition model. |
          | 'recognition_02': | Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. |
      operationId: Face_DetectWithStream
      parameters:
        - default: true
          description: A value indicating whether the operation should return faceIds of detected faces.
          in: query
          name: returnFaceId
          type: boolean
        - default: false
          description: A value indicating whether the operation should return landmarks of the detected faces.
          in: query
          name: returnFaceLandmarks
          type: boolean
        - $ref: "#/parameters/returnFaceAttributes"
        - description: An image stream.
          in: body
          name: Image
          required: true
          schema:
            format: file
            type: object
          x-ms-parameter-location: method
        - $ref: "#/parameters/recognitionModel"
        - $ref: "#/parameters/returnRecognitionModel"
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected.
          schema:
            $ref: "#/definitions/DetectedFaces"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Detect with stream example:
          parameters:
            Content-Type: application/octet-stream
            Endpoint: "{Endpoint}"
            Image: "{Image binary in base 64 format}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            recognitionModel: recognition_01
            returnFaceAttributes:
              - age
              - gender
              - headPose
              - smile
              - facialHair
              - glasses
              - emotion
              - hair
              - makeup
              - occlusion
              - accessories
              - blur
              - exposure
              - noise
            returnRecognitionModel: true
          responses:
            "200":
              body:
                - faceAttributes:
                    accessories:
                      - confidence: 0.99
                        type: headWear
                      - confidence: 1
                        type: glasses
                      - confidence: 0.87
                        type: mask
                    age: 71
                    blur:
                      blurLevel: Medium
                      value: 0.51
                    emotion:
                      anger: 0.575
                      contempt: 0
                      disgust: 0.006
                      fear: 0.008
                      happiness: 0.394
                      neutral: 0.013
                      sadness: 0
                      surprise: 0.004
                    exposure:
                      exposureLevel: GoodExposure
                      value: 0.55
                    facialHair:
                      beard: 0.1
                      moustache: 0.8
                      sideburns: 0.02
                    gender: male
                    glasses: sunglasses
                    hair:
                      bald: 0
                      hairColor:
                        - color: brown
                          confidence: 1
                        - color: blond
                          confidence: 0.88
                        - color: black
                          confidence: 0.48
                        - color: other
                          confidence: 0.11
                        - color: gray
                          confidence: 0.07
                        - color: red
                          confidence: 0.03
                      invisible: false
                    headPose:
                      pitch: 1.6
                      roll: 2.1
                      yaw: 3
                    makeup:
                      eyeMakeup: true
                      lipMakeup: false
                    noise:
                      noiseLevel: Low
                      value: 0.12
                    occlusion:
                      eyeOccluded: false
                      foreheadOccluded: false
                      mouthOccluded: false
                    smile: 0.88
                  faceId: c5c24a82-6845-4031-9d5d-978df9175426
                  faceLandmarks:
                    eyeLeftBottom:
                      x: 413
                      y: 80.1
                    eyeLeftInner:
                      x: 418.9
                      y: 78
                    eyeLeftOuter:
                      x: 406.7
                      y: 80.6
                    eyeLeftTop:
                      x: 412.2
                      y: 76.2
                    eyeRightBottom:
                      x: 447
                      y: 75.3
                    eyeRightInner:
                      x: 441.5
                      y: 75
                    eyeRightOuter:
                      x: 451.7
                      y: 73.4
                    eyeRightTop:
                      x: 446.4
                      y: 71.7
                    eyebrowLeftInner:
                      x: 425.4
                      y: 70.5
                    eyebrowLeftOuter:
                      x: 397.9
                      y: 78.5
                    eyebrowRightInner:
                      x: 4.8
                      y: 69.7
                    eyebrowRightOuter:
                      x: 5.5
                      y: 68.5
                    mouthLeft:
                      x: 417.8
                      y: 114.4
                    mouthRight:
                      x: 451.3
                      y: 109.3
                    noseLeftAlarOutTip:
                      x: 424.3
                      y: 96.4
                    noseLeftAlarTop:
                      x: 428.3
                      y: 89.7
                    noseRightAlarOutTip:
                      x: 446.6
                      y: 92.5
                    noseRightAlarTop:
                      x: 442.2
                      y: 87
                    noseRootLeft:
                      x: 428
                      y: 77.1
                    noseRootRight:
                      x: 435.8
                      y: 75.6
                    noseTip:
                      x: 437.7
                      y: 92.4
                    pupilLeft:
                      x: 412.7
                      y: 78.4
                    pupilRight:
                      x: 446.8
                      y: 74.2
                    underLipBottom:
                      x: 437.3
                      y: 114.5
                    underLipTop:
                      x: 436.8
                      y: 111.4
                    upperLipBottom:
                      x: 437.6
                      y: 108.2
                    upperLipTop:
                      x: 437.6
                      y: 105.9
                  faceRectangle:
                    height: 78
                    left: 394
                    top: 54
                    width: 78
                  recognitionModel: recognition_01
  "/facelists/{faceListId}/persistedfaces?overload=stream":
    post:
      consumes:
        - application/octet-stream
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: FaceList_AddFaceFromStream
      parameters:
        - $ref: "#/parameters/faceListId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: An image stream.
          in: body
          name: Image
          required: true
          schema:
            format: file
            type: object
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add face to face list from stream example:
          parameters:
            Content-Type: application/octet-stream
            Endpoint: "{Endpoint}"
            Image: "{Image stream in base 64 encoded format}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            faceListId: sample_face_list
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{Customized user data}"
          responses:
            "200":
              body:
                persistedFaceId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA
  "/largefacelists/{largeFaceListId}/persistedfaces?overload=stream":
    post:
      consumes:
        - application/octet-stream
      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](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [LargeFaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |

        Quota:
        * Free-tier subscription quota: 1,000 faces per large face list.
        * S0-tier subscription quota: 1,000,000 faces per large face list.
      operationId: LargeFaceList_AddFaceFromStream
      parameters:
        - $ref: "#/parameters/largeFaceListId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: An image stream.
          in: body
          name: Image
          required: true
          schema:
            format: file
            type: object
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns a new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add face to large face list from stream example:
          parameters:
            Content-Type: application/octet-stream
            Endpoint: "{Endpoint}"
            Image: "{Image stream in base 64 encoded format}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            largeFaceListId: sample_face_list
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{Customized user data}"
          responses:
            "200":
              body:
                persistedFaceId: B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA
  "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?overload=stream":
    post:
      consumes:
        - application/octet-stream
      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](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        * 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [LargePersonGroup Person - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: LargePersonGroupPerson_AddFaceFromStream
      parameters:
        - $ref: "#/parameters/largePersonGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: An image stream.
          in: body
          name: Image
          required: true
          schema:
            format: file
            type: object
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add face to person with stream example:
          parameters:
            Content-Type: application/octet-stream
            Endpoint: "{Endpoint}"
            Image: "{Image stream in base 64 encoded format}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            largePersonGroupId: abc
            personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{customized User data}"
          responses:
            "200":
              body:
                persistedFaceId: 6e04c175-219e-42a2-9d26-0e7b790e1ef4
  "/persongroups/{personGroupId}/persons/{personId}/persistedfaces?overload=stream":
    post:
      consumes:
        - application/octet-stream
      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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
        <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
        *   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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), 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/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
          | Model | Recommended use-case(s) |
          | ---------- | -------- |
          | 'detection_01': | The default detection model for [PersonGroup Person - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
          | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
      operationId: PersonGroupPerson_AddFaceFromStream
      parameters:
        - $ref: "#/parameters/personGroupId"
        - $ref: "#/parameters/personId"
        - $ref: "#/parameters/faceUserData"
        - $ref: "#/parameters/targetFace"
        - description: An image stream.
          in: body
          name: Image
          required: true
          schema:
            format: file
            type: object
          x-ms-parameter-location: method
        - $ref: "#/parameters/detectionModel"
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the new persistedFaceId.
          schema:
            $ref: "#/definitions/PersistedFace"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Add face to person with stream example:
          parameters:
            Content-Type: application/octet-stream
            Endpoint: "{Endpoint}"
            Image: "{Image stream in base 64 encoded format}"
            Ocp-Apim-Subscription-Key: "{API key}"
            detectionModel: detection_01
            personGroupId: abc
            personId: 4caa25ee-3bc6-4e88-adf8-12455ce7aab0
            targetFace:
              - 10
              - 10
              - 100
              - 100
            userData: "{customized User data}"
          responses:
            "200":
              body:
                persistedFaceId: 6e04c175-219e-42a2-9d26-0e7b790e1ef4
  /verify?overload=person:
    post:
      consumes:
        - application/json
      description: Verify whether two faces belong to a same person. Compares a face Id with a Person Id
      operationId: Face_VerifyFaceToPerson
      parameters:
        - description: Request body for face to person verification.
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/VerifyFaceToPersonRequest"
          x-ms-client-flatten: true
      produces:
        - application/json
      responses:
        "200":
          description: A successful call returns the verification result.
          schema:
            $ref: "#/definitions/VerifyResult"
        default:
          description: Error response.
          schema:
            $ref: "#/definitions/APIError"
      x-ms-examples:
        Verify face to person example:
          parameters:
            Content-Type: application/json
            Endpoint: "{Endpoint}"
            Ocp-Apim-Subscription-Key: "{API key}"
            body:
              faceId: c5c24a82-6845-4031-9d5d-978df9175426
              largePersonGroupId: sample_group
              personId: 815df99c-598f-4926-930a-a734b3fd651c
          responses:
            "200":
              body:
                confidence: 0.9
                isIdentical: true
