AmazonRekognitionClient.DetectCustomLabels Method (DetectCustomLabelsRequest)

This operation applies only to Amazon Rekognition Custom Labels.

Detects custom labels in a supplied image by using an Amazon Rekognition Custom Labels model.

You specify which version of a model version to use by using the ProjectVersionArn input parameter.

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.

For each object that the model version detects on an image, the API returns a (CustomLabel) object in an array (CustomLabels). Each CustomLabel object provides the label name (Name), the level of confidence that the image contains the object (Confidence), and object location information, if it exists, for the label on the image (Geometry). Note that for the DetectCustomLabelsLabels operation, Polygons are not returned in the Geometry section of the response.

To filter labels that are returned, specify a value for MinConfidence. DetectCustomLabelsLabels only returns labels with a confidence that's higher than the specified value. The value of MinConfidence maps to the assumed threshold values created during training. For more information, see Assumed threshold 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 MinConfidence normalizes the threshold value to a percentage value (0-100). Confidence responses from DetectCustomLabels are also returned as a percentage. You can use MinConfidence to change the precision and recall or your model. For more information, see Analyzing an image in the Amazon Rekognition Custom Labels Developer Guide.

If you don't specify a value for MinConfidence, DetectCustomLabels returns labels based on the assumed threshold of each label.

This is a stateless API operation. That is, the operation does not persist any data.

This operation requires permissions to perform the rekognition:DetectCustomLabels action.

For more information, see Analyzing an image in the Amazon Rekognition Custom Labels Developer Guide.

Note:

For .NET Core this operation is only available in asynchronous form. Please refer to DetectCustomLabelsAsync.

Namespace: Amazon.Rekognition
Assembly: AWSSDK.Rekognition.dll
Version: 3.x.y.z

Syntax

public virtual DetectCustomLabelsResponse DetectCustomLabels(
         DetectCustomLabelsRequest request
)

Parameters

request: Type: Amazon.Rekognition.Model.DetectCustomLabelsRequest

Container for the necessary parameters to execute the DetectCustomLabels service method.

Return Value

Type: DetectCustomLabelsResponse

The response from the DetectCustomLabels service method, as returned by Rekognition.

Exceptions

Exception	Condition
AccessDeniedException	You are not authorized to perform the action.
ImageTooLargeException	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.
InternalServerErrorException	Amazon Rekognition experienced a service issue. Try your call again.
InvalidImageFormatException	The provided image format is not supported.
InvalidParameterException	Input parameter violated a constraint. Validate your parameter before calling the API operation again.
InvalidS3ObjectException	Amazon Rekognition is unable to access the S3 object specified in the request.
LimitExceededException	An Amazon Rekognition service limit was exceeded. For example, if you start too many jobs concurrently, subsequent calls to start operations (ex: StartLabelDetection) will raise a LimitExceededException exception (HTTP status code: 400) until the number of concurrently running jobs is below the Amazon Rekognition service limit.
ProvisionedThroughputExceededException	The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.
ResourceNotFoundException	The resource specified in the request cannot be found.
ResourceNotReadyException	The requested resource isn't ready. For example, this exception occurs when you call DetectCustomLabels with a model version that isn't deployed.
ThrottlingException	Amazon Rekognition is temporarily unable to process the request. Try your call again.

Examples

Detects custom labels in an image with an Amazon Rekognition Custom Labels model

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


var client = new AmazonRekognitionClient();
var response = client.DetectCustomLabels(new DetectCustomLabelsRequest 
{
    Image = new Image { S3Object = new S3Object {
        Bucket = "custom-labels-console-us-east-1-1111111111",
        Name = "assets/flowers_1_test_dataset/camellia4.jpg"
    } },
    MaxResults = 100,
    MinConfidence = 50,
    ProjectVersionArn = "arn:aws:rekognition:us-east-1:111122223333:project/my-project/version/my-project.2023-07-31T11.49.37/1690829378219"
});

List<CustomLabel> customLabels = response.CustomLabels;

Version Information

.NET Framework:
Supported in: 4.5 and newer, 3.5

AmazonRekognitionClient.DetectCustomLabels (DetectCustomLabelsRequest)

Method