start_face_detection ¶

def start_face_detection(
    self,
    video: "capo_rekognition.types.video.Video",
    *,
    config_overrides: Optional[RekognitionClientConfig] = None,
    client_request_token: Optional[
        "capo_rekognition.types.client_request_token.ClientRequestToken"
    ] = None,
    notification_channel: Optional[
        "capo_rekognition.types.notification_channel.NotificationChannel"
    ] = None,
    face_attributes: Optional[
        "capo_rekognition.types.face_attributes.FaceAttributes"
    ] = None,
    job_tag: Optional["capo_rekognition.types.job_tag.JobTag"] = None,
) -> "capo_rekognition.types.start_face_detection_response.StartFaceDetectionResponse":
    """<p>Starts asynchronous detection of faces in a stored video.</p> <p>Amazon Rekognition Video can detect faces in a video stored in an Amazon S3 bucket. Use <a>Video</a> to specify the bucket name and the filename of the video. <code>StartFaceDetection</code> returns a job identifier (<code>JobId</code>) 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 <code>NotificationChannel</code>. To get the results of the face detection operation, first check that the status value published to the Amazon SNS topic is <code>SUCCEEDED</code>. If so, call <a>GetFaceDetection</a> and pass the job identifier (<code>JobId</code>) from the initial call to <code>StartFaceDetection</code>.</p> <p>For more information, see Detecting faces in a stored video in the Amazon Rekognition Developer Guide.</p>

    Args:
        video: <p>The video in which you want to detect faces. 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>StartFaceDetection</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>
        notification_channel: <p>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 <i>AmazonRekognition</i> if you are using the AmazonRekognitionServiceRole permissions policy.</p>
        face_attributes: <p>The face attributes you want returned.</p> <p> <code>DEFAULT</code> - The following subset of facial attributes are returned: BoundingBox, Confidence, Pose, Quality and Landmarks. </p> <p> <code>ALL</code> - All facial attributes are returned.</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.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_detection_request.StartFaceDetectionRequest]",
    ) -> OperationResponse[
        "capo_rekognition.types.start_face_detection_response.StartFaceDetectionResponse"
    ]:
        import capo_rekognition._operations.rekognition_service.start_face_detection

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

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("StartFaceDetection")
    )
    input_: capo_rekognition.types.start_face_detection_request.StartFaceDetectionRequest = {
        "video": video
    }
    if client_request_token is not None:
        input_["client_request_token"] = client_request_token
    if notification_channel is not None:
        input_["notification_channel"] = notification_channel
    if face_attributes is not None:
        input_["face_attributes"] = face_attributes
    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