Amazon Rekognition Celebrity Recognition API

openapi: 3.1.0
info:
  title: Amazon Rekognition Celebrity Recognition 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:
  /#GetCelebrityRecognition:
    post:
      operationId: GetCelebrityRecognition
      summary: Get Celebrity Recognition
      description: Gets the celebrity recognition results for a Amazon Rekognition Video analysis started by StartCelebrityRecognition.
        Celebrity recognition in a video is an asynchronous operation. Analysis is started by a call to StartCelebrityRecognition
        which returns a job identifier (JobId). When the celebrity recognition operation finishes, Amazon Rekognition Video
        publishes a completion status to the Amazon Simple Notification Service topic registered in the initial call to StartCelebrityRecognition.
        To get the results of the celebrity recognition analysis, first check that the status value published to the Amazon
        SNS topic is SUCCEEDED. If so, call GetCelebrityDetection and pass the job identifier (JobId) from the initial call
        to StartCelebrityDetection. For more information, see Working With Stored Videos in the Amazon Rekognition Developer
        Guide. GetCelebrityRecognition returns detected celebrities and the time(s) they are detected in an array (Celebrities)
        of CelebrityRecognition objects. Each CelebrityRecognition contains information about the celebrity in a CelebrityDetail
        object and the time, Timestamp, the celebrity was detected. This CelebrityDetail object stores information about the
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetCelebrityRecognitionResponse'
        '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.GetCelebrityRecognition
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetCelebrityRecognitionRequest'
      tags:
      - Celebrity Recognition
  /#StartCelebrityRecognition:
    post:
      operationId: StartCelebrityRecognition
      summary: Start Celebrity Recognition
      description: Starts asynchronous recognition of celebrities in a stored video. Amazon Rekognition Video can detect celebrities
        in a video must be stored in an Amazon S3 bucket. Use Video to specify the bucket name and the filename of the video.
        StartCelebrityRecognition returns a job identifier (JobId) which you use to get the results of the analysis. When
        celebrity recognition analysis is finished, Amazon Rekognition Video publishes a completion status to the Amazon Simple
        Notification Service topic that you specify in NotificationChannel. To get the results of the celebrity recognition
        analysis, first check that the status value published to the Amazon SNS topic is SUCCEEDED. If so, call GetCelebrityRecognition
        and pass the job identifier (JobId) from the initial call to StartCelebrityRecognition. For more information, see
        Recognizing celebrities in the Amazon Rekognition Developer Guide.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartCelebrityRecognitionResponse'
        '400':
          description: AccessDeniedException; IdempotentParameterMismatchException; InvalidParameterException; InvalidS3ObjectException;
            LimitExceededException; ProvisionedThroughputExceededException; 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.StartCelebrityRecognition
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartCelebrityRecognitionRequest'
      tags:
      - Celebrity Recognition
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.
    CelebrityDetail:
      type: object
      properties:
        Urls:
          type: array
          items:
            type: string
          description: An array of URLs pointing to additional celebrity information.
        Name:
          type: string
          description: The name of the celebrity.
        Id:
          type: string
          description: The unique identifier for the celebrity.
        Confidence:
          type: number
          description: The confidence, in percentage, that Amazon Rekognition has that the recognized face is the celebrity.
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        Face:
          $ref: '#/components/schemas/FaceDetail'
        KnownGender:
          $ref: '#/components/schemas/KnownGender'
    CelebrityRecognition:
      type: object
      properties:
        Timestamp:
          type: integer
          description: The time, in milliseconds from the start of the video, that the celebrity was recognized. Note that
            Timestamp is not guaranteed to be accurate to the individual frame where the celebrity first appears.
        Celebrity:
          $ref: '#/components/schemas/CelebrityDetail'
    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.
    GetCelebrityRecognitionRequest:
      type: object
      properties:
        JobId:
          type: string
          description: Job identifier for the required celebrity recognition analysis. You can get the job identifer from
            a call to StartCelebrityRecognition.
        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 recognized celebrities to retrieve),
            Amazon Rekognition Video returns a pagination token in the response. You can use this pagination token to retrieve
            the next set of celebrities.
        SortBy:
          type: string
          enum:
          - ID
          - TIMESTAMP
          description: Sort to use for celebrities returned in Celebrities field. Specify ID to sort by the celebrity identifier,
            specify TIMESTAMP to sort by the time the celebrity was recognized.
      required:
      - JobId
    GetCelebrityRecognitionResponse:
      type: object
      properties:
        JobStatus:
          type: string
          enum:
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          description: The current status of the celebrity recognition job.
        StatusMessage:
          type: string
          description: If the job fails, StatusMessage provides a descriptive error message.
        VideoMetadata:
          $ref: '#/components/schemas/VideoMetadata'
        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 celebrities.
        Celebrities:
          type: array
          items:
            $ref: '#/components/schemas/CelebrityRecognition'
          description: Array of celebrities recognized in the video.
        JobId:
          type: string
          description: Job identifier for the celebrity recognition operation for which you want to obtain results. The job
            identifer is returned by an initial call to StartCelebrityRecognition.
        Video:
          $ref: '#/components/schemas/Video'
        JobTag:
          type: string
          description: A job identifier specified in the call to StartCelebrityRecognition 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.
    KnownGender:
      type: object
      properties:
        Type:
          type: string
          enum:
          - Male
          - Female
          - Nonbinary
          - Unlisted
          description: A string value of the KnownGender info about the Celebrity.
    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
    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.
    StartCelebrityRecognitionRequest:
      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 StartCelebrityRecognition
            requests, the same JobId is returned. Use ClientRequestToken to prevent the same job from being accidently started
            more than once.
        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
    StartCelebrityRecognitionResponse:
      type: object
      properties:
        JobId:
          type: string
          description: The identifier for the celebrity recognition analysis job. Use JobId to identify the job in a subsequent
            call to GetCelebrityRecognition.
    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)