detect.yml

openapi: 3.0.3
paths:
  /detect:
    parameters:
      - $ref: './common.yml#/components/parameters/x-request'
    post:
      tags:
        - match
      summary: "detect and check quality"
      description: "Use the POST `api/detect` endpoint to analyze images, recognize faces in them, and return cropped and aligned portraits of the detected people. 
      
      
      The Face Detection feature lets you:

      - **Check face image quality**: Assess whether a portrait meets certain standards, for example, ICAO, Schengen visa, USA visa. To perform image quality check, use the `processParam.quality` field.

      - **Evaluate face attributes**: Estimate the age range of a person; check whether the eyes are occluded, closed, or open; detect a facial expression or smile; see if there are glasses, sunglasses, head coverage, medical mask, etc. To evaluate attributes, add the `processParam.attributes` field.

      
      You can perform Face Detection in two ways:

      - By adding parameters manually. In this case, the configuration is not saved and can not be automatically repeated.
      
      - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones."      
      operationId: detect
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DetectRequest"
      responses:
        200:
          description: "Successful operation; the coordinates of the detected faces are returned."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DetectResponse"
        403:
          $ref: "./common.yml#/components/responses/BadLicense"

components:
  schemas:
    DetectRequest:
      type: object
      properties:
        tag:
          type: string
          description: "Session identificator, should be unique for each session."
        processParam:
          $ref: "./common.yml#/components/schemas/ProcessParam"
        image:
          $ref: "./common.yml#/components/schemas/ImageData"
        thumbnails:
          description: "Use `processParam.outputImageParams.crop` instead."
          deprecated: true
          type: boolean
          default: false

    DetectResponse:
      allOf:
        - $ref: './common.yml#/components/schemas/FaceSDKResult'
        - type: object
          properties:
            results:
              $ref: '#/components/schemas/DetectResult'

    DetectResult:
      type: object
      required:
        - detections
      properties:
        detections:
          type: array
          items:
            $ref: "#/components/schemas/Detection"
        detectorType:
          description: "Internal."
          type: integer
        landmarksType:
          description: "Internal."
          type: integer
        scenario:
          description: "Scenario from Request processParam."
          $ref: "./common.yml#/components/schemas/FaceQualityScenarios"
        timer:
          type: number
          format: float
          description: "The total time taken for the detection."
          example: 0.84793560000000001

    Detection:
      type: object
      required:
        - landmarks
        - roi
      properties:
        crop:
          description: "Base64 of the aligned and cropped portrait. Returned if align is set."
          $ref: "./common.yml#/components/schemas/ImageData"
        attributes:
          type: object
          properties:
            details:
              type: array
              items:
                type: object
                additionalProperties: true
            elapsedTime:
              type: number
              description: "The elapsed time for attribute detection."
        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: integer
              example: [ x, y ]
          example: [ [ x, y ] ]
        quality:
          type: object
          description: "Field for checking the portrait quality. If it is not mentioned, no quality check is performed."
          properties:
            nonCompliant:
              type: array
              description: "The array of all the non-compliant assessment characteristics."
              items:
                $ref: "./common.yml#/components/schemas/FaceQualityConfigName"
              example: ["ImageWidthToHeight", "Yaw"]
            detailsGroups:
              description: "The array of the assessment results for each group of characteristics."
              type: array
              items:
                $ref: "./common.yml#/components/schemas/QualityDetailsGroups"
            details:
              type: array
              description: "The array of the assessment characteristics that were set in the request."
              items:
                $ref: "./common.yml#/components/schemas/QualityDetail"

            score:
              type: number
              format: float
              description: "Returns the estimated portrait quality assessment result,
               a number from 0 to 1, where 1 is for absolute compliance."
              example: -1.0
            timer:
              type: number
              format: float
              description: "The total time the quality assessment has taken."
              example: 0.42036411166191101
        roi:
          $ref: "./common.yml#/components/schemas/FaceRectangular"
        thumbnail:
          $ref: "./common.yml#/components/schemas/Thumbnail"

    FaceAttribute:
      description: "Face attributes for evaluation."
      type: string
      enum:
        - Age
        - Emotion
        - EyeLeft
        - EyeRight
        - Smile
        - Glasses
        - HeadCovering
        - ForeheadCovering
        - Mouth
        - MedicalMask
        - Occlusion
        - StrongMakeup
        - Headphones
      x-enum-varnames:
        - AGE
        - EMOTION
        - EYE_LEFT
        - EYE_RIGHT
        - SMILE
        - GLASSES
        - HEAD_COVERING
        - FOREHEAD_COVERING
        - MOUTH
        - MEDICAL_MASK
        - OCCLUSION
        - STRONG_MAKEUP
        - HEADPHONES