Microsoft Azure AI Foundry Findsimilars API

openapi: 3.2.0
info:
  title: Azure AI Face Findsimilars API
  version: v1.2
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- KeyAuth: []
- AADToken:
  - https://cognitiveservices.azure.com/.default
tags:
- name: Findsimilars
paths:
  /findsimilars:
    post:
      operationId: FaceRecognitionOperations_FindSimilar
      summary: Given query face's faceId, to search the similar-looking faces from a faceId…
      description: 'Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity.


        Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person''s other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces.


        The ''recognitionModel'' associated with the query faceId should be the same as the ''recognitionModel'' used by the target faceId array.'
      responses:
        '200':
          description: A successful call returns an array of the most similar faces represented in faceId if the input parameter is faceIds or persistedFaceId if the input parameter is faceListId or largeFaceListId.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FindSimilarResult'
        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:
                faceId:
                  $ref: '#/components/schemas/Azure.Core.uuid'
                  description: faceId of the query face. User needs to call "Detect" first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call.
                maxNumOfCandidatesReturned:
                  type: integer
                  format: int32
                  description: The number of top similar faces returned. The valid range is [1, 1000]. Default value is 20.
                  default: 20
                  minimum: 1
                  maximum: 1000
                mode:
                  type: string
                  description: Similar face searching mode. It can be 'matchPerson' or 'matchFace'. Default value is 'matchPerson'.
                  default: matchPerson
                  enum:
                  - matchPerson
                  - matchFace
                  x-ms-enum:
                    name: FindSimilarMatchMode
                    modelAsString: true
                    values:
                    - name: matchPerson
                      value: matchPerson
                      description: Match person.
                    - name: matchFace
                      value: matchFace
                      description: Match face.
                faceIds:
                  type: array
                  description: An array of candidate faceIds. All of them are created by "Detect" and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000.
                  items:
                    $ref: '#/components/schemas/Azure.Core.uuid'
              required:
              - faceId
              - faceIds
        required: true
      tags:
      - Findsimilars
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
    FindSimilarResult:
      type: object
      description: Response body for find similar face operation.
      properties:
        confidence:
          type: number
          format: float
          description: Confidence value of the candidate. The higher confidence, the more similar. Range between [0,1].
          minimum: 0
          maximum: 1
        faceId:
          $ref: '#/components/schemas/Azure.Core.uuid'
          description: faceId of candidate face when find by faceIds. faceId is created by "Detect" and will expire 24 hours after the detection call.
        persistedFaceId:
          $ref: '#/components/schemas/Azure.Core.uuid'
          description: persistedFaceId of candidate face when find by faceListId or largeFaceListId. persistedFaceId in face list/large face list is persisted and will not expire.
      required:
      - confidence
    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 (63 KB total) ---
# Full source: https://artifacts.apis.io/azure-ai-foundry/openapi/azure-ai-foundry-findsimilars-api-openapi.yml