Microsoft Azure AI Foundry Group API

openapi: 3.2.0
info:
  title: Azure AI Face Group API
  version: v1.2
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- KeyAuth: []
- AADToken:
  - https://cognitiveservices.azure.com/.default
tags:
- name: Group
paths:
  /group:
    post:
      operationId: FaceRecognitionOperations_Group
      summary: Divide candidate faces into groups based on face similarity
      description: '>

        *

        * 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 "Verify Face To Face" when you only have 2 candidate faces.

        * The ''recognitionModel'' associated with the query faces'' faceIds should be the same.'
      responses:
        '200':
          description: A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupingResult'
        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:
              type: object
              properties:
                faceIds:
                  type: array
                  description: Array of candidate faceIds created by "Detect". The maximum is 1000 faces.
                  items:
                    $ref: '#/components/schemas/Azure.Core.uuid'
              required:
              - faceIds
        required: true
      tags:
      - Group
components:
  schemas:
    Azure.Core.uuid:
      type: string
      format: uuid
      description: Universally Unique Identifier
    FaceErrorResponse:
      type: object
      description: A response containing error details.
      properties:
        error:
          $ref: '#/components/schemas/FaceError'
          description: The error object.
      required:
      - error
    GroupingResult:
      type: object
      description: Response body for group face operation.
      properties:
        groups:
          type: array
          description: A partition of the original faces based on face similarity. Groups are ranked by number of faces.
          items:
            type: array
            items:
              $ref: '#/components/schemas/Azure.Core.uuid'
        messyGroup:
          type: array
          description: Face ids array of faces that cannot find any similar faces from original faces.
          items:
            $ref: '#/components/schemas/Azure.Core.uuid'
      required:
      - groups
      - messyGroup
    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
  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 (61 KB total) ---
# Full source: https://artifacts.apis.io/azure-ai-foundry/openapi/azure-ai-foundry-group-api-openapi.yml