Microsoft Azure Facelists API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Facelists API
schemes:
- https
tags:
- name: Facelists
paths:
  /facelists/{faceListId}:
    put:
      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](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).<br> After creation, user should use [FaceList - Add Face](https://docs.microsoft.com/rest/api/faceapi/facelist/addfacefromurl) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) 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](https://docs.microsoft.com/rest/api/faceapi/persongroup) / [LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup) and [Face - Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br> Please consider [LargeFaceList](https://docs.microsoft.com/rest/api/faceapi/largefacelist) 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.<br>Please Refer to [Specify a face recognition model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
      operationId: microsoftAzureFacelistCreate
      parameters:
      - $ref: '#/parameters/faceListId'
      - name: body
        description: Request body for creating a face list.
        in: body
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/MetaDataContract'
      consumes:
      - application/json
      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:
          $ref: ./examples/CreateNewFaceList.json
      summary: Microsoft Azure Put Facelists Facelistid
      tags:
      - Facelists
    get:
      description: Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.<br>
      operationId: microsoftAzureFacelistGet
      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:
          $ref: ./examples/GetFaceList.json
      summary: Microsoft Azure Get Facelists Facelistid
      tags:
      - Facelists
    patch:
      description: Update information of a face list.
      operationId: microsoftAzureFacelistUpdate
      parameters:
      - $ref: '#/parameters/faceListId'
      - name: body
        description: Request body for updating a face list.
        in: body
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/NameAndUserDataContract'
      consumes:
      - application/json
      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:
        Update face list example:
          $ref: ./examples/UpdateFaceList.json
      summary: Microsoft Azure Patch Facelists Facelistid
      tags:
      - Facelists
    delete:
      description: Delete a specified face list.
      operationId: microsoftAzureFacelistDelete
      parameters:
      - $ref: '#/parameters/faceListId'
      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:
        Delete face list example:
          $ref: ./examples/DeleteFaceList.json
      summary: Microsoft Azure Delete Facelists Facelistid
      tags:
      - Facelists
  /facelists:
    get:
      description: List face lists’ faceListId, name, userData and recognitionModel.  <br>To get face information inside faceList use [FaceList - Get](https://docs.microsoft.com/rest/api/faceapi/facelist/get)<br>
      operationId: microsoftAzureFacelistList
      parameters:
      - $ref: '#/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns an array of faceList.
          schema:
            $ref: '#/definitions/FaceLists'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      produces:
      - application/json
      x-ms-examples:
        List Face lists example:
          $ref: ./examples/ListFaceLists.json
      summary: Microsoft Azure Get Facelists
      tags:
      - Facelists
  /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: microsoftAzureFacelistDeleteface
      parameters:
      - $ref: '#/parameters/faceListId'
      - $ref: '#/parameters/persistedFaceId'
      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:
        Delete face in face list example:
          $ref: ./examples/DeleteFaceListFace.json
      summary: Microsoft Azure Delete Facelists Facelistid Persistedfaces Persistedfaceid
      tags:
      - Facelists
  /facelists/{faceListId}/persistedfaces:
    post:
      description: 'Add a face to a specified face list, up to 1,000 faces.<br> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](https://docs.microsoft.com/rest/api/faceapi/facelist/deleteface) or [FaceList - Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) is called.<br> Note persistedFaceId is different from faceId generated by [Face - Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>* 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.<br>* JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.<br>* "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl), there’s no guarantee to detect and add the face successfully.<br>* Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.<br>* Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.<br>* 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.<br>* Different ''detectionModel'' values can be provided. To use and compare different detection models, please refer to [How to specify a detection model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).'
      operationId: microsoftAzureFacelistAddfacefromurl
      parameters:
      - $ref: '#/parameters/faceListId'
      - $ref: '#/parameters/faceUserData'
      - $ref: '#/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      - $ref: '#/parameters/detectionModel'
      produces:
      - application/json
      consumes:
      - 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:
          $ref: ./examples/AddFaceListFaceFromUrl.json
      summary: Microsoft Azure Post Facelists Facelistid Persistedfaces
      tags:
      - Facelists
definitions:
  NameAndUserDataContractForCreation:
    type: object
    description: A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.
    required:
    - name
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
  RecognitionModel:
    type: string
    description: Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.
    default: recognition_01
    x-nullable: false
    x-ms-enum:
      name: RecognitionModel
      modelAsString: true
    enum:
    - recognition_01
    - recognition_02
    - recognition_03
    - recognition_04
  NameAndUserDataContract:
    type: object
    description: A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
  MetaDataContract:
    type: object
    description: A combination of user defined name and user specified data and recognition model name for largePersonGroup/personGroup, and largeFaceList/faceList.
    properties:
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
    allOf:
    - $ref: '#/definitions/NameAndUserDataContractForCreation'
  PersistedFace:
    type: object
    required:
    - persistedFaceId
    description: PersonFace object.
    properties:
      persistedFaceId:
        type: string
        format: uuid
        description: The persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in at the time specified by faceIdTimeToLive after the detection call.
      userData:
        type: string
        description: User-provided data attached to the face. The size limit is 1KB.
        maxLength: 1024
  APIError:
    type: object
    description: Error information returned by the API
    properties:
      error:
        $ref: '#/definitions/Error'
  PersistedFaces:
    type: array
    description: An array of persisted faces within the face list or large face list.
    items:
      $ref: '#/definitions/PersistedFace'
  FaceLists:
    type: array
    description: An array of face list results, with fields of faceListId, name and userData
    items:
      $ref: '#/definitions/FaceList'
  FaceList:
    description: Face list object.
    type: object
    required:
    - faceListId
    - name
    properties:
      faceListId:
        type: string
        description: FaceListId of the target face list.
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
      name:
        type: string
        description: User defined name, maximum length is 128.
        maxLength: 128
        minLength: 1
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
        maxLength: 16384
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
      persistedFaces:
        description: Persisted faces within the face list.
        $ref: '#/definitions/PersistedFaces'
  Error:
    type: object
    description: Error body.
    properties:
      code:
        type: string
      message:
        type: string
parameters:
  persistedFaceId:
    name: persistedFaceId
    in: path
    description: Id referencing a particular persistedFaceId of an existing face.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
    collectionFormat: csv
  returnRecognitionModel:
    name: returnRecognitionModel
    description: A value indicating whether the operation should return 'recognitionModel' in response.
    default: false
    required: false
    type: boolean
    in: query
    x-ms-parameter-location: method
  detectionModel:
    name: detectionModel
    description: Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
    default: detection_01
    required: false
    type: string
    in: query
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: DetectionModel
      modelAsString: true
    enum:
    - detection_01
    - detection_02
    - detection_03
  faceUserData:
    name: userData
    in: query
    description: User-specified data about the face for any purpose. The maximum length is 1KB.
    type: string
    maxLength: 1024
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
  targetFace:
    name: targetFace
    in: query
    description: A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image.
    type: array
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
    items:
      type: integer
      format: int32
      x-nullable: false
      maxItems: 4
      minItems: 4
  faceListId:
    name: faceListId
    in: path
    description: Id referencing a particular face list.
    required: true
    type: string
    x-ms-parameter-location: method
    collectionFormat: csv
    maxLength: 64
    pattern: ^[a-z0-9-_]+$
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'