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

*****************
start_face_search
*****************



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

  

  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 <https://docs.aws.amazon.com/rekognition/latest/dg/procedure-person-search-videos.html>`__.

  

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


  **Request Syntax**
  ::

    response = client.start_face_search(
        Video={
            'S3Object': {
                'Bucket': 'string',
                'Name': 'string',
                'Version': 'string'
            }
        },
        ClientRequestToken='string',
        FaceMatchThreshold=...,
        CollectionId='string',
        NotificationChannel={
            'SNSTopicArn': 'string',
            'RoleArn': 'string'
        },
        JobTag='string'
    )
    
  :type Video: dict
  :param Video: **[REQUIRED]** 

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

    

  
  :type FaceMatchThreshold: float
  :param FaceMatchThreshold: 

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

    

  
  :type CollectionId: string
  :param CollectionId: **[REQUIRED]** 

    ID of the collection that contains the faces you want to search for.

    

  
  :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 search. The Amazon SNS topic must have a topic name that begins with *AmazonRekognition* if you are using the AmazonRekognitionServiceRole permissions policy to access the topic.

    

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

    

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

    
    ::

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

    

    - *(dict) --* 
      

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

        The identifier for the search job. Use ``JobId`` to identify the job in a subsequent call to ``GetFaceSearch``.

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

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

  