Amazon Rekognition Face Search API

openapi: 3.1.0
info:
  title: Amazon Rekognition Face Search 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:
  /#GetFaceSearch:
    post:
      operationId: GetFaceSearch
      summary: Get Face Search
      description: 'Gets the face search results for Amazon Rekognition Video face search started by StartFaceSearch. The
        search returns faces in a collection that match the faces of persons detected in a video. It also includes the time(s)
        that faces are matched in the video. Face search in a video is an asynchronous operation. You start face search by
        calling to StartFaceSearch which returns a job identifier (JobId). When the search operation finishes, Amazon Rekognition
        Video publishes a completion status to the Amazon Simple Notification Service topic registered in the initial call
        to StartFaceSearch. To get the search results, first check that the status value published to the Amazon SNS topic
        is SUCCEEDED. If so, call GetFaceSearch and pass the job identifier (JobId) from the initial call to StartFaceSearch.
        For more information, see Searching Faces in a Collection in the Amazon Rekognition Developer Guide. The search results
        are retured in an array, Persons, of PersonMatch objects. EachPersonMatch element contains details about the matching
        faces in the input collection, person information (facial attributes, bounding boxes, and person identifer) for the
        matched person, and the time the person '
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetFaceSearchResponse'
        '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.GetFaceSearch
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetFaceSearchRequest'
      tags:
      - Face Search
  /#StartFaceSearch:
    post:
      operationId: StartFaceSearch
      summary: Start Face Search
      description: Starts the asynchronous search for faces in a collection that match the faces of persons detected in a
        stored video. The video must be stored in an Amazon S3 bucket. Use Video to specify the bucket name and the filename
        of the video. StartFaceSearch returns a job identifier (JobId) which you use to get the search results once the search
        has completed. When searching is finished, Amazon Rekognition Video publishes a completion status to the Amazon Simple
        Notification Service topic that you specify in NotificationChannel. To get the search results, first check that the
        status value published to the Amazon SNS topic is SUCCEEDED. If so, call GetFaceSearch and pass the job identifier
        (JobId) from the initial call to StartFaceSearch. For more information, see Searching stored videos for faces.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartFaceSearchResponse'
        '400':
          description: AccessDeniedException; IdempotentParameterMismatchException; InvalidParameterException; InvalidS3ObjectException;
            LimitExceededException; ProvisionedThroughputExceededException; ResourceNotFoundException; VideoTooLargeException
          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.StartFaceSearch
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartFaceSearchRequest'
      tags:
      - Face Search
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.
    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'
    FaceMatch:
      type: object
      properties:
        Similarity:
          type: number
          description: Confidence in the match of this face with the input face.
        Face:
          $ref: '#/components/schemas/Face'
    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.
    GetFaceSearchRequest:
      type: object
      properties:
        JobId:
          type: string
          description: The job identifer for the search request. You get the job identifier from an initial call to StartFaceSearch.
        MaxResults:
          type: integer
          description: Maximum number of results to return per paginated call. The largest value you can specify is 1000.
            If you specify a value greater than 1000, a maximum of 1000 results is returned. The default value is 1000.
        NextToken:
          type: string
          description: If the previous response was incomplete (because there is more search results to retrieve), Amazon
            Rekognition Video returns a pagination token in the response. You can use this pagination token to retrieve the
            next set of search results.
        SortBy:
          type: string
          enum:
          - INDEX
          - TIMESTAMP
          description: Sort to use for grouping faces in the response. Use TIMESTAMP to group faces by the time that they
            are recognized. Use INDEX to sort by recognized faces.
      required:
      - JobId
    GetFaceSearchResponse:
      type: object
      properties:
        JobStatus:
          type: string
          enum:
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          description: The current status of the face search job.
        StatusMessage:
          type: string
          description: If the job fails, StatusMessage provides a descriptive error message.
        NextToken:
          type: string
          description: If the response is truncated, Amazon Rekognition Video returns this token that you can use in the subsequent
            request to retrieve the next set of search results.
        VideoMetadata:
          $ref: '#/components/schemas/VideoMetadata'
        Persons:
          type: array
          items:
            $ref: '#/components/schemas/PersonMatch'
          description: An array of persons, PersonMatch, in the video whose face(s) match the face(s) in an Amazon Rekognition
            collection. It also includes time information for when persons are matched in the video. You specify the input
            collection in an initial call to StartFaceSearch. Each Persons element includes a time the person was matched,
            face match details (FaceMatches) for matching faces in the collection, and person information (Person) for the
            matched person.
        JobId:
          type: string
          description: Job identifier for the face search operation for which you want to obtain results. The job identifer
            is returned by an initial call to StartFaceSearch.
        Video:
          $ref: '#/components/schemas/Video'
        JobTag:
          type: string
          description: A job identifier specified in the call to StartFaceSearch and returned in the job completion notification
            sent to your Amazon Simple Notification Service topic.
    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.
    NotificationChannel:
      type: object
      properties:
        SNSTopicArn:
          type: string
          description: The Amazon SNS topic to which Amazon Rekognition posts the completion status.
        RoleArn:
          type: string
          description: The ARN of an IAM role that gives Amazon Rekognition publishing permissions to the Amazon SNS topic.
      required:
      - SNSTopicArn
      - RoleArn
    PersonDetail:
      type: object
      properties:
        Index:
          type: integer
          description: Identifier for the person detected person within a video. Use to keep track of the person throughout
            the video. The identifier is not stored by Amazon Rekognition.
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        Face:
          $ref: '#/components/schemas/FaceDetail'
    PersonMatch:
      type: object
      properties:
        Timestamp:
          type: integer
          description: The time, in milliseconds from the beginning of the video, that the person was matched in the video.
        Person:
          $ref: '#/components/schemas/PersonDetail'
        FaceMatches:
          type: array
          items:
            $ref: '#/components/schemas/FaceMatch'
          description: Information about the faces in the input collection that match the face of a person in the video.
    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.
    StartFaceSearchRequest:
      type: object
      properties:
        Video:
          $ref: '#/components/schemas/Video'
        ClientRequestToken:
          type: string
          description: Idempotent token used to identify the start request. If you use the same token with multiple StartFaceSearch
            requests, the same JobId is returned. Use ClientRequestToken to prevent the same job from being accidently started
            more than once.
        FaceMatchThreshold:
          type: number
          description: The minimum confidence in the person match to return. For example, don't return any matches where confidence
            in matches is less than 70%. The default value is 80%.
        CollectionId:
          type: string
          description: ID of the collection that contains the faces you want to search for.
        NotificationChannel:
          $ref: '#/components/schemas/NotificationChannel'
        JobTag:
          type: string
          description: An identifier you specify that's returned in the completion notification that's published to your Amazon
            Simple Notification Service topic. For example, you can use JobTag to group related jobs and identify them in
            the completion notification.
      required:
      - Video
      - CollectionId
    StartFaceSearchResponse:
      type: object
      properties:
        JobId:
          type: string
          description: The identifier for the search job. Use JobId to identify the job in a subsequent call to GetFaceSearch.
    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.
    Video:
      type: object
      properties:
        S3Object:
          $ref: '#/components/schemas/S3Object'
    VideoMetadata:
      type: object
      properties:
        Codec:
          type: string
          description: Type of compression used in the analyzed video.
        DurationMillis:
          type: integer
          description: Length of the video in milliseconds.
        Format:
          type: string
          description: Format of the analyzed video. Possible values are MP4, MOV and AVI.
        FrameRate:
          type: number
          description: Number of frames per second in the video.
        FrameHeight:
          type: integer
          description: Vertical pixel dimension of the video.
        FrameWidth:
          type: integer
          description: Horizontal pixel dimension of the video.
        ColorRange:
          type: string
          enum:
          - FULL
          - LIMITED
          description: A description of the range of luminance values in a video, either LIMITED (16 to 235) or FULL (0 to
            255).
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)