Microsoft Azure AI Foundry Facelists API

openapi: 3.2.0
info:
  title: Azure AI Face Facelists API
  version: v1.2
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- KeyAuth: []
- AADToken:
  - https://cognitiveservices.azure.com/.default
tags:
- name: Facelists
paths:
  /facelists:
    get:
      operationId: FaceListOperations_GetFaceLists
      description: 'List Face Lists'' faceListId, name, userData and recognitionModel.


        To get face information inside Face List use "Get Face List".'
      parameters:
      - name: returnRecognitionModel
        in: query
        description: Return 'recognitionModel' or not. The default value is false.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A successful call returns an array of Face Lists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FaceListItem'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      tags:
      - Facelists
      summary: Face list operations get face lists
      x-summary-source: derived
  /facelists/{faceListId}:
    get:
      operationId: FaceListOperations_GetFaceList
      description: Retrieve a Face List's faceListId, name, userData, recognitionModel and faces in the Face List.
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      - name: returnRecognitionModel
        in: query
        description: Return 'recognitionModel' or not. The default value is false.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A successful call returns the Face List's information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceList'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      tags:
      - Facelists
      summary: Face list operations get face list
      x-summary-source: derived
    put:
      operationId: FaceListOperations_CreateFaceList
      summary: Create an empty Face List with user-specified faceListId, name, an optional…
      description: 'Up to 64 Face Lists are allowed in one subscription.


        Face List is a list of faces, up to 1,000 faces, and used by "Find Similar From Face List".


        After creation, user should use "Add Face List Face" to import the faces. No image will be stored. Only the extracted face feature(s) will be stored on server until "Delete Face List" 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 Person Group / Large Person Group and "Identify".


        Please consider Large Face List when the face number is large. It can support up to 1,000,000 faces.'
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      responses:
        '200':
          description: The request has succeeded.
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
        required: true
      tags:
      - Facelists
    patch:
      operationId: FaceListOperations_UpdateFaceList
      description: Update information of a Face List, including name and userData.
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      responses:
        '200':
          description: The request has succeeded.
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDefinedFieldsForUpdate'
        required: true
      tags:
      - Facelists
      summary: Face list operations update face list
      x-summary-source: derived
    delete:
      operationId: FaceListOperations_DeleteFaceList
      description: Delete a specified Face List.
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      responses:
        '200':
          description: The request has succeeded.
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      tags:
      - Facelists
      summary: Face list operations delete face list
      x-summary-source: derived
  /facelists/{faceListId}/persistedfaces:
    post:
      operationId: FaceListOperations_AddFaceListFaceFromUrl
      summary: Add a face to a specified Face List, up to 1,000 faces
      description: 'To deal with an image containing 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(s) will be stored on server until "Delete Face List Face" or "Delete Face List" is called.


        Note that persistedFaceId is different from faceId generated by "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 "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.

        * 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 here.'
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      - $ref: '#/components/parameters/AddFaceOptions.targetFace'
      - $ref: '#/components/parameters/AddFaceOptions.detectionModel'
      - $ref: '#/components/parameters/AddFaceOptions.userData'
      responses:
        '200':
          description: A successful call returns a new persistedFaceId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddFaceResult'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddFaceFromUrlRequest'
        required: true
      tags:
      - Facelists
  /facelists/{faceListId}/persistedfaces/{persistedFaceId}:
    delete:
      operationId: FaceListOperations_DeleteFaceListFace
      summary: Delete a face from a Face List by specified faceListId and persistedFaceId
      description: Adding/deleting faces to/from a same Face List are processed sequentially and to/from different Face Lists are in parallel.
      parameters:
      - name: faceListId
        in: path
        description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
        required: true
        schema:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9-_]+$
      - name: persistedFaceId
        in: path
        description: Face ID of the face.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The request has succeeded.
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceErrorResponse'
      tags:
      - Facelists
components:
  schemas:
    RecognitionModel:
      type: string
      description: The recognition model for the face.
      enum:
      - recognition_01
      - recognition_02
      - recognition_03
      - recognition_04
      x-ms-enum:
        name: RecognitionModel
        modelAsString: true
        values:
        - name: recognition_01
          value: recognition_01
          description: The default recognition model for "Detect". All those faceIds created before 2019 March are bonded with this recognition model.
        - name: recognition_02
          value: recognition_02
          description: Recognition model released in 2019 March.
        - name: recognition_03
          value: recognition_03
          description: Recognition model released in 2020 May.
        - name: recognition_04
          value: recognition_04
          description: Recognition model released in 2021 February. It's recommended to use this recognition model for better recognition accuracy.
    FaceError:
      type: object
      description: 'The error object. For comprehensive details on error codes and messages returned by the Face Service, please refer to the following link: https://aka.ms/face-error-codes-and-messages.'
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        message:
          type: string
          description: A human-readable representation of the error.
      required:
      - code
      - message
    AddFaceResult:
      type: object
      description: Response body for adding face.
      properties:
        persistedFaceId:
          $ref: '#/components/schemas/Azure.Core.uuid'
          description: Persisted Face ID of the added face, which is persisted and will not expire. Different from faceId which is created in "Detect" and will expire in 24 hours after the detection call.
      required:
      - persistedFaceId
    CreateCollectionRequest:
      type: object
      description: Model for creating face collection.
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
          minLength: 1
          maxLength: 128
        userData:
          type: string
          description: Optional user defined data. Length should not exceed 16K.
          maxLength: 16384
        recognitionModel:
          type: string
          description: The 'recognitionModel' associated with this face list. Supported 'recognitionModel' values include 'recognition_01', 'recognition_02, 'recognition_03', and 'recognition_04'. The default value is 'recognition_01'. 'recognition_04' is recommended since its accuracy is improved on faces wearing masks compared with 'recognition_03', and its overall accuracy is improved compared with 'recognition_01' and 'recognition_02'.
          default: recognition_01
          enum:
          - recognition_01
          - recognition_02
          - recognition_03
          - recognition_04
          x-ms-enum:
            name: RecognitionModel
            modelAsString: true
            values:
            - name: recognition_01
              value: recognition_01
              description: The default recognition model for "Detect". All those faceIds created before 2019 March are bonded with this recognition model.
            - name: recognition_02
              value: recognition_02
              description: Recognition model released in 2019 March.
            - name: recognition_03
              value: recognition_03
              description: Recognition model released in 2020 May.
            - name: recognition_04
              value: recognition_04
              description: Recognition model released in 2021 February. It's recommended to use this recognition model for better recognition accuracy.
      required:
      - name
    FaceList:
      type: object
      description: Face list is a list of faces, up to 1,000 faces.
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
          minLength: 1
          maxLength: 128
        userData:
          type: string
          description: Optional user defined data. Length should not exceed 16K.
          maxLength: 16384
        recognitionModel:
          $ref: '#/components/schemas/RecognitionModel'
          description: Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds.
        faceListId:
          $ref: '#/components/schemas/collectionId'
          description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
          readOnly: true
        persistedFaces:
          type: array
          description: Face ids of registered faces in the face list.
          items:
            $ref: '#/components/schemas/FaceListFace'
      required:
      - name
      - faceListId
    Azure.Core.uuid:
      type: string
      format: uuid
      description: Universally Unique Identifier
    FaceListItem:
      type: object
      description: Face list item for list face list.
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
          minLength: 1
          maxLength: 128
        userData:
          type: string
          description: Optional user defined data. Length should not exceed 16K.
          maxLength: 16384
        recognitionModel:
          $ref: '#/components/schemas/RecognitionModel'
          description: Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds.
        faceListId:
          $ref: '#/components/schemas/collectionId'
          description: Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.
      required:
      - name
      - faceListId
    FaceListFace:
      type: object
      description: Face resource for face list.
      properties:
        persistedFaceId:
          $ref: '#/components/schemas/Azure.Core.uuid'
          description: Face ID of the face.
          readOnly: true
        userData:
          type: string
          description: User-provided data attached to the face. The length limit is 1K.
          maxLength: 1024
      required:
      - persistedFaceId
    AddFaceFromUrlRequest:
      type: object
      description: Add face from url request.
      properties:
        url:
          type: string
          format: uri
          description: URL of input image.
      required:
      - url
    FaceErrorResponse:
      type: object
      description: A response containing error details.
      properties:
        error:
          $ref: '#/components/schemas/FaceError'
          description: The error object.
      required:
      - error
    collectionId:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[a-z0-9-_]+$
    UserDefinedFieldsForUpdate:
      type: object
      description: User defined fields for object update.
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
          minLength: 1
          maxLength: 128
        userData:
          type: string
          description: Optional user defined data. Length should not exceed 16K.
          maxLength: 16384
  parameters:
    AddFaceOptions.userData:
      name: userData
      in: query
      description: User-provided data attached to the face. The size limit is 1K.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 1024
    AddFaceOptions.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'.
      required: false
      x-ms-parameter-location: method
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
          format: int32
        maxItems: 4
        minItems: 4
    AddFaceOptions.detectionModel:
      name: detectionModel
      in: query
      description: The 'detectionModel' associated with the detected faceIds. Supported 'detectionModel' values include 'detection_01', 'detection_02' and 'detection_03'. The default value is 'detection_01'.
      required: false
      x-ms-enum:
        name: DetectionModel
        modelAsString: true
        values:
        - name: detection_01
          value: detection_01
          description: The default detection model. 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.
        - name: detection_02
          value: detection_02
          description: Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces.
        - name: detection_03
          value: detection_03
          description: Detection model released in 2021 February with improved accuracy especially on small faces.
      x-ms-parameter-location: method
      schema:
        type: string
        enum:
        - detection_01
        - detection_02
        - detection_03
        default: detection_01
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            https://cognitiveservices.azure.com/.default: ''
          authorizationUrl: https://api.example.com/oauth2/authorize
          tokenUrl: https://api.example.com/oauth2/token
      description: The Azure Active Directory OAuth2 Flow
    KeyAuth:
      type: apiKey
      description: The secret key for your Azure AI Face subscription.
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/face/{apiVersion}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: 'Supported Cognitive Services endpoints (protocol and hostname, for example:

      https://{resource-name}.cognitiveservices.azure.com).'
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true


# --- truncated at 32 KB (77 KB total) ---
# Full source: https://artifacts.apis.io/azure-ai-foundry/openapi/azure-ai-foundry-facelists-api-openapi.yml