Amazon Rekognition Facial Analysis API

openapi: 3.0.3
info:
  title: Amazon Rekognition Celebrity Recognition Facial Analysis API
  description: Amazon Rekognition is a cloud-based computer vision service providing image and video analysis including label detection, facial analysis, face comparison, celebrity recognition, text detection, content moderation, custom labels, face liveness detection, and streaming video analysis.
  version: '2016-06-27'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-generated-from: documentation
servers:
- url: https://rekognition.amazonaws.com
  description: Amazon Rekognition global endpoint
tags:
- name: Facial Analysis
  description: Detect and analyze faces with detailed attributes.
paths:
  /#DetectFaces:
    post:
      operationId: detectFaces
      summary: Amazon Rekognition Detect Faces
      description: Detects faces within an image and returns detailed facial attributes for each detected face.
      tags:
      - Facial Analysis
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DetectFacesRequest'
            examples:
              detectFacesRequestExample:
                summary: Default detectFaces request
                x-microcks-default: true
                value:
                  Image:
                    S3Object:
                      Bucket: my-images-bucket
                      Name: images/face.jpg
                  Attributes:
                  - ALL
      responses:
        '200':
          description: Faces detected successfully.
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DetectFacesResponse'
              examples:
                detectFaces200Example:
                  summary: Default detectFaces 200 response
                  x-microcks-default: true
                  value:
                    FaceDetails:
                    - BoundingBox:
                        Width: 0.35
                        Height: 0.45
                        Left: 0.1
                        Top: 0.05
                      Confidence: 99.7
                      AgeRange:
                        Low: 25
                        High: 35
        '400':
          description: Invalid request parameters.
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - aws_signature: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#CompareFaces:
    post:
      operationId: compareFaces
      summary: Amazon Rekognition Compare Faces
      description: Compares a face in the source input image with each face detected in the target input image.
      tags:
      - Facial Analysis
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CompareFacesRequest'
            examples:
              compareFacesRequestExample:
                summary: Default compareFaces request
                x-microcks-default: true
                value:
                  SourceImage:
                    S3Object:
                      Bucket: my-bucket
                      Name: source.jpg
                  TargetImage:
                    S3Object:
                      Bucket: my-bucket
                      Name: target.jpg
                  SimilarityThreshold: 80.0
      responses:
        '200':
          description: Face comparison completed successfully.
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CompareFacesResponse'
              examples:
                compareFaces200Example:
                  summary: Default compareFaces 200 response
                  x-microcks-default: true
                  value:
                    FaceMatches:
                    - Similarity: 95.3
                      Face:
                        BoundingBox:
                          Width: 0.3
                          Height: 0.4
                          Left: 0.1
                          Top: 0.1
                        Confidence: 99.5
                    UnmatchedFaces: []
        '400':
          description: Invalid request parameters.
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - aws_signature: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    FaceDetail:
      type: object
      description: Structure containing attributes of the face that the algorithm detected.
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        AgeRange:
          type: object
          description: The estimated age range in years for the face.
          properties:
            Low:
              type: integer
              example: 25
            High:
              type: integer
              example: 35
        Smile:
          type: object
          properties:
            Value:
              type: boolean
            Confidence:
              type: number
              format: float
        Gender:
          type: object
          properties:
            Value:
              type: string
              enum:
              - Male
              - Female
            Confidence:
              type: number
              format: float
        Emotions:
          type: array
          items:
            type: object
            properties:
              Type:
                type: string
                enum:
                - HAPPY
                - SAD
                - ANGRY
                - CONFUSED
                - DISGUSTED
                - SURPRISED
                - CALM
                - UNKNOWN
                - FEAR
              Confidence:
                type: number
                format: float
        Confidence:
          type: number
          format: float
          description: Confidence level that the bounding box contains a face.
          example: 99.7
    CompareFacesResponse:
      type: object
      properties:
        SourceImageFace:
          type: object
          properties:
            BoundingBox:
              $ref: '#/components/schemas/BoundingBox'
            Confidence:
              type: number
              format: float
        FaceMatches:
          type: array
          items:
            type: object
            properties:
              Similarity:
                type: number
                format: float
                example: 95.3
              Face:
                type: object
                properties:
                  BoundingBox:
                    $ref: '#/components/schemas/BoundingBox'
                  Confidence:
                    type: number
                    format: float
        UnmatchedFaces:
          type: array
          items:
            type: object
    Image:
      type: object
      description: Provides the input image either as bytes or an S3 object.
      properties:
        Bytes:
          type: string
          format: byte
          description: Blob of image bytes up to 5 MBs.
        S3Object:
          $ref: '#/components/schemas/S3Object'
    ErrorResponse:
      type: object
      description: Standard error response from the Amazon Rekognition API.
      properties:
        __type:
          type: string
          description: The type of exception.
          example: InvalidParameterException
        message:
          type: string
          description: Human-readable description of the error.
          example: Request has invalid parameters.
    DetectFacesRequest:
      type: object
      required:
      - Image
      properties:
        Image:
          $ref: '#/components/schemas/Image'
        Attributes:
          type: array
          description: An array of facial attributes to return. ALL returns all attributes.
          items:
            type: string
            enum:
            - DEFAULT
            - ALL
    S3Object:
      type: object
      description: Provides the S3 bucket name and object name.
      properties:
        Bucket:
          type: string
          description: Name of the S3 bucket.
          example: my-images-bucket
        Name:
          type: string
          description: S3 object key name.
          example: images/photo.jpg
        Version:
          type: string
          description: S3 object version ID if versioning is enabled.
          example: v1
    BoundingBox:
      type: object
      description: Identifies the bounding box around the label, face, text or object.
      properties:
        Width:
          type: number
          format: float
          description: Width of the bounding box as a ratio of the overall image width.
          example: 0.35
        Height:
          type: number
          format: float
          description: Height of the bounding box as a ratio of the overall image height.
          example: 0.45
        Left:
          type: number
          format: float
          description: Left coordinate of the bounding box as a ratio of overall image width.
          example: 0.1
        Top:
          type: number
          format: float
          description: Top coordinate of the bounding box as a ratio of overall image height.
          example: 0.05
    DetectFacesResponse:
      type: object
      properties:
        FaceDetails:
          type: array
          description: Details of each face found in the image.
          items:
            $ref: '#/components/schemas/FaceDetail'
        OrientationCorrection:
          type: string
          description: Orientation correction value.
    CompareFacesRequest:
      type: object
      required:
      - SourceImage
      - TargetImage
      properties:
        SourceImage:
          $ref: '#/components/schemas/Image'
        TargetImage:
          $ref: '#/components/schemas/Image'
        SimilarityThreshold:
          type: number
          format: float
          description: Minimum confidence for a match to be included in FaceMatches.
          example: 80.0
        QualityFilter:
          type: string
          enum:
          - NONE
          - AUTO
          - LOW
          - MEDIUM
          - HIGH
  securitySchemes:
    aws_signature:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. Include the Authorization header with AWS4-HMAC-SHA256 signature.