Microsoft Azure Largefacelists API

openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Largefacelists API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
tags:
- name: Largefacelists
paths:
  /largefacelists/{largeFaceListId}:
    put:
      description: 'Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel.

        Large face list is a list of faces, up to 1,000,000 faces, and used by Face - Find Similar.

        After creation, user should use LargeFaceList Face - Add to import the faces and LargeFaceList - Train to make it ready for Face - Find Similar. No image will be stored. Only the extracted face features are stored on server until LargeFaceList - Delete is called.

        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 / LargePersonGroup and Face - Identify.

        ''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. Please refer to Specify a recognition model.


        Large face list quota:

        * Free-tier subscription quota: 64 large face lists.

        * S0-tier subscription quota: 1,000,000 large face lists.'
      operationId: microsoftAzureLargefacelistCreate
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      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 large face list example:
          $ref: ./examples/CreateNewLargeFaceList.json
      summary: Microsoft Azure Put Largefacelists Largefacelistid
      tags:
      - Largefacelists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaDataContract'
        description: Request body for creating a large face list.
        required: true
    get:
      description: Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
      operationId: microsoftAzureLargefacelistGet
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - $ref: '#/components/parameters/returnRecognitionModel'
      responses:
        '200':
          description: A successful call returns the large face list's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LargeFaceList'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get large face list example:
          $ref: ./examples/GetLargeFaceList.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid
      tags:
      - Largefacelists
    patch:
      description: Update information of a large face list.
      operationId: microsoftAzureLargefacelistUpdate
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      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 large face list example:
          $ref: ./examples/UpdateLargeFaceList.json
      summary: Microsoft Azure Patch Largefacelists Largefacelistid
      tags:
      - Largefacelists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameAndUserDataContract'
        description: Request body for updating a large face list.
        required: true
    delete:
      description: Delete a specified large face list.
      operationId: microsoftAzureLargefacelistDelete
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      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 large face list example:
          $ref: ./examples/DeleteLargeFaceList.json
      summary: Microsoft Azure Delete Largefacelists Largefacelistid
      tags:
      - Largefacelists
  /largefacelists/{largeFaceListId}/training:
    get:
      description: Retrieve the training status of a large face list (completed or ongoing).
      operationId: microsoftAzureLargefacelistGettrainingstatus
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      responses:
        '200':
          description: A successful call returns the large face list's training status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingStatus'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get large face list's training status example:
          $ref: ./examples/GetLargeFaceListTrainingStatus.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Training
      tags:
      - Largefacelists
  /largefacelists:
    get:
      description: 'List large face lists’ information of largeFaceListId, name, userData and recognitionModel.

        To get face information inside largeFaceList use LargeFaceList Face - Get

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


        For example, total 5 large person lists: "list1", ..., "list5".

        "start=&top=" will return all 5 lists.

        "start=&top=2" will return "list1", "list2".

        "start=list2&top=3" will return "list3", "list4", "list5".'
      operationId: microsoftAzureLargefacelistList
      parameters:
      - $ref: '#/components/parameters/returnRecognitionModel'
      - name: start
        description: Starting large face list id to return (used to list a range of large face lists).
        in: query
        required: false
        schema:
          type: string
      - name: top
        description: Number of large face lists to return starting with the large face list id indicated by the 'start' parameter.
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      responses:
        '200':
          description: A successful call returns an array of largeFaceList.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LargeFaceLists'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        List large face lists example:
          $ref: ./examples/ListLargeFaceLists.json
      summary: Microsoft Azure Get Largefacelists
      tags:
      - Largefacelists
  /largefacelists/{largeFaceListId}/train:
    post:
      description: Queue a large face list training task, the training task may not be started immediately.
      operationId: microsoftAzureLargefacelistTrain
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      responses:
        '202':
          description: The training task was queued successfully.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Queue large face list training:
          $ref: ./examples/QueueLargeFaceListTraining.json
      summary: Microsoft Azure Post Largefacelists Largefacelistid Train
      tags:
      - Largefacelists
  /largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}:
    delete:
      description: 'Delete a face from a large face list by specified largeFaceListId and persistedFaceId.

        Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel.'
      operationId: microsoftAzureLargefacelistDeleteface
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - $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 large face list example:
          $ref: ./examples/DeleteLargeFaceListFace.json
      summary: Microsoft Azure Delete Largefacelists Largefacelistid Persistedfaces…
      tags:
      - Largefacelists
    get:
      description: Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).
      operationId: microsoftAzureLargefacelistGetface
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - $ref: '#/components/parameters/persistedFaceId'
      responses:
        '200':
          description: A successful call returns target persisted face's information (persistedFaceId and userData).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFace'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        Get persisted face example:
          $ref: ./examples/GetLargeFaceListPersistedFace.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Persistedfaces…
      tags:
      - Largefacelists
    patch:
      description: Update a persisted face's userData field.
      operationId: microsoftAzureLargefacelistUpdateface
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - $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:
        Update face example:
          $ref: ./examples/UpdateLargeFaceListFace.json
      summary: Microsoft Azure Patch Largefacelists Largefacelistid Persistedfaces…
      tags:
      - Largefacelists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFaceRequest'
        description: Request body for updating persisted face.
        required: true
  /largefacelists/{largeFaceListId}/persistedfaces:
    post:
      description: 'Add a face to a specified large face list, up to 1,000,000 faces.

        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 or LargeFaceList - Delete is called.

        Note persistedFaceId is different from faceId generated by Face - Detect.

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


        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: microsoftAzureLargefacelistAddfacefromurl
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - $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 large face list face example:
          $ref: ./examples/AddLargeFaceListFaceFromUrl.json
      summary: Microsoft Azure Post Largefacelists Largefacelistid Persistedfaces
      tags:
      - Largefacelists
    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: microsoftAzureLargefacelistListfaces
      parameters:
      - $ref: '#/components/parameters/largeFaceListId'
      - name: start
        description: Starting face id to return (used to list a range of faces).
        in: query
        required: false
        schema:
          type: string
      - name: top
        description: Number of faces to return starting with the face id indicated by the 'start' parameter.
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      responses:
        '200':
          description: A successful call returns an array of face information that belong to the large face list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFaces'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-ms-examples:
        List faces in large face list:
          $ref: ./examples/ListLargeFaceListFaces.json
      summary: Microsoft Azure Get Largefacelists Largefacelistid Persistedfaces
      tags:
      - Largefacelists
components:
  schemas:
    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
    PersistedFaces:
      type: array
      description: An array of persisted faces within the face list or large face list.
      items:
        $ref: '#/components/schemas/PersistedFace'
    LargeFaceList:
      description: Large face list object.
      type: object
      required:
      - largeFaceListId
      - name
      properties:
        largeFaceListId:
          type: string
          description: LargeFaceListId of the target large 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'
    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
    Error:
      type: object
      description: Error body.
      properties:
        code:
          type: string
        message:
          type: string
    LargeFaceLists:
      type: array
      description: An array of large face list results, with fields of largeFaceListId, name and userData
      items:
        $ref: '#/components/schemas/LargeFaceList'
    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
    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
    APIError:
      type: object
      description: Error information returned by the API
      properties:
        error:
          $ref: '#/components/schemas/Error'
    TrainingStatus:
      type: object
      required:
      - status
      - createdDateTime
      description: Training status object.
      properties:
        status:
          type: string
          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.'
          x-ms-enum:
            name: TrainingStatusType
            modelAsString: false
          enum:
          - nonstarted
          - running
          - succeeded
          - failed
        createdDateTime:
          type: string
          format: date-time
          description: A combined UTC date and time string that describes the created time of the person group, large person group or large face list.
          x-ms-client-name: created
        lastActionDateTime:
          type: string
          format: date-time
          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.
          x-ms-client-name: lastAction
        lastSuccessfulTrainingDateTime:
          type: string
          format: date-time
          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.
          x-ms-client-name: lastSuccessfulTraining
        message:
          type: string
          description: Show failure message when training failed (omitted when training succeed).
    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'
    UpdateFaceRequest:
      type: object
      description: Request to update face data.
      properties:
        userData:
          type: string
          description: User-provided data attached to the face. The size limit is 1KB.
          maxLength: 1024
  parameters:
    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
    largeFaceListId:
      name: largeFaceListId
      in: path
      description: Id referencing a particular large face list.
      required: true
      x-ms-parameter-location: method
      style: simple
      explode: false
      schema:
        type: string
        maxLength: 64
        pattern: ^[a-z0-9-_]+$
    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
    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
    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
  securitySchemes:
    apim_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/face/v1.0-preview'
  useSchemePrefix: false
  parameters:


# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/microsoft-azure-largefacelists-api-openapi.yml