match.yml

openapi: 3.0.4

paths:
  /match:
    parameters:
      - $ref: "./common.yml#/components/parameters/x-request"
    post:
      tags:
        - match
      summary: "compare faces (1:1)"
      description: "To perform a comparison of faces in the same image or in two different images, use POST `/api/match`. It's possible to compare faces in the same image or in two different images, this is defined by the `images.type` parameter. <br><br> The face detection result is displayed in the `detections` field.

Each face is identified by two parameters: `faceIndex` (the index number of the face) and `imageIndex` (the index number of the image on which the face is detected).

So, if there are two images each of which has two faces in them, the parameters will be the following:

- First face in the first image: `faceIndex: 0`, `imageIndex: 0`

- Second face in the first image: `faceIndex: 1`, `imageIndex: 0`

- First face of the second image: `faceIndex: 0`, `imageIndex: 1`

- Second face in the second image: `faceIndex: 1`, `imageIndex: 1`"
      operationId: match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MatchRequest"
      responses:
        200:
          description: "Successful operation; the compare results are returned."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchResponse"
        403:
          $ref: "./common.yml#/components/responses/BadLicense"

components:
  schemas:
    MatchRequest:
      title: "MatchRequest"
      allOf:
        - $ref: "./common.yml#/components/schemas/TransactionLabels"
        - $ref: "#/components/schemas/MatchRequestData"

    MatchRequestData:
      title: "MatchRequestData"
      type: object
      required:
        - images
      properties:
        tag:
          type: string
          description: "Session identificator, should be unique for each session."
        images:
          type: array
          description: "An array of images to be processed. At least two images must be provided."
          items:
            $ref: "#/components/schemas/MatchImage"
        outputImageParams:
          $ref: "./common.yml#/components/schemas/ProcessParam/properties/outputImageParams"

    MatchImageIndex:
      title: "MatchImageIndex"
      type: integer
      description: "The image index number. Can be given; if not given, the index numbers are set automatically starting from `0`. All index numbers must be whole and unique—not repeated."

    MatchFaceIndex:
      title: "MatchFaceIndex"
      type: number
      description: "The detected face index number."

    MatchImage:
      title: "MatchImage"
      type: object
      required:
        - data
      properties:
        index:
          $ref: "#/components/schemas/MatchImageIndex"
        type:
          $ref: "./common.yml#/components/schemas/ImageSource"
        data:
          $ref: "./common.yml#/components/schemas/ImageData"
        detectAll:
          $ref: "#/components/schemas/detectAll"

    MatchResponse:
      title: "MatchResponse"
      allOf:
        - $ref: "./common.yml#/components/schemas/FaceSDKResult"
        - $ref: "#/components/schemas/MatchResponseData"

    MatchResponseData:
      title: "MatchResponseData"
      type: object
      properties:
        detections:
          type: array
          description: "The detection results."
          items:
            $ref: "#/components/schemas/MatchImageDetection"
        results:
          type: array
          description: "The comparison results."
          items:
            $ref: "#/components/schemas/MatchImageResult"
        metadata:
          type: object
          additionalProperties: true
          description: "A free-form object containing person's extended attributes."

    MatchImageResult:
      title: "MatchImageResult"
      type: object
      required:
        - firstIndex
        - secondIndex
      properties:
        firstIndex:
          $ref: "#/components/schemas/MatchImageIndex"
        firstFaceIndex:
          $ref: "#/components/schemas/MatchFaceIndex"
        first:
          $ref: "./common.yml#/components/schemas/ImageSource"
        secondIndex:
          $ref: "#/components/schemas/MatchImageIndex"
        secondFaceIndex:
          $ref: "#/components/schemas/MatchFaceIndex"
        second:
          $ref: "./common.yml#/components/schemas/ImageSource"
        score:
          type: number
          description: "A dimensionless number that shows how similar the compared faces are. 0—absolutely identical faces."
        similarity:
          type: number
          description: "The detected faces similarity, %. 100%—absolutely identical faces, 0%—absolutely not identical."

    MatchImageDetection:
      title: "MatchImageDetection"
      type: object
      required:
        - imageIndex
        - status
      properties:
        faces:
          type: array
          description: "Detected faces."
          items:
            $ref: "#/components/schemas/DetectionFace"
        imageIndex:
          $ref: "#/components/schemas/MatchImageIndex"
        status:
          $ref: "./common.yml#/components/schemas/FaceSDKResultCode"

    DetectionFace:
      title: "DetectionFace"
      type: object
      properties:
        faceIndex:
          $ref: "#/components/schemas/MatchFaceIndex"
        landmarks:
          description: "Absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips."
          type: array
          items:
            description: "Cartesian points. First element - X-axis coordinate. Second element - Y-axis coordinate."
            type: array
            items:
              type: number
              example: [ x, y ]
          example: [ [ x, y ] ]
        rotationAngle:
          description: "Angle of rotation of the face from the vertical axis, degrees."
          type: number
        roi:
          $ref: "./common.yml#/components/schemas/FaceRectangular"
        crop:
          type: string
          format: byte
          description: "Base64-encoded aligned and cropped portrait."

    detectAll:
      title: "detectAll"
      type: boolean
      description: "Whether to detect all faces in the image. If set to `false`, only the most central face is detected."
      default: false