Amazon Rekognition Face Collections API

openapi: 3.1.0
info:
  title: Amazon Rekognition Face Collections API
  version: '2016-06-27'
  description: Generated from AWS's published Smithy model for Amazon Rekognition. 3 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:
  /#IndexFaces:
    post:
      operationId: IndexFaces
      summary: Index Faces
      description: 'Detects faces in the input image and adds them to the specified collection. Amazon Rekognition doesn''t
        save the actual faces that are detected. Instead, the underlying detection algorithm first detects the faces in the
        input image. For each face, the algorithm extracts facial features into a feature vector, and stores it in the backend
        database. Amazon Rekognition uses feature vectors when it performs face match and search operations using the SearchFaces
        and SearchFacesByImage operations. For more information, see Adding faces to a collection in the Amazon Rekognition
        Developer Guide. To get the number of faces in a collection, call DescribeCollection. If you''re using version 1.0
        of the face detection model, IndexFaces indexes the 15 largest faces in the input image. Later versions of the face
        detection model index the 100 largest faces in the input image. If you''re using version 4 or later of the face model,
        image orientation information is not returned in the OrientationCorrection field. To determine which version of the
        model you''re using, call DescribeCollection and supply the collection ID. You can also get the model version from
        the value of FaceModelVersion in the response '
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/IndexFacesResponse'
              example:
                FaceRecords:
                - FaceDetail:
                    BoundingBox:
                      Width: 0.25
                      Top: 0.4933333396911621
                      Left: 0.31888890266418457
                      Height: 0.33481481671333313
                    Landmarks:
                    - Y: 0.6248345971107483
                      X: 0.3976764678955078
                      Type: eyeLeft
                    - Y: 0.6317117214202881
                      X: 0.4810936450958252
                      Type: eyeRight
                    - Y: 0.7111940383911133
                      X: 0.41986238956451416
                      Type: noseLeft
                    - Y: 0.7497701048851013
                      X: 0.40525302290916443
                      Type: mouthDown
                    - Y: 0.7558549642562866
                      X: 0.4753248989582062
                      Type: mouthUp
                    Pose:
                      Yaw: -24.438663482666016
                      Roll: 4.707281112670898
                      Pitch: -9.713645935058594
                    Quality:
                      Sharpness: 80
                      Brightness: 29.23358917236328
                    Confidence: 99.9991226196289
                  Face:
                    BoundingBox:
                      Width: 0.25
                      Top: 0.4933333396911621
                      Left: 0.31888890266418457
                      Height: 0.33481481671333313
                    FaceId: ff43d742-0c13-5d16-a3e8-03d3f58e980b
                    Confidence: 99.9991226196289
                    ImageId: 465f4e93-763e-51d0-b030-b9667a2d94b1
                - FaceDetail:
                    BoundingBox:
                      Width: 0.24444444477558136
                      Top: 0.15111111104488373
                      Left: 0.5144444704055786
                      Height: 0.32592591643333435
                    Landmarks:
                    - Y: 0.290842205286026
                      X: 0.6006892323493958
                      Type: eyeLeft
                    - Y: 0.29609042406082153
                      X: 0.6808141469955444
                      Type: eyeRight
                    - Y: 0.3522595763206482
                      X: 0.6395332217216492
                      Type: noseLeft
                    - Y: 0.38689887523651123
                      X: 0.5892083048820496
                      Type: mouthDown
                    - Y: 0.394125759601593
                      X: 0.674560010433197
                      Type: mouthUp
                    Pose:
                      Yaw: 6.716655254364014
                      Roll: 2.1029529571533203
                      Pitch: -4.683138370513916
                    Quality:
                      Sharpness: 160
                      Brightness: 34.951698303222656
                    Confidence: 99.99950408935547
                  Face:
                    BoundingBox:
                      Width: 0.24444444477558136
                      Top: 0.15111111104488373
                      Left: 0.5144444704055786
                      Height: 0.32592591643333435
                    FaceId: 8be04dba-4e58-520d-850e-9eae4af70eb2
                    Confidence: 99.99950408935547
                    ImageId: 465f4e93-763e-51d0-b030-b9667a2d94b1
                OrientationCorrection: ROTATE_0
        '400':
          description: AccessDeniedException; ImageTooLargeException; InvalidImageFormatException; InvalidParameterException;
            InvalidS3ObjectException; ProvisionedThroughputExceededException; ResourceNotFoundException; ServiceQuotaExceededException
          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.IndexFaces
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/IndexFacesRequest'
            example:
              CollectionId: myphotos
              Image:
                S3Object:
                  Bucket: mybucket
                  Name: myphoto
              ExternalImageId: myphotoid
              DetectionAttributes: []
      tags:
      - Face Collections
  /#CreateCollection:
    post:
      operationId: CreateCollection
      summary: Create Collection
      description: Creates a collection in an AWS Region. You can add faces to the collection using the IndexFaces operation.
        For example, you might create collections, one for each of your application users. A user can then index faces using
        the IndexFaces operation and persist results in a specific collection. Then, a user can search the collection for
        faces in the user-specific container. When you create a collection, it is associated with the latest version of the
        face model version. Collection names are case-sensitive. This operation requires permissions to perform the rekognition:CreateCollection
        action. If you want to tag your collection, you also require permission to perform the rekognition:TagResource operation.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateCollectionResponse'
              example:
                StatusCode: 200
                CollectionArn: aws:rekognition:us-west-2:123456789012:collection/myphotos
        '400':
          description: AccessDeniedException; InvalidParameterException; ProvisionedThroughputExceededException; ResourceAlreadyExistsException;
            ServiceQuotaExceededException
          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.CreateCollection
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
            example:
              CollectionId: myphotos
      tags:
      - Face Collections
  /#ListCollections:
    post:
      operationId: ListCollections
      summary: List Collections
      description: Returns list of collection IDs in your account. If the result is truncated, the response also provides
        a NextToken that you can use in the subsequent request to fetch the next set of collection IDs. For an example, see
        Listing collections in the Amazon Rekognition Developer Guide. This operation requires permissions to perform the
        rekognition:ListCollections action.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListCollectionsResponse'
              example:
                CollectionIds:
                - myphotos
        '400':
          description: AccessDeniedException; InvalidPaginationTokenException; InvalidParameterException; ProvisionedThroughputExceededException;
            ResourceNotFoundException
          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.ListCollections
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListCollectionsRequest'
      tags:
      - Face Collections
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.
    CreateCollectionRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: ID for the collection that you are creating.
        Tags:
          type: object
          additionalProperties:
            type: string
          description: A set of tags (key-value pairs) that you want to attach to the collection.
      required:
      - CollectionId
    CreateCollectionResponse:
      type: object
      properties:
        StatusCode:
          type: integer
          description: HTTP status code indicating the result of the operation.
        CollectionArn:
          type: string
          description: Amazon Resource Name (ARN) of the collection. You can use this to manage permissions on your resources.
        FaceModelVersion:
          type: string
          description: Version number of the face detection model associated with the collection you are creating.
    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.
    Face:
      type: object
      properties:
        FaceId:
          type: string
          description: Unique identifier that Amazon Rekognition assigns to the face.
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        ImageId:
          type: string
          description: Unique identifier that Amazon Rekognition assigns to the input image.
        ExternalImageId:
          type: string
          description: Identifier that you assign to all the faces in the input image.
        Confidence:
          type: number
          description: Confidence level that the bounding box contains a face (and not a different object such as a tree).
        IndexFacesModelVersion:
          type: string
          description: The version of the face detect and storage model that was used when indexing the face vector.
        UserId:
          type: string
          description: Unique identifier assigned to the user.
    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.
    FaceRecord:
      type: object
      properties:
        Face:
          $ref: '#/components/schemas/Face'
        FaceDetail:
          $ref: '#/components/schemas/FaceDetail'
    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.
    IndexFacesRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection to which you want to add the faces that are detected in the input
            images.
        Image:
          $ref: '#/components/schemas/Image'
        ExternalImageId:
          type: string
          description: The ID you want to assign to all the faces detected in the image.
        DetectionAttributes:
          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).
        MaxFaces:
          type: integer
          description: The maximum number of faces to index. The value of MaxFaces must be greater than or equal to 1. IndexFaces
            returns no more than 100 detected faces in an image, even if you specify a larger value for MaxFaces. If IndexFaces
            detects more faces than the value of MaxFaces, the faces with the lowest quality are filtered out first. If there
            are still more faces than the value of MaxFaces, the faces with the smallest bounding boxes are filtered out (up
            to the number that's needed to satisfy the value of MaxFaces). Information about the unindexed faces is available
            in the UnindexedFaces array. The fac
        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 indexed. 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 default value is AUTO. 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 filterin
      required:
      - CollectionId
      - Image
    IndexFacesResponse:
      type: object
      properties:
        FaceRecords:
          type: array
          items:
            $ref: '#/components/schemas/FaceRecord'
          description: An array of faces detected and added to the collection. For more information, see Searching Faces in
            a Collection in the Amazon Rekognition Developer Guide.
        OrientationCorrection:
          type: string
          enum:
          - ROTATE_0
          - ROTATE_90
          - ROTATE_180
          - ROTATE_270
          description: 'If your collection is associated with a face detection model that''s later than version 3.0, the value
            of OrientationCorrection is always null and no orientation information is returned. If your collection is associated
            with a face detection model that''s version 3.0 or earlier, the following applies: 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 '
        FaceModelVersion:
          type: string
          description: The version number of the face detection model that's associated with the input collection (CollectionId).
        UnindexedFaces:
          type: array
          items:
            $ref: '#/components/schemas/UnindexedFace'
          description: An array of faces that were detected in the image but weren't indexed. They weren't indexed because
            the quality filter identified them as low quality, or the MaxFaces request parameter filtered them out. To use
            the quality filter, you specify the QualityFilter request parameter.
    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.
    ListCollectionsRequest:
      type: object
      properties:
        NextToken:
          type: string
          description: Pagination token from the previous response.
        MaxResults:
          type: integer
          description: Maximum number of collection IDs to return.
    ListCollectionsResponse:
      type: object
      properties:
        CollectionIds:
          type: array
          items:
            type: string
          description: An array of collection IDs.
        NextToken:
          type: string
          description: If the result is truncated, the response provides a NextToken that you can use in the subsequent request
            to fetch the next set of collection IDs.
        FaceModelVersions:
          type: array
          items:
            type: string
          description: Version numbers of the face detection models associated with the collections in the array CollectionIds.
            For example, the value of FaceModelVersions[2] is the version number for the face detection model used by the
            collection in CollectionId[2].
    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.
    UnindexedFace:
      type: object
      properties:
        Reasons:
          type: array
          items:
            type: string
            enum:
            - EXCEEDS_MAX_FACES
            - EXTREME_POSE
            - LOW_BRIGHTNESS
            - LOW_SHARPNESS
            - LOW_CONFIDENCE
            - SMALL_BOUNDING_BOX
            - LOW_FACE_QUALITY
          description: An array of reasons that specify why a face wasn't indexed. EXTREME_POSE - The face is at a pose that
            can't be detected. For example, the head is turned too far away from the camera. EXCEEDS_MAX_FACES - The number
            of faces detected is already higher than that specified by the MaxFaces input parameter for IndexFaces. LOW_BRIGHTNESS
            - The image is too dark. LOW_SHARPNESS - The image is too blurry. LOW_CONFIDENCE - The face was detected with
            a low confidence. SMALL_BOUNDING_BOX - The bounding box around the face is too small.
        FaceDetail:
          $ref: '#/components/schemas/FaceDetail'
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)