detect_custom_labels ¶

def detect_custom_labels(
    self,
    project_version_arn: "capo_rekognition.types.project_version_arn.ProjectVersionArn",
    image: "capo_rekognition.types.image.Image",
    *,
    config_overrides: Optional[RekognitionClientConfig] = None,
    max_results: Optional["capo_rekognition.types.u_integer.UInteger"] = None,
    min_confidence: Optional["capo_rekognition.types.percent.Percent"] = None,
) -> "capo_rekognition.types.detect_custom_labels_response.DetectCustomLabelsResponse":
    """<note> <p>This operation applies only to Amazon Rekognition Custom Labels.</p> </note> <p>Detects custom labels in a supplied image by using an Amazon Rekognition Custom Labels model. </p> <p>You specify which version of a model version to use by using the <code>ProjectVersionArn</code> input parameter. </p> <p>You pass the input image as base64-encoded image bytes or as a reference to an image in an Amazon S3 bucket. If you use the AWS CLI to call Amazon Rekognition operations, passing image bytes is not supported. The image must be either a PNG or JPEG formatted file. </p> <p> For each object that the model version detects on an image, the API returns a (<code>CustomLabel</code>) object in an array (<code>CustomLabels</code>). Each <code>CustomLabel</code> object provides the label name (<code>Name</code>), the level of confidence that the image contains the object (<code>Confidence</code>), and object location information, if it exists, for the label on the image (<code>Geometry</code>). </p> <p>To filter labels that are returned, specify a value for <code>MinConfidence</code>. <code>DetectCustomLabelsLabels</code> only returns labels with a confidence that's higher than the specified value. The value of <code>MinConfidence</code> maps to the assumed threshold values created during training. For more information, see <i>Assumed threshold</i> in the Amazon Rekognition Custom Labels Developer Guide. Amazon Rekognition Custom Labels metrics expresses an assumed threshold as a floating point value between 0-1. The range of <code>MinConfidence</code> normalizes the threshold value to a percentage value (0-100). Confidence responses from <code>DetectCustomLabels</code> are also returned as a percentage. You can use <code>MinConfidence</code> to change the precision and recall or your model. For more information, see <i>Analyzing an image</i> in the Amazon Rekognition Custom Labels Developer Guide. </p> <p>If you don't specify a value for <code>MinConfidence</code>, <code>DetectCustomLabels</code> returns labels based on the assumed threshold of each label.</p> <p>This is a stateless API operation. That is, the operation does not persist any data.</p> <p>This operation requires permissions to perform the <code>rekognition:DetectCustomLabels</code> action. </p> <p>For more information, see <i>Analyzing an image</i> in the Amazon Rekognition Custom Labels Developer Guide. </p>

    Args:
        project_version_arn: <p>The ARN of the model version that you want to use. Only models associated with Custom Labels projects accepted by the operation. If a provided ARN refers to a model version associated with a project for a different feature type, then an InvalidParameterException is returned.</p>
        max_results: <p>Maximum number of results you want the service to return in the response. The service returns the specified number of highest confidence labels ranked from highest confidence to lowest.</p>
        min_confidence: <p>Specifies the minimum confidence level for the labels to return. <code>DetectCustomLabels</code> doesn't return any labels with a confidence value that's lower than this specified value. If you specify a value of 0, <code>DetectCustomLabels</code> returns all labels, regardless of the assumed threshold applied to each label. If you don't specify a value for <code>MinConfidence</code>, <code>DetectCustomLabels</code> returns labels based on the assumed threshold of each label.</p>

    Raises:
        capo_rekognition.errors.access_denied_exception.AccessDeniedException: <p>You are not authorized to perform the action.</p>
        capo_rekognition.errors.image_too_large_exception.ImageTooLargeException: <p>The input image size exceeds the allowed limit. If you are calling DetectProtectiveEquipment, the image size or resolution exceeds the allowed limit. For more information, see Guidelines and quotas in Amazon Rekognition in the Amazon Rekognition Developer Guide. </p>
        capo_rekognition.errors.internal_server_error.InternalServerError: <p>Amazon Rekognition experienced a service issue. Try your call again.</p>
        capo_rekognition.errors.invalid_image_format_exception.InvalidImageFormatException: <p>The provided image format is not supported. </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.resource_not_ready_exception.ResourceNotReadyException: <p>The requested resource isn't ready. For example, this exception occurs when you call <code>DetectCustomLabels</code> with a model version that isn't deployed. </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.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        To detect custom labels in an image with an Amazon Rekognition Custom Labels model
        Detects custom labels in an image with an Amazon Rekognition Custom Labels model

        >>> client.detect_custom_labels(project_version_arn='arn:aws:rekognition:us-east-1:111122223333:project/my-project/version/my-project.2023-07-31T11.49.37/1690829378219', image={'S3Object': {'Bucket': 'custom-labels-console-us-east-1-1111111111', 'Name': 'assets/flowers_1_test_dataset/camellia4.jpg'}}, max_results=100, min_confidence=50)
    """

    def _handler(
        req: "OperationRequest[capo_rekognition.types.detect_custom_labels_request.DetectCustomLabelsRequest]",
    ) -> OperationResponse[
        "capo_rekognition.types.detect_custom_labels_response.DetectCustomLabelsResponse"
    ]:
        import capo_rekognition._operations.rekognition_service.detect_custom_labels

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

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("DetectCustomLabels")
    )
    input_: capo_rekognition.types.detect_custom_labels_request.DetectCustomLabelsRequest = {
        "project_version_arn": project_version_arn,
        "image": image,
    }
    if max_results is not None:
        input_["max_results"] = max_results
    if min_confidence is not None:
        input_["min_confidence"] = min_confidence

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