detect.yml

openapi: 3.0.4

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 additionally:

      - **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. For the list of assessed characteristics, see the [Face Image Quality Characteristics page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/).

      - **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. For the list of assessed attributes, see the [Attributes List page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/).

      
      You can perform Face Detection in two ways:

      - By adding parameters manually. In this case, the configuration is not saved and you will need to add all the necessary parameters to each request.
      
      - By a processing `scenario` that includes certain parameters. You can use predefined scenarios or add custom ones. For detailed information about scenarios, refer to the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)."
      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:
      title: "DetectRequest"
      type: object
      allOf:
        - $ref: "./common.yml#/components/schemas/TransactionLabels"
        - $ref: "#/components/schemas/DetectRequestData"

    DetectRequestData:
      title: "DetectRequestData"
      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"

    DetectResponse:
      title: "DetectResponse"
      allOf:
        - $ref: "./common.yml#/components/schemas/FaceSDKResult"
        - $ref: "#/components/schemas/DetectResponseResults"

    DetectResponseResults:
      title: "DetectResponseResults"
      type: object
      properties:
          results:
            $ref: "#/components/schemas/DetectResult"

    DetectResult:
      title: "DetectResult"
      type: object
      description: "The detection results."
      required:
        - detections
      properties:
        detections:
          type: array
          description: "The array of performed checks."
          items:
            $ref: "#/components/schemas/Detection"
        detectorType:
          description: "Internal."
          type: integer
        landmarksType:
          description: "Internal."
          type: integer
        scenario:
          description: "The face detection scenario that was set in the `processParam.scenario` field of the request."
          type: string
        elapsedTime:
          type: number
          format: float
          description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response."
          example: 0.84793560000000001

    DetectAttributesDetails:
      title: "DetectAttributesDetails"
      allOf:
        - $ref: "#/components/schemas/DetailItem"
        - $ref: "#/components/schemas/AttributesData"

    AttributesData:
      title: "AttributesData"
      type: object
      properties:
        value:
          type: array
          description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)."
          items:
            type: integer

    DetectDetailsMeta:
      title: "DetectDetailsMeta"
      allOf:
        - $ref: "#/components/schemas/DetailItem"
        - $ref: "#/components/schemas/DetectMetaData"


    DetectMetaData:
      title: "DetectMetaData"
      type: object
      properties:
        confidence:
          type: number
          description: "The confidence in the estimated value, `1.0` is for 100% confidence."
          format: float
        value:
          type: string
          description: "The estimated value for the attribute, see the [Returned values column](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/)."

    Detection:
      title: "Detection"
      type: object
      required:
        - landmarks
        - roi
      properties:
        crop:
          $ref: "./common.yml#/components/schemas/ImageData"
        attributes:
          $ref: "#/components/schemas/DetectionAttributes"
        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:
          $ref: "#/components/schemas/DetectionQuality"
        roi:
          $ref: "./common.yml#/components/schemas/FaceRectangular"

    DetectionAttributes:
      title: "DetectionAttributes"
      type: object
      description: "The evaluated attributes, see the [Attributes List](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/attributes-detection/) for details."
      properties:
        details:
          type: array
          description: "Attributes assessment details. Returns `DetectDetailsMeta` or `DetectAttributesDetails`."
          items:
            oneOf:
              - $ref: "#/components/schemas/DetectAttributesDetails"
              - $ref: "#/components/schemas/DetectDetailsMeta"
        elapsedTime:
          type: number
          description: "Server processing time for attribute detection, ms."

    DetailItem:
      title: "DetailItem"
      type: object
      properties:
        name:
          description: "The name of the attribute."
          type: string
      discriminator:
        propertyName: name
        mapping:
          Age: "DetectAttributesDetails"
          EyeRight: "DetectDetailsMeta"
          EyeLeft: "DetectDetailsMeta"
          Emotion: "DetectDetailsMeta"
          Smile: "DetectDetailsMeta"
          Glasses: "DetectDetailsMeta"
          HeadCovering: "DetectDetailsMeta"
          ForeheadCovering: "DetectDetailsMeta"
          Mouth: "DetectDetailsMeta"
          MedicalMask: "DetectDetailsMeta"
          Occlusion: "DetectDetailsMeta"
          StrongMakeup: "DetectDetailsMeta"
          Headphones: "DetectDetailsMeta"

    DetectionQuality:
      title: "DetectionQuality"
      type: object
      description: "The portrait quality assessment results, see [Face Image Quality Characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/face-image-quality-check/). If not set in request, no quality check is performed."
      properties:
        nonCompliant:
          type: array
          description: "Non-compliant assessment characteristics."
          items:
            $ref: "./common.yml#/components/schemas/FaceQualityConfigName"
          example: [ "ImageWidthToHeight", "Yaw" ]
        detailsGroups:
          description: "Assessment results for each [group of characteristics](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-groups/)."
          type: array
          items:
            $ref: "./common.yml#/components/schemas/QualityDetailsGroups"
        details:
          type: array
          description: "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
        elapsedTime:
          type: number
          format: float
          description: "Server processing time for quality assessment, ms."
          example: 0.42036411166191101