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

********************
start_face_detection
********************



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

  

  Starts asynchronous detection of faces in a stored video.

   

  Amazon Rekognition Video can detect faces in a video stored in an Amazon S3 bucket. Use  Video to specify the bucket name and the filename of the video. ``StartFaceDetection`` returns a job identifier ( ``JobId``) that you use to get the results of the operation. When face 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 face detection operation, first check that the status value published to the Amazon SNS topic is ``SUCCEEDED``. If so, call  GetFaceDetection and pass the job identifier ( ``JobId``) from the initial call to ``StartFaceDetection``.

   

  For more information, see Detecting faces in a stored video in the Amazon Rekognition Developer Guide.

  

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


  **Request Syntax**
  ::

    response = client.start_face_detection(
        Video={
            'S3Object': {
                'Bucket': 'string',
                'Name': 'string',
                'Version': 'string'
            }
        },
        ClientRequestToken='string',
        NotificationChannel={
            'SNSTopicArn': 'string',
            'RoleArn': 'string'
        },
        FaceAttributes='DEFAULT'|'ALL',
        JobTag='string'
    )
    
  :type Video: dict
  :param Video: **[REQUIRED]** 

    The video in which you want to detect faces. 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 ``StartFaceDetection`` requests, the same ``JobId`` is returned. Use ``ClientRequestToken`` to prevent the same job from being accidently started more than once.

    

  
  :type NotificationChannel: dict
  :param NotificationChannel: 

    The ARN of the Amazon SNS topic to which you want Amazon Rekognition Video to publish the completion status of the face detection operation. 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 FaceAttributes: string
  :param FaceAttributes: 

    The face attributes you want returned.

     

    ``DEFAULT`` - The following subset of facial attributes are returned: BoundingBox, Confidence, Pose, Quality and Landmarks.

     

    ``ALL`` - All facial attributes are returned.

    

  
  :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.

    

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

    
    ::

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

    

    - *(dict) --* 
      

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

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

        
  
  **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`

  