Amazon Rekognition Stored Video Analysis API

openapi: 3.1.0
info:
  title: Amazon Rekognition Stored Video 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:
  /#GetLabelDetection:
    post:
      operationId: GetLabelDetection
      summary: Get Label Detection
      description: 'Gets the label detection results of a Amazon Rekognition Video analysis started by StartLabelDetection.
        The label detection operation is started by a call to StartLabelDetection which returns a job identifier (JobId).
        When the label detection operation finishes, Amazon Rekognition publishes a completion status to the Amazon Simple
        Notification Service topic registered in the initial call to StartlabelDetection. To get the results of the label
        detection operation, first check that the status value published to the Amazon SNS topic is SUCCEEDED. If so, call
        GetLabelDetection and pass the job identifier (JobId) from the initial call to StartLabelDetection. GetLabelDetection
        returns an array of detected labels (Labels) sorted by the time the labels were detected. You can also sort by the
        label name by specifying NAME for the SortBy input parameter. If there is no NAME specified, the default sort is by
        timestamp. You can select how results are aggregated by using the AggregateBy input parameter. The default aggregation
        method is TIMESTAMPS. You can also aggregate by SEGMENTS, which aggregates all instances of labels detected in a given
        segment. The returned Labels array may include the '
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetLabelDetectionResponse'
        '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.GetLabelDetection
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetLabelDetectionRequest'
      tags:
      - Stored Video Analysis
  /#StartLabelDetection:
    post:
      operationId: StartLabelDetection
      summary: Start Label Detection
      description: Starts asynchronous detection of labels in a stored video. Amazon Rekognition Video can detect labels in
        a video. Labels are instances of real-world entities. This includes objects like flower, tree, and table; events like
        wedding, graduation, and birthday party; concepts like landscape, evening, and nature; and activities like a person
        getting out of a car or a person skiing. The video must be stored in an Amazon S3 bucket. Use Video to specify the
        bucket name and the filename of the video. StartLabelDetection returns a job identifier (JobId) which you use to get
        the results of the operation. When label detection 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
        label detection operation, first check that the status value published to the Amazon SNS topic is SUCCEEDED. If so,
        call GetLabelDetection and pass the job identifier (JobId) from the initial call to StartLabelDetection. Optional
        Parameters StartLabelDetection has the GENERAL_LABELS Feature applied by default. This feature allows you to provide
        filtering criteria to the Settings parameter. Yo
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartLabelDetectionResponse'
        '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.StartLabelDetection
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartLabelDetectionRequest'
      tags:
      - Stored Video 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.
    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.
    DominantColor:
      type: object
      properties:
        Red:
          type: integer
          description: The Red RGB value for a dominant color.
        Blue:
          type: integer
          description: The Blue RGB value for a dominant color.
        Green:
          type: integer
          description: The Green RGB value for a dominant color.
        HexCode:
          type: string
          description: The Hex code equivalent of the RGB values for a dominant color.
        CSSColor:
          type: string
          description: The CSS color name of a dominant color.
        SimplifiedColor:
          type: string
          description: One of 12 simplified color names applied to a dominant color.
        PixelPercent:
          type: number
          description: The percentage of image pixels that have a given dominant color.
    GeneralLabelsSettings:
      type: object
      properties:
        LabelInclusionFilters:
          type: array
          items:
            type: string
          description: The labels that should be included in the return from DetectLabels.
        LabelExclusionFilters:
          type: array
          items:
            type: string
          description: The labels that should be excluded from the return from DetectLabels.
        LabelCategoryInclusionFilters:
          type: array
          items:
            type: string
          description: The label categories that should be included in the return from DetectLabels.
        LabelCategoryExclusionFilters:
          type: array
          items:
            type: string
          description: The label categories that should be excluded from the return from DetectLabels.
    GetLabelDetectionRequest:
      type: object
      properties:
        JobId:
          type: string
          description: Job identifier for the label detection operation for which you want results returned. You get the job
            identifer from an initial call to StartlabelDetection.
        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 are more labels to retrieve), Amazon Rekognition
            Video returns a pagination token in the response. You can use this pagination token to retrieve the next set of
            labels.
        SortBy:
          type: string
          enum:
          - NAME
          - TIMESTAMP
          description: Sort to use for elements in the Labels array. Use TIMESTAMP to sort array elements by the time labels
            are detected. Use NAME to alphabetically group elements for a label together. Within each label group, the array
            element are sorted by detection confidence. The default sort is by TIMESTAMP.
        AggregateBy:
          type: string
          enum:
          - TIMESTAMPS
          - SEGMENTS
          description: Defines how to aggregate the returned results. Results can be aggregated by timestamps or segments.
      required:
      - JobId
    GetLabelDetectionRequestMetadata:
      type: object
      properties:
        SortBy:
          type: string
          enum:
          - NAME
          - TIMESTAMP
          description: The sorting method chosen for a GetLabelDetection request.
        AggregateBy:
          type: string
          enum:
          - TIMESTAMPS
          - SEGMENTS
          description: The aggregation method chosen for a GetLabelDetection request.
    GetLabelDetectionResponse:
      type: object
      properties:
        JobStatus:
          type: string
          enum:
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          description: The current status of the label detection 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 labels.
        Labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelDetection'
          description: An array of labels detected in the video. Each element contains the detected label and the time, in
            milliseconds from the start of the video, that the label was detected.
        LabelModelVersion:
          type: string
          description: Version number of the label detection model that was used to detect labels.
        JobId:
          type: string
          description: Job identifier for the label detection operation for which you want to obtain results. The job identifer
            is returned by an initial call to StartLabelDetection.
        Video:
          $ref: '#/components/schemas/Video'
        JobTag:
          type: string
          description: A job identifier specified in the call to StartLabelDetection and returned in the job completion notification
            sent to your Amazon Simple Notification Service topic.
        GetRequestMetadata:
          $ref: '#/components/schemas/GetLabelDetectionRequestMetadata'
    Instance:
      type: object
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        Confidence:
          type: number
          description: The confidence that Amazon Rekognition has in the accuracy of the bounding box.
        DominantColors:
          type: array
          items:
            $ref: '#/components/schemas/DominantColor'
          description: The dominant colors found in an individual instance of a label.
    InternalServerError:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
        Logref:
          type: string
          description: A universally unique identifier (UUID) for the request.
    Label:
      type: object
      properties:
        Name:
          type: string
          description: The name (label) of the object or scene.
        Confidence:
          type: number
          description: Level of confidence.
        Instances:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
          description: If Label represents an object, Instances contains the bounding boxes for each instance of the detected
            object. Bounding boxes are returned for common object labels such as people, cars, furniture, apparel or pets.
        Parents:
          type: array
          items:
            $ref: '#/components/schemas/Parent'
          description: The parent labels for a label. The response includes all ancestor labels.
        Aliases:
          type: array
          items:
            $ref: '#/components/schemas/LabelAlias'
          description: A list of potential aliases for a given label.
        Categories:
          type: array
          items:
            $ref: '#/components/schemas/LabelCategory'
          description: A list of the categories associated with a given label.
    LabelAlias:
      type: object
      properties:
        Name:
          type: string
          description: The name of an alias for a given label.
    LabelCategory:
      type: object
      properties:
        Name:
          type: string
          description: The name of a category that applies to a given label.
    LabelDetection:
      type: object
      properties:
        Timestamp:
          type: integer
          description: Time, in milliseconds from the start of the video, that the label was detected. Note that Timestamp
            is not guaranteed to be accurate to the individual frame where the label first appears.
        Label:
          $ref: '#/components/schemas/Label'
        StartTimestampMillis:
          type: integer
          description: The time in milliseconds defining the start of the timeline segment containing a continuously detected
            label.
        EndTimestampMillis:
          type: integer
          description: The time in milliseconds defining the end of the timeline segment containing a continuously detected
            label.
        DurationMillis:
          type: integer
          description: The time duration of a segment in milliseconds, I.e. time elapsed from StartTimestampMillis to EndTimestampMillis.
    LabelDetectionSettings:
      type: object
      properties:
        GeneralLabels:
          $ref: '#/components/schemas/GeneralLabelsSettings'
    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
    Parent:
      type: object
      properties:
        Name:
          type: string
          description: The name of the parent label.
    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.
    StartLabelDetectionRequest:
      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 StartLabelDetection
            requests, the same JobId is returned. Use ClientRequestToken to prevent the same job from being accidently started
            more than once.
        MinConfidence:
          type: number
          description: Specifies the minimum confidence that Amazon Rekognition Video must have in order to return a detected
            label. Confidence represents how certain Amazon Rekognition is that a label is correctly identified.0 is the lowest
            confidence. 100 is the highest confidence. Amazon Rekognition Video doesn't return any labels with a confidence
            level lower than this specified value. If you don't specify MinConfidence, the operation returns labels and bounding
            boxes (if detected) with confidence values greater than or equal to 50 percent.
        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.
        Features:
          type: array
          items:
            type: string
            enum:
            - GENERAL_LABELS
          description: The features to return after video analysis. You can specify that GENERAL_LABELS are returned.
        Settings:
          $ref: '#/components/schemas/LabelDetectionSettings'
      required:
      - Video
    StartLabelDetectionResponse:
      type: object
      properties:
        JobId:
          type: string
          description: The identifier for the label detection job. Use JobId to identify the job in a subsequent call to GetLabelDetection.
    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)