:doc:`Rekognition <../../rekognition>` / Client / start_label_detection

*********************
start_label_detection
*********************



.. py:method:: Rekognition.Client.start_label_detection(**kwargs)

  

  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. You can filter with sets of individual labels or with label categories. You can specify inclusive filters, exclusive filters, or a combination of inclusive and exclusive filters. For more information on filtering, see `Detecting labels in a video <https://docs.aws.amazon.com/rekognition/latest/dg/labels-detecting-labels-video.html>`__.

   

  You can specify ``MinConfidence`` to control the confidence threshold for the labels returned. The default is 50.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/rekognition-2016-06-27/StartLabelDetection>`_  


  **Request Syntax**
  ::

    response = client.start_label_detection(
        Video={
            'S3Object': {
                'Bucket': 'string',
                'Name': 'string',
                'Version': 'string'
            }
        },
        ClientRequestToken='string',
        MinConfidence=...,
        NotificationChannel={
            'SNSTopicArn': 'string',
            'RoleArn': 'string'
        },
        JobTag='string',
        Features=[
            'GENERAL_LABELS',
        ],
        Settings={
            'GeneralLabels': {
                'LabelInclusionFilters': [
                    'string',
                ],
                'LabelExclusionFilters': [
                    'string',
                ],
                'LabelCategoryInclusionFilters': [
                    'string',
                ],
                'LabelCategoryExclusionFilters': [
                    'string',
                ]
            }
        }
    )
    
  :type Video: dict
  :param Video: **[REQUIRED]** 

    The video in which you want to detect labels. The video must be stored in an Amazon S3 bucket.

    

  
    - **S3Object** *(dict) --* 

      The Amazon S3 bucket name and file name for the video.

      

    
      - **Bucket** *(string) --* 

        Name of the S3 bucket.

        

      
      - **Name** *(string) --* 

        S3 object key name.

        

      
      - **Version** *(string) --* 

        If the bucket is versioning enabled, you can specify the object version.

        

      
    
  
  :type ClientRequestToken: string
  :param ClientRequestToken: 

    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.

    

  
  :type MinConfidence: float
  :param MinConfidence: 

    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.

    

  
  :type NotificationChannel: dict
  :param NotificationChannel: 

    The Amazon SNS topic ARN you want Amazon Rekognition Video to publish the completion status of the label detection operation to. The Amazon SNS topic must have a topic name that begins with *AmazonRekognition* if you are using the AmazonRekognitionServiceRole permissions policy.

    

  
    - **SNSTopicArn** *(string) --* **[REQUIRED]** 

      The Amazon SNS topic to which Amazon Rekognition posts the completion status.

      

    
    - **RoleArn** *(string) --* **[REQUIRED]** 

      The ARN of an IAM role that gives Amazon Rekognition publishing permissions to the Amazon SNS topic.

      

    
  
  :type JobTag: string
  :param JobTag: 

    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.

    

  
  :type Features: list
  :param Features: 

    The features to return after video analysis. You can specify that GENERAL_LABELS are returned.

    

  
    - *(string) --* 

    

  :type Settings: dict
  :param Settings: 

    The settings for a StartLabelDetection request.Contains the specified parameters for the label detection request of an asynchronous label analysis operation. Settings can include filters for GENERAL_LABELS.

    

  
    - **GeneralLabels** *(dict) --* 

      Contains filters for the object labels returned by DetectLabels. Filters can be inclusive, exclusive, or a combination of both and can be applied to individual labels or entire label categories. To see a list of label categories, see `Detecting Labels <https://docs.aws.amazon.com/rekognition/latest/dg/labels.html>`__.

      

    
      - **LabelInclusionFilters** *(list) --* 

        The labels that should be included in the return from DetectLabels.

        

      
        - *(string) --* 

        
    
      - **LabelExclusionFilters** *(list) --* 

        The labels that should be excluded from the return from DetectLabels.

        

      
        - *(string) --* 

        
    
      - **LabelCategoryInclusionFilters** *(list) --* 

        The label categories that should be included in the return from DetectLabels.

        

      
        - *(string) --* 

        
    
      - **LabelCategoryExclusionFilters** *(list) --* 

        The label categories that should be excluded from the return from DetectLabels.

        

      
        - *(string) --* 

        
    
    
  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'JobId': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **JobId** *(string) --* 

        The identifier for the label detection job. Use ``JobId`` to identify the job in a subsequent call to ``GetLabelDetection``.

        
  
  **Exceptions**
  
  *   :py:class:`Rekognition.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`Rekognition.Client.exceptions.IdempotentParameterMismatchException`

  
  *   :py:class:`Rekognition.Client.exceptions.InvalidParameterException`

  
  *   :py:class:`Rekognition.Client.exceptions.InvalidS3ObjectException`

  
  *   :py:class:`Rekognition.Client.exceptions.InternalServerError`

  
  *   :py:class:`Rekognition.Client.exceptions.VideoTooLargeException`

  
  *   :py:class:`Rekognition.Client.exceptions.ProvisionedThroughputExceededException`

  
  *   :py:class:`Rekognition.Client.exceptions.LimitExceededException`

  
  *   :py:class:`Rekognition.Client.exceptions.ThrottlingException`

  