Microsoft Azure Facelists API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Facelists API
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: '#/components/parameters/faceListId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Create new face list example:
          $ref: ./examples/CreateNewFaceList.json
      summary: Microsoft Azure Put Facelists Facelistid
      tags:
      - Facelists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaDataContract'
        description: Request body for creating a face list.
        required: true
    get:
      description: Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.<br>
      operationId: microsoftAzureFacelistGet
      parameters:
      - $ref: '#/components/parameters/faceListId'
      - $ref: '#/components/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns the face list's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceList'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/faceListId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Update face list example:
          $ref: ./examples/UpdateFaceList.json
      summary: Microsoft Azure Patch Facelists Facelistid
      tags:
      - Facelists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameAndUserDataContract'
        description: Request body for updating a face list.
        required: true
    delete:
      description: Delete a specified face list.
      operationId: microsoftAzureFacelistDelete
      parameters:
      - $ref: '#/components/parameters/faceListId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns an array of faceList.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceLists'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      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: '#/components/parameters/faceListId'
      - $ref: '#/components/parameters/persistedFaceId'
      responses:
        '200':
          description: A successful call returns an empty response body.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/faceListId'
      - $ref: '#/components/parameters/faceUserData'
      - $ref: '#/components/parameters/targetFace'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      - $ref: '#/components/parameters/detectionModel'
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Create face list face example:
          $ref: ./examples/AddFaceListFaceFromUrl.json
      summary: Microsoft Azure Post Facelists Facelistid Persistedfaces
      tags:
      - Facelists
components:
  schemas:
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    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
    Error:
      type: object
      description: Error body.
      properties:
        code:
          type: string
        message:
          type: string
    PersistedFaces:
      type: array
      description: An array of persisted faces within the face list or large face list.
      items:
        $ref: '#/components/schemas/PersistedFace'
    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
    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: '#/components/schemas/RecognitionModel'
        persistedFaces:
          description: Persisted faces within the face list.
          $ref: '#/components/schemas/PersistedFaces'
    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-ms-enum:
        name: RecognitionModel
        modelAsString: true
      enum:
      - recognition_01
      - recognition_02
      - recognition_03
      - recognition_04
    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: '#/components/schemas/RecognitionModel'
      allOf:
      - $ref: '#/components/schemas/NameAndUserDataContractForCreation'
    FaceLists:
      type: array
      description: An array of face list results, with fields of faceListId, name and userData
      items:
        $ref: '#/components/schemas/FaceList'
    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
  parameters:
    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.
      x-ms-parameter-location: method
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
          format: int32
          maxItems: 4
          minItems: 4
    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.
      required: false
      in: query
      x-ms-parameter-location: method
      x-ms-enum:
        name: DetectionModel
        modelAsString: true
      schema:
        type: string
        enum:
        - detection_01
        - detection_02
        - detection_03
        default: detection_01
    returnRecognitionModel:
      name: returnRecognitionModel
      description: A value indicating whether the operation should return 'recognitionModel' in response.
      required: false
      in: query
      x-ms-parameter-location: method
      schema:
        type: boolean
        default: false
    faceListId:
      name: faceListId
      in: path
      description: Id referencing a particular face list.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
    persistedFaceId:
      name: persistedFaceId
      in: path
      description: Id referencing a particular persistedFaceId of an existing face.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    faceUserData:
      name: userData
      in: query
      description: User-specified data about the face for any purpose. The maximum length is 1KB.
      x-ms-parameter-location: method
      required: false
      style: form
      explode: false
      schema:
        type: string
        maxLength: 1024
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'