Amazon Rekognition Facial Analysis API

openapi: 3.1.0
info:
  title: Amazon Rekognition Facial Analysis API
  version: '2016-06-27'
  description: Generated from AWS's published Smithy model for Amazon Rekognition. 2 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://rekognition.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /#CompareFaces:
    post:
      operationId: CompareFaces
      summary: Compare Faces
      description: Compares a face in the source input image with each of the 100 largest faces detected in the target input
        image. If the source image contains multiple faces, the service detects the largest face and compares it with each
        face detected in the target image. CompareFaces uses machine learning algorithms, which are probabilistic. A false
        negative is an incorrect prediction that a face in the target image has a low similarity confidence score when compared
        to the face in the source image. To reduce the probability of false negatives, we recommend that you compare the target
        image against multiple source images. If you plan to use CompareFaces to make a decision that impacts an individual's
        rights, privacy, or access to services, we recommend that you pass the result to a human for review and further validation
        before taking action. You pass the input and target images either as base64-encoded image bytes or as references to
        images in an Amazon S3 bucket. If you use the AWS CLI to call Amazon Rekognition operations, passing image bytes isn't
        supported. The image must be formatted as a PNG or JPEG file. In response, the operation returns an array of face
        matches ordered by similarity scor
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CompareFacesResponse'
              example:
                FaceMatches:
                - Face:
                    BoundingBox:
                      Width: 0.25
                      Top: 0.4933333396911621
                      Left: 0.31888890266418457
                      Height: 0.33481481671333313
                    Confidence: 99.9991226196289
                  Similarity: 100
                SourceImageFace:
                  BoundingBox:
                    Width: 0.25
                    Top: 0.4933333396911621
                    Left: 0.31888890266418457
                    Height: 0.33481481671333313
                  Confidence: 99.9991226196289
        '400':
          description: AccessDeniedException; ImageTooLargeException; InvalidImageFormatException; InvalidParameterException;
            InvalidS3ObjectException; ProvisionedThroughputExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.CompareFaces
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CompareFacesRequest'
            example:
              SourceImage:
                S3Object:
                  Bucket: mybucket
                  Name: mysourceimage
              TargetImage:
                S3Object:
                  Bucket: mybucket
                  Name: mytargetimage
              SimilarityThreshold: 90
      tags:
      - Facial Analysis
  /#DetectFaces:
    post:
      operationId: DetectFaces
      summary: Detect Faces
      description: Detects faces within an image that is provided as input. DetectFaces detects the 100 largest faces in the
        image. For each face detected, the operation returns face details. These details include a bounding box of the face,
        a confidence value (that the bounding box contains a face), and a fixed set of attributes such as facial landmarks
        (for example, coordinates of eye and mouth), pose, presence of facial occlusion, and so on. The face-detection algorithm
        is most effective on frontal faces. For non-frontal or obscured faces, the algorithm might not detect the faces or
        might detect faces with lower confidence. You pass the input image either as base64-encoded image bytes or as a reference
        to an image in an Amazon S3 bucket. If you use the AWS CLI to call Amazon Rekognition operations, passing image bytes
        is not supported. The image must be either a PNG or JPEG formatted file. This is a stateless API operation. That is,
        the operation does not persist any data. This operation requires permissions to perform the rekognition:DetectFaces
        action.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DetectFacesResponse'
              example:
                FaceDetails:
                - BoundingBox:
                    Width: 0.23999999463558197
                    Top: 0.33666667342185974
                    Left: 0.5555555820465088
                    Height: 0.18000000715255737
                  Landmarks:
                  - Y: 0.40819624066352844
                    X: 0.6394737362861633
                    Type: eyeLeft
                  - Y: 0.41039225459098816
                    X: 0.7266660928726196
                    Type: eyeRight
                  - Y: 0.44240960478782654
                    X: 0.6912462115287781
                    Type: eyeRight
                  - Y: 0.46700039505958557
                    X: 0.6306198239326477
                    Type: mouthDown
                  - Y: 0.47114261984825134
                    X: 0.7215608954429626
                    Type: mouthUp
                  Pose:
                    Yaw: 13.693790435791016
                    Roll: 0.9950747489929199
                    Pitch: 4.050806522369385
                  Quality:
                    Sharpness: 80
                    Brightness: 37.60169982910156
                  Confidence: 100
                OrientationCorrection: ROTATE_0
        '400':
          description: AccessDeniedException; ImageTooLargeException; InvalidImageFormatException; InvalidParameterException;
            InvalidS3ObjectException; ProvisionedThroughputExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.DetectFaces
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DetectFacesRequest'
            example:
              Image:
                S3Object:
                  Bucket: mybucket
                  Name: myphoto
      tags:
      - Facial Analysis
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: rekognition
  schemas:
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
        Logref:
          type: string
          description: A universally unique identifier (UUID) for the request.
    AgeRange:
      type: object
      properties:
        Low:
          type: integer
          description: The lowest estimated age.
        High:
          type: integer
          description: The highest estimated age.
    Beard:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face has beard or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    BoundingBox:
      type: object
      properties:
        Width:
          type: number
          description: Width of the bounding box as a ratio of the overall image width.
        Height:
          type: number
          description: Height of the bounding box as a ratio of the overall image height.
        Left:
          type: number
          description: Left coordinate of the bounding box as a ratio of overall image width.
        Top:
          type: number
          description: Top coordinate of the bounding box as a ratio of overall image height.
    CompareFacesMatch:
      type: object
      properties:
        Similarity:
          type: number
          description: Level of confidence that the faces match.
        Face:
          $ref: '#/components/schemas/ComparedFace'
    CompareFacesRequest:
      type: object
      properties:
        SourceImage:
          $ref: '#/components/schemas/Image'
        TargetImage:
          $ref: '#/components/schemas/Image'
        SimilarityThreshold:
          type: number
          description: The minimum level of confidence in the face matches that a match must meet to be included in the FaceMatches
            array.
        QualityFilter:
          type: string
          enum:
          - NONE
          - AUTO
          - LOW
          - MEDIUM
          - HIGH
          description: A filter that specifies a quality bar for how much filtering is done to identify faces. Filtered faces
            aren't compared. If you specify AUTO, Amazon Rekognition chooses the quality bar. If you specify LOW, MEDIUM,
            or HIGH, filtering removes all faces that don’t meet the chosen quality bar. The quality bar is based on a variety
            of common use cases. Low-quality detections can occur for a number of reasons. Some examples are an object that's
            misidentified as a face, a face that's too blurry, or a face with a pose that's too extreme to use. If you specify
            NONE, no filtering is performed. The defaul
      required:
      - SourceImage
      - TargetImage
    CompareFacesResponse:
      type: object
      properties:
        SourceImageFace:
          $ref: '#/components/schemas/ComparedSourceImageFace'
        FaceMatches:
          type: array
          items:
            $ref: '#/components/schemas/CompareFacesMatch'
          description: An array of faces in the target image that match the source image face. Each CompareFacesMatch object
            provides the bounding box, the confidence level that the bounding box contains a face, and the similarity score
            for the face in the bounding box and the face in the source image.
        UnmatchedFaces:
          type: array
          items:
            $ref: '#/components/schemas/ComparedFace'
          description: An array of faces in the target image that did not match the source image face.
        SourceImageOrientationCorrection:
          type: string
          enum:
          - ROTATE_0
          - ROTATE_90
          - ROTATE_180
          - ROTATE_270
          description: The value of SourceImageOrientationCorrection is always null. If the input image is in .jpeg format,
            it might contain exchangeable image file format (Exif) metadata that includes the image's orientation. Amazon
            Rekognition uses this orientation information to perform image correction. The bounding box coordinates are translated
            to represent object locations after the orientation information in the Exif metadata is used to correct the image
            orientation. Images in .png format don't contain Exif metadata. Amazon Rekognition doesn’t perform image correction
            for images in .png format and .jpeg imag
        TargetImageOrientationCorrection:
          type: string
          enum:
          - ROTATE_0
          - ROTATE_90
          - ROTATE_180
          - ROTATE_270
          description: The value of TargetImageOrientationCorrection is always null. If the input image is in .jpeg format,
            it might contain exchangeable image file format (Exif) metadata that includes the image's orientation. Amazon
            Rekognition uses this orientation information to perform image correction. The bounding box coordinates are translated
            to represent object locations after the orientation information in the Exif metadata is used to correct the image
            orientation. Images in .png format don't contain Exif metadata. Amazon Rekognition doesn’t perform image correction
            for images in .png format and .jpeg imag
    ComparedFace:
      type: object
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        Confidence:
          type: number
          description: Level of confidence that what the bounding box contains is a face.
        Landmarks:
          type: array
          items:
            $ref: '#/components/schemas/Landmark'
          description: An array of facial landmarks.
        Pose:
          $ref: '#/components/schemas/Pose'
        Quality:
          $ref: '#/components/schemas/ImageQuality'
        Emotions:
          type: array
          items:
            $ref: '#/components/schemas/Emotion'
          description: The emotions that appear to be expressed on the face, and the confidence level in the determination.
            Valid values include "Happy", "Sad", "Angry", "Confused", "Disgusted", "Surprised", "Calm", "Unknown", and "Fear".
        Smile:
          $ref: '#/components/schemas/Smile'
    ComparedSourceImageFace:
      type: object
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        Confidence:
          type: number
          description: Confidence level that the selected bounding box contains a face.
    DetectFacesRequest:
      type: object
      properties:
        Image:
          $ref: '#/components/schemas/Image'
        Attributes:
          type: array
          items:
            type: string
            enum:
            - DEFAULT
            - ALL
            - AGE_RANGE
            - BEARD
            - EMOTIONS
            - EYE_DIRECTION
            - EYEGLASSES
            - EYES_OPEN
            - GENDER
            - MOUTH_OPEN
            - MUSTACHE
            - FACE_OCCLUDED
            - SMILE
            - SUNGLASSES
          description: An array of facial attributes you want to be returned. A DEFAULT subset of facial attributes - BoundingBox,
            Confidence, Pose, Quality, and Landmarks - will always be returned. You can request for specific facial attributes
            (in addition to the default list) - by using ["DEFAULT", "FACE_OCCLUDED"] or just ["FACE_OCCLUDED"]. You can request
            for all facial attributes by using ["ALL"]. Requesting more attributes may increase response time. If you provide
            both, ["ALL", "DEFAULT"], the service uses a logical "AND" operator to determine which attributes to return (in
            this case, all attributes). Note t
      required:
      - Image
    DetectFacesResponse:
      type: object
      properties:
        FaceDetails:
          type: array
          items:
            $ref: '#/components/schemas/FaceDetail'
          description: Details of each face found in the image.
        OrientationCorrection:
          type: string
          enum:
          - ROTATE_0
          - ROTATE_90
          - ROTATE_180
          - ROTATE_270
          description: 'The value of OrientationCorrection is always null. If the input image is in .jpeg format, it might
            contain exchangeable image file format (Exif) metadata that includes the image''s orientation. Amazon Rekognition
            uses this orientation information to perform image correction. The bounding box coordinates are translated to
            represent object locations after the orientation information in the Exif metadata is used to correct the image
            orientation. Images in .png format don''t contain Exif metadata. Amazon Rekognition doesn’t perform image correction
            for images in .png format and .jpeg images without '
    Emotion:
      type: object
      properties:
        Type:
          type: string
          enum:
          - HAPPY
          - SAD
          - ANGRY
          - CONFUSED
          - DISGUSTED
          - SURPRISED
          - CALM
          - UNKNOWN
          - FEAR
          description: Type of emotion detected.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    EyeDirection:
      type: object
      properties:
        Yaw:
          type: number
          description: Value representing eye direction on the yaw axis.
        Pitch:
          type: number
          description: Value representing eye direction on the pitch axis.
        Confidence:
          type: number
          description: The confidence that the service has in its predicted eye direction.
    EyeOpen:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the eyes on the face are open.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Eyeglasses:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is wearing eye glasses or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    FaceDetail:
      type: object
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        AgeRange:
          $ref: '#/components/schemas/AgeRange'
        Smile:
          $ref: '#/components/schemas/Smile'
        Eyeglasses:
          $ref: '#/components/schemas/Eyeglasses'
        Sunglasses:
          $ref: '#/components/schemas/Sunglasses'
        Gender:
          $ref: '#/components/schemas/Gender'
        Beard:
          $ref: '#/components/schemas/Beard'
        Mustache:
          $ref: '#/components/schemas/Mustache'
        EyesOpen:
          $ref: '#/components/schemas/EyeOpen'
        MouthOpen:
          $ref: '#/components/schemas/MouthOpen'
        Emotions:
          type: array
          items:
            $ref: '#/components/schemas/Emotion'
          description: The emotions that appear to be expressed on the face, and the confidence level in the determination.
            The API is only making a determination of the physical appearance of a person's face. It is not a determination
            of the person’s internal emotional state and should not be used in such a way. For example, a person pretending
            to have a sad face might not be sad emotionally.
        Landmarks:
          type: array
          items:
            $ref: '#/components/schemas/Landmark'
          description: Indicates the location of landmarks on the face. Default attribute.
        Pose:
          $ref: '#/components/schemas/Pose'
        Quality:
          $ref: '#/components/schemas/ImageQuality'
        Confidence:
          type: number
          description: Confidence level that the bounding box contains a face (and not a different object such as a tree).
            Default attribute.
        FaceOccluded:
          $ref: '#/components/schemas/FaceOccluded'
        EyeDirection:
          $ref: '#/components/schemas/EyeDirection'
    FaceOccluded:
      type: object
      properties:
        Value:
          type: boolean
          description: True if a detected face’s eyes, nose, and mouth are partially captured or if they are covered by masks,
            dark sunglasses, cell phones, hands, or other objects. False if common occurrences that do not impact face verification
            are detected, such as eye glasses, lightly tinted sunglasses, strands of hair, and others.
        Confidence:
          type: number
          description: The confidence that the service has detected the presence of a face occlusion.
    Gender:
      type: object
      properties:
        Value:
          type: string
          enum:
          - Male
          - Female
          description: The predicted gender of the face.
        Confidence:
          type: number
          description: Level of confidence in the prediction.
    Image:
      type: object
      properties:
        Bytes:
          type: string
          format: byte
          description: Blob of image bytes up to 5 MBs. Note that the maximum image size you can pass to DetectCustomLabels
            is 4MB.
        S3Object:
          $ref: '#/components/schemas/S3Object'
    ImageQuality:
      type: object
      properties:
        Brightness:
          type: number
          description: Value representing brightness of the face. The service returns a value between 0 and 100 (inclusive).
            A higher value indicates a brighter face image.
        Sharpness:
          type: number
          description: Value representing sharpness of the face. The service returns a value between 0 and 100 (inclusive).
            A higher value indicates a sharper face image.
    InternalServerError:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
        Logref:
          type: string
          description: A universally unique identifier (UUID) for the request.
    Landmark:
      type: object
      properties:
        Type:
          type: string
          enum:
          - eyeLeft
          - eyeRight
          - nose
          - mouthLeft
          - mouthRight
          - leftEyeBrowLeft
          - leftEyeBrowRight
          - leftEyeBrowUp
          - rightEyeBrowLeft
          - rightEyeBrowRight
          - rightEyeBrowUp
          - leftEyeLeft
          - leftEyeRight
          - leftEyeUp
          - leftEyeDown
          - rightEyeLeft
          - rightEyeRight
          - rightEyeUp
          - rightEyeDown
          - noseLeft
          - noseRight
          - mouthUp
          - mouthDown
          - leftPupil
          - rightPupil
          - upperJawlineLeft
          - midJawlineLeft
          - chinBottom
          - midJawlineRight
          - upperJawlineRight
          description: Type of landmark.
        X:
          type: number
          description: The x-coordinate of the landmark expressed as a ratio of the width of the image. The x-coordinate is
            measured from the left-side of the image. For example, if the image is 700 pixels wide and the x-coordinate of
            the landmark is at 350 pixels, this value is 0.5.
        Y:
          type: number
          description: The y-coordinate of the landmark expressed as a ratio of the height of the image. The y-coordinate
            is measured from the top of the image. For example, if the image height is 200 pixels and the y-coordinate of
            the landmark is at 50 pixels, this value is 0.25.
    MouthOpen:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the mouth on the face is open or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Mustache:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face has mustache or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Pose:
      type: object
      properties:
        Roll:
          type: number
          description: Value representing the face rotation on the roll axis.
        Yaw:
          type: number
          description: Value representing the face rotation on the yaw axis.
        Pitch:
          type: number
          description: Value representing the face rotation on the pitch axis.
    S3Object:
      type: object
      properties:
        Bucket:
          type: string
          description: Name of the S3 bucket.
        Name:
          type: string
          description: S3 object key name.
        Version:
          type: string
          description: If the bucket is versioning enabled, you can specify the object version.
    Smile:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is smiling or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Sunglasses:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is wearing sunglasses or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/rekognition/service/2016-06-27/rekognition-2016-06-27.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)