start_face_search ¶

def start_face_search(
    self,
    video: "capo_rekognition.types.video.Video",
    collection_id: "capo_rekognition.types.collection_id.CollectionId",
    *,
    config_overrides: Optional[RekognitionClientConfig] = None,
    client_request_token: Optional[
        "capo_rekognition.types.client_request_token.ClientRequestToken"
    ] = None,
    face_match_threshold: Optional["capo_rekognition.types.percent.Percent"] = None,
    notification_channel: Optional[
        "capo_rekognition.types.notification_channel.NotificationChannel"
    ] = None,
    job_tag: Optional["capo_rekognition.types.job_tag.JobTag"] = None,
) -> "capo_rekognition.types.start_face_search_response.StartFaceSearchResponse":
    """<p>Starts the asynchronous search for faces in a collection that match the faces of persons detected in a stored video.</p> <p>The video must be stored in an Amazon S3 bucket. Use <a>Video</a> to specify the bucket name and the filename of the video. <code>StartFaceSearch</code> returns a job identifier (<code>JobId</code>) 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 <code>NotificationChannel</code>. To get the search results, first check that the status value published to the Amazon SNS topic is <code>SUCCEEDED</code>. If so, call <a>GetFaceSearch</a> and pass the job identifier (<code>JobId</code>) from the initial call to <code>StartFaceSearch</code>. For more information, see <a href="https://docs.aws.amazon.com/rekognition/latest/dg/procedure-person-search-videos.html">Searching stored videos for faces</a>. </p>

    Args:
        video: <p>The video you want to search. The video must be stored in an Amazon S3 bucket. </p>
        client_request_token: <p>Idempotent token used to identify the start request. If you use the same token with multiple <code>StartFaceSearch</code> requests, the same <code>JobId</code> is returned. Use <code>ClientRequestToken</code> to prevent the same job from being accidently started more than once. </p>
        face_match_threshold: <p>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%.</p>
        collection_id: <p>ID of the collection that contains the faces you want to search for.</p>
        notification_channel: <p>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 <i>AmazonRekognition</i> if you are using the AmazonRekognitionServiceRole permissions policy to access the topic.</p>
        job_tag: <p>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 <code>JobTag</code> to group related jobs and identify them in the completion notification.</p>

    Raises:
        capo_rekognition.errors.access_denied_exception.AccessDeniedException: <p>You are not authorized to perform the action.</p>
        capo_rekognition.errors.idempotent_parameter_mismatch_exception.IdempotentParameterMismatchException: <p>A <code>ClientRequestToken</code> input parameter was reused with an operation, but at least one of the other input parameters is different from the previous call to the operation.</p>
        capo_rekognition.errors.internal_server_error.InternalServerError: <p>Amazon Rekognition experienced a service issue. Try your call again.</p>
        capo_rekognition.errors.invalid_parameter_exception.InvalidParameterException: <p>Input parameter violated a constraint. Validate your parameter before calling the API operation again.</p>
        capo_rekognition.errors.invalid_s3_object_exception.InvalidS3ObjectException: <p>Amazon Rekognition is unable to access the S3 object specified in the request.</p>
        capo_rekognition.errors.limit_exceeded_exception.LimitExceededException: <p>An Amazon Rekognition service limit was exceeded. For example, if you start too many jobs concurrently, subsequent calls to start operations (ex: <code>StartLabelDetection</code>) will raise a <code>LimitExceededException</code> exception (HTTP status code: 400) until the number of concurrently running jobs is below the Amazon Rekognition service limit. </p>
        capo_rekognition.errors.provisioned_throughput_exceeded_exception.ProvisionedThroughputExceededException: <p>The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.</p>
        capo_rekognition.errors.resource_not_found_exception.ResourceNotFoundException: <p>The resource specified in the request cannot be found.</p>
        capo_rekognition.errors.throttling_exception.ThrottlingException: <p>Amazon Rekognition is temporarily unable to process the request. Try your call again.</p>
        capo_rekognition.errors.video_too_large_exception.VideoTooLargeException: <p>The file size or duration of the supplied media is too large. The maximum file size is 10GB. The maximum duration is 6 hours. </p>
        capo_rekognition.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_rekognition.types.start_face_search_request.StartFaceSearchRequest]",
    ) -> OperationResponse[
        "capo_rekognition.types.start_face_search_response.StartFaceSearchResponse"
    ]:
        import capo_rekognition._operations.rekognition_service.start_face_search

        output, http_response = (
            capo_rekognition._operations.rekognition_service.start_face_search.start_face_search(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("StartFaceSearch")
    )
    input_: capo_rekognition.types.start_face_search_request.StartFaceSearchRequest = {
        "video": video,
        "collection_id": collection_id,
    }
    if client_request_token is not None:
        input_["client_request_token"] = client_request_token
    if face_match_threshold is not None:
        input_["face_match_threshold"] = face_match_threshold
    if notification_channel is not None:
        input_["notification_channel"] = notification_channel
    if job_tag is not None:
        input_["job_tag"] = job_tag

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output