Amazon Rekognition

2019/12/04 - Amazon Rekognition - 7 new1 updated api methods

Changes  Update rekognition client to latest version

DescribeProjects (new) Link ¶

Lists and gets information about your Amazon Rekognition Custom Labels projects.

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

See also: AWS API Documentation

Request Syntax

client.describe_projects(
    NextToken='string',
    MaxResults=123
)
type NextToken:

string

param NextToken:

If the previous response was incomplete (because there is more results to retrieve), Amazon Rekognition Custom Labels returns a pagination token in the response. You can use this pagination token to retrieve the next set of results.

type MaxResults:

integer

param MaxResults:

The maximum number of results to return per paginated call. The largest value you can specify is 100. If you specify a value greater than 100, a ValidationException error occurs. The default value is 100.

rtype:

dict

returns:

Response Syntax

{
    'ProjectDescriptions': [
        {
            'ProjectArn': 'string',
            'CreationTimestamp': datetime(2015, 1, 1),
            'Status': 'CREATING'|'CREATED'|'DELETING'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • ProjectDescriptions (list) --

      A list of project descriptions. The list is sorted by the date and time the projects are created.

      • (dict) --

        A description of a Amazon Rekognition Custom Labels project.

        • ProjectArn (string) --

          The Amazon Resource Name (ARN) of the project.

        • CreationTimestamp (datetime) --

          The Unix timestamp for the date and time that the project was created.

        • Status (string) --

          The current status of the project.

    • NextToken (string) --

      If the previous response was incomplete (because there is more results to retrieve), Amazon Rekognition Custom Labels returns a pagination token in the response. You can use this pagination token to retrieve the next set of results.

DetectCustomLabels (new) Link ¶

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

During training model calculates a threshold value that determines if a prediction for a label is true. By default, DetectCustomLabels doesn't return labels whose confidence value is below the model's calculated threshold value. To filter labels that are returned, specify a value for MinConfidence that is higher than the model's calculated threshold. You can get the model's calculated threshold from the model's training results shown in the Amazon Rekognition Custom Labels console. To get all labels, regardless of confidence, specify a MinConfidence value of 0.

You can also add the MaxResults parameter to limit the number of labels returned.

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.

See also: AWS API Documentation

Request Syntax

client.detect_custom_labels(
    ProjectVersionArn='string',
    Image={
        'Bytes': b'bytes',
        'S3Object': {
            'Bucket': 'string',
            'Name': 'string',
            'Version': 'string'
        }
    },
    MaxResults=123,
    MinConfidence=...
)
type ProjectVersionArn:

string

param ProjectVersionArn:

[REQUIRED]

The ARN of the model version that you want to use.

type Image:

dict

param Image:

[REQUIRED]

Provides the input image either as bytes or an S3 object.

You pass image bytes to an Amazon Rekognition API operation by using the Bytes property. For example, you would use the Bytes property to pass an image loaded from a local file system. Image bytes passed by using the Bytes property must be base64-encoded. Your code may not need to encode image bytes if you are using an AWS SDK to call Amazon Rekognition API operations.

For more information, see Analyzing an Image Loaded from a Local File System in the Amazon Rekognition Developer Guide.

You pass images stored in an S3 bucket to an Amazon Rekognition API operation by using the S3Object property. Images stored in an S3 bucket do not need to be base64-encoded.

The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

If you use the AWS CLI to call Amazon Rekognition operations, passing image bytes using the Bytes property is not supported. You must first upload the image to an Amazon S3 bucket and then call the operation using the S3Object property.

For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource Based Policies in the Amazon Rekognition Developer Guide.

  • Bytes (bytes) --

    Blob of image bytes up to 5 MBs.

  • S3Object (dict) --

    Identifies an S3 object as the image source.

    • 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 MaxResults:

integer

param MaxResults:

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.

type MinConfidence:

float

param MinConfidence:

Specifies the minimum confidence level for the labels to return. Amazon Rekognition doesn't return any labels with a confidence lower than this specified value. If you specify a value of 0, all labels are return, regardless of the default thresholds that the model version applies.

rtype:

dict

returns:

Response Syntax

{
    'CustomLabels': [
        {
            'Name': 'string',
            'Confidence': ...,
            'Geometry': {
                'BoundingBox': {
                    'Width': ...,
                    'Height': ...,
                    'Left': ...,
                    'Top': ...
                },
                'Polygon': [
                    {
                        'X': ...,
                        'Y': ...
                    },
                ]
            }
        },
    ]
}

Response Structure

  • (dict) --

    • CustomLabels (list) --

      An array of custom labels detected in the input image.

      • (dict) --

        A custom label detected in an image by a call to DetectCustomLabels.

        • Name (string) --

          The name of the custom label.

        • Confidence (float) --

          The confidence that the model has in the detection of the custom label. The range is 0-100. A higher value indicates a higher confidence.

        • Geometry (dict) --

          The location of the detected object on the image that corresponds to the custom label. Includes an axis aligned coarse bounding box surrounding the object and a finer grain polygon for more accurate spatial information.

          • BoundingBox (dict) --

            An axis-aligned coarse representation of the detected item's location on the image.

            • Width (float) --

              Width of the bounding box as a ratio of the overall image width.

            • Height (float) --

              Height of the bounding box as a ratio of the overall image height.

            • Left (float) --

              Left coordinate of the bounding box as a ratio of overall image width.

            • Top (float) --

              Top coordinate of the bounding box as a ratio of overall image height.

          • Polygon (list) --

            Within the bounding box, a fine-grained polygon around the detected item.

            • (dict) --

              The X and Y coordinates of a point on an image. The X and Y values returned are ratios of the overall image size. For example, if the input image is 700x200 and the operation returns X=0.5 and Y=0.25, then the point is at the (350,50) pixel coordinate on the image.

              An array of Point objects, Polygon, is returned by DetectText and by DetectCustomLabels. Polygon represents a fine-grained polygon around a detected item. For more information, see Geometry in the Amazon Rekognition Developer Guide.

              • X (float) --

                The value of the X coordinate for a point on a Polygon.

              • Y (float) --

                The value of the Y coordinate for a point on a Polygon.

DescribeProjectVersions (new) Link ¶

Lists and describes the models in an Amazon Rekognition Custom Labels project. You can specify up to 10 model versions in ProjectVersionArns. If you don't specify a value, descriptions for all models are returned.

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

See also: AWS API Documentation

Request Syntax

client.describe_project_versions(
    ProjectArn='string',
    VersionNames=[
        'string',
    ],
    NextToken='string',
    MaxResults=123
)
type ProjectArn:

string

param ProjectArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the project that contains the models you want to describe.

type VersionNames:

list

param VersionNames:

A list of model version names that you want to describe. You can add up to 10 model version names to the list. If you don't specify a value, all model descriptions are returned.

  • (string) --

type NextToken:

string

param NextToken:

If the previous response was incomplete (because there is more results to retrieve), Amazon Rekognition Custom Labels returns a pagination token in the response. You can use this pagination token to retrieve the next set of results.

type MaxResults:

integer

param MaxResults:

The maximum number of results to return per paginated call. The largest value you can specify is 100. If you specify a value greater than 100, a ValidationException error occurs. The default value is 100.

rtype:

dict

returns:

Response Syntax

{
    'ProjectVersionDescriptions': [
        {
            'ProjectVersionArn': 'string',
            'CreationTimestamp': datetime(2015, 1, 1),
            'MinInferenceUnits': 123,
            'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING',
            'StatusMessage': 'string',
            'BillableTrainingTimeInSeconds': 123,
            'TrainingEndTimestamp': datetime(2015, 1, 1),
            'OutputConfig': {
                'S3Bucket': 'string',
                'S3KeyPrefix': 'string'
            },
            'TrainingDataResult': {
                'Input': {
                    'Assets': [
                        {
                            'GroundTruthManifest': {
                                'S3Object': {
                                    'Bucket': 'string',
                                    'Name': 'string',
                                    'Version': 'string'
                                }
                            }
                        },
                    ]
                },
                'Output': {
                    'Assets': [
                        {
                            'GroundTruthManifest': {
                                'S3Object': {
                                    'Bucket': 'string',
                                    'Name': 'string',
                                    'Version': 'string'
                                }
                            }
                        },
                    ]
                }
            },
            'TestingDataResult': {
                'Input': {
                    'Assets': [
                        {
                            'GroundTruthManifest': {
                                'S3Object': {
                                    'Bucket': 'string',
                                    'Name': 'string',
                                    'Version': 'string'
                                }
                            }
                        },
                    ],
                    'AutoCreate': True|False
                },
                'Output': {
                    'Assets': [
                        {
                            'GroundTruthManifest': {
                                'S3Object': {
                                    'Bucket': 'string',
                                    'Name': 'string',
                                    'Version': 'string'
                                }
                            }
                        },
                    ],
                    'AutoCreate': True|False
                }
            },
            'EvaluationResult': {
                'F1Score': ...,
                'Summary': {
                    'S3Object': {
                        'Bucket': 'string',
                        'Name': 'string',
                        'Version': 'string'
                    }
                }
            }
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • ProjectVersionDescriptions (list) --

      A list of model descriptions. The list is sorted by the creation date and time of the model versions, latest to earliest.

      • (dict) --

        The description of a version of a model.

        • ProjectVersionArn (string) --

          The Amazon Resource Name (ARN) of the model version.

        • CreationTimestamp (datetime) --

          The Unix datetime for the date and time that training started.

        • MinInferenceUnits (integer) --

          The minimum number of inference units used by the model. For more information, see StartProjectVersion.

        • Status (string) --

          The current status of the model version.

        • StatusMessage (string) --

          A descriptive message for an error or warning that occurred.

        • BillableTrainingTimeInSeconds (integer) --

          The duration, in seconds, that the model version has been billed for training. This value is only returned if the model version has been successfully trained.

        • TrainingEndTimestamp (datetime) --

          The Unix date and time that training of the model ended.

        • OutputConfig (dict) --

          The location where training results are saved.

          • S3Bucket (string) --

            The S3 bucket where training output is placed.

          • S3KeyPrefix (string) --

            The prefix applied to the training output files.

        • TrainingDataResult (dict) --

          The manifest file that represents the training results.

          • Input (dict) --

            The training assets that you supplied for training.

            • Assets (list) --

              A Sagemaker GroundTruth manifest file that contains the training images (assets).

              • (dict) --

                Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

                • GroundTruthManifest (dict) --

                  The S3 bucket that contains the Ground Truth manifest file.

                  • S3Object (dict) --

                    Provides the S3 bucket name and object name.

                    The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

                    For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

          • Output (dict) --

            The images (assets) that were actually trained by Amazon Rekognition Custom Labels.

            • Assets (list) --

              A Sagemaker GroundTruth manifest file that contains the training images (assets).

              • (dict) --

                Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

                • GroundTruthManifest (dict) --

                  The S3 bucket that contains the Ground Truth manifest file.

                  • S3Object (dict) --

                    Provides the S3 bucket name and object name.

                    The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

                    For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

        • TestingDataResult (dict) --

          The manifest file that represents the testing results.

          • Input (dict) --

            The testing dataset that was supplied for training.

            • Assets (list) --

              The assets used for testing.

              • (dict) --

                Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

                • GroundTruthManifest (dict) --

                  The S3 bucket that contains the Ground Truth manifest file.

                  • S3Object (dict) --

                    Provides the S3 bucket name and object name.

                    The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

                    For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

            • AutoCreate (boolean) --

              If specified, Amazon Rekognition Custom Labels creates a testing dataset with an 80/20 split of the training dataset.

          • Output (dict) --

            The subset of the dataset that was actually tested. Some images (assets) might not be tested due to file formatting and other issues.

            • Assets (list) --

              The assets used for testing.

              • (dict) --

                Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

                • GroundTruthManifest (dict) --

                  The S3 bucket that contains the Ground Truth manifest file.

                  • S3Object (dict) --

                    Provides the S3 bucket name and object name.

                    The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

                    For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

            • AutoCreate (boolean) --

              If specified, Amazon Rekognition Custom Labels creates a testing dataset with an 80/20 split of the training dataset.

        • EvaluationResult (dict) --

          The training results. EvaluationResult is only returned if training is successful.

          • F1Score (float) --

            The F1 score for the evaluation of all labels. The F1 score metric evaluates the overall precision and recall performance of the model as a single value. A higher value indicates better precision and recall performance. A lower score indicates that precision, recall, or both are performing poorly.

          • Summary (dict) --

            The S3 bucket that contains the training summary.

            • S3Object (dict) --

              Provides the S3 bucket name and object name.

              The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

              For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

    • NextToken (string) --

      If the previous response was incomplete (because there is more results to retrieve), Amazon Rekognition Custom Labels returns a pagination token in the response. You can use this pagination token to retrieve the next set of results.

StopProjectVersion (new) Link ¶

Stops a running model. The operation might take a while to complete. To check the current status, call DescribeProjectVersions.

See also: AWS API Documentation

Request Syntax

client.stop_project_version(
    ProjectVersionArn='string'
)
type ProjectVersionArn:

string

param ProjectVersionArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the model version that you want to delete.

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

rtype:

dict

returns:

Response Syntax

{
    'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING'
}

Response Structure

  • (dict) --

    • Status (string) --

      The current status of the stop operation.

CreateProject (new) Link ¶

Creates a new Amazon Rekognition Custom Labels project. A project is a logical grouping of resources (images, Labels, models) and operations (training, evaluation and detection).

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

See also: AWS API Documentation

Request Syntax

client.create_project(
    ProjectName='string'
)
type ProjectName:

string

param ProjectName:

[REQUIRED]

The name of the project to create.

rtype:

dict

returns:

Response Syntax

{
    'ProjectArn': 'string'
}

Response Structure

  • (dict) --

    • ProjectArn (string) --

      The Amazon Resource Name (ARN) of the new project. You can use the ARN to configure IAM access to the project.

CreateProjectVersion (new) Link ¶

Creates a new version of a model and begins training. Models are managed as part of an Amazon Rekognition Custom Labels project. You can specify one training dataset and one testing dataset. The response from CreateProjectVersion is an Amazon Resource Name (ARN) for the version of the model.

Training takes a while to complete. You can get the current status by calling DescribeProjectVersions.

Once training has successfully completed, call DescribeProjectVersions to get the training results and evaluate the model.

After evaluating the model, you start the model by calling StartProjectVersion.

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

See also: AWS API Documentation

Request Syntax

client.create_project_version(
    ProjectArn='string',
    VersionName='string',
    OutputConfig={
        'S3Bucket': 'string',
        'S3KeyPrefix': 'string'
    },
    TrainingData={
        'Assets': [
            {
                'GroundTruthManifest': {
                    'S3Object': {
                        'Bucket': 'string',
                        'Name': 'string',
                        'Version': 'string'
                    }
                }
            },
        ]
    },
    TestingData={
        'Assets': [
            {
                'GroundTruthManifest': {
                    'S3Object': {
                        'Bucket': 'string',
                        'Name': 'string',
                        'Version': 'string'
                    }
                }
            },
        ],
        'AutoCreate': True|False
    }
)
type ProjectArn:

string

param ProjectArn:

[REQUIRED]

The ARN of the Amazon Rekognition Custom Labels project that manages the model that you want to train.

type VersionName:

string

param VersionName:

[REQUIRED]

A name for the version of the model. This value must be unique.

type OutputConfig:

dict

param OutputConfig:

[REQUIRED]

The Amazon S3 location to store the results of training.

  • S3Bucket (string) --

    The S3 bucket where training output is placed.

  • S3KeyPrefix (string) --

    The prefix applied to the training output files.

type TrainingData:

dict

param TrainingData:

[REQUIRED]

The dataset to use for training.

  • Assets (list) --

    A Sagemaker GroundTruth manifest file that contains the training images (assets).

    • (dict) --

      Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

      • GroundTruthManifest (dict) --

        The S3 bucket that contains the Ground Truth manifest file.

        • S3Object (dict) --

          Provides the S3 bucket name and object name.

          The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

          For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

          • 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 TestingData:

dict

param TestingData:

[REQUIRED]

The dataset to use for testing.

  • Assets (list) --

    The assets used for testing.

    • (dict) --

      Assets are the images that you use to train and evaluate a model version. Assets are referenced by Sagemaker GroundTruth manifest files.

      • GroundTruthManifest (dict) --

        The S3 bucket that contains the Ground Truth manifest file.

        • S3Object (dict) --

          Provides the S3 bucket name and object name.

          The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.

          For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see Resource-Based Policies in the Amazon Rekognition Developer Guide.

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

  • AutoCreate (boolean) --

    If specified, Amazon Rekognition Custom Labels creates a testing dataset with an 80/20 split of the training dataset.

rtype:

dict

returns:

Response Syntax

{
    'ProjectVersionArn': 'string'
}

Response Structure

  • (dict) --

    • ProjectVersionArn (string) --

      The ARN of the model version that was created. Use DescribeProjectVersion to get the current status of the training operation.

StartProjectVersion (new) Link ¶

Starts the running of the version of a model. Starting a model takes a while to complete. To check the current state of the model, use DescribeProjectVersions.

Once the model is running, you can detect custom labels in new images by calling DetectCustomLabels.

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

See also: AWS API Documentation

Request Syntax

client.start_project_version(
    ProjectVersionArn='string',
    MinInferenceUnits=123
)
type ProjectVersionArn:

string

param ProjectVersionArn:

[REQUIRED]

The Amazon Resource Name(ARN) of the model version that you want to start.

type MinInferenceUnits:

integer

param MinInferenceUnits:

[REQUIRED]

The minimum number of inference units to use. A single inference unit represents 1 hour of processing and can support up to 5 Transaction Pers Second (TPS). Use a higher number to increase the TPS throughput of your model. You are charged for the number of inference units that you use.

rtype:

dict

returns:

Response Syntax

{
    'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING'
}

Response Structure

  • (dict) --

    • Status (string) --

      The current running status of the model.

DetectModerationLabels (updated) Link ¶
Changes (request, response)
Request
{'HumanLoopConfig': {'DataAttributes': {'ContentClassifiers': ['FreeOfPersonallyIdentifiableInformation '
                                                               '| '
                                                               'FreeOfAdultContent']},
                     'FlowDefinitionArn': 'string',
                     'HumanLoopName': 'string'}}
Response
{'HumanLoopActivationOutput': {'HumanLoopActivationConditionsEvaluationResults': 'string',
                               'HumanLoopActivationReasons': ['string'],
                               'HumanLoopArn': 'string'}}

Detects unsafe content in a specified JPEG or PNG format image. Use DetectModerationLabels to moderate images depending on your requirements. For example, you might want to filter images that contain nudity, but not images containing suggestive content.

To filter images, use the labels returned by DetectModerationLabels to determine which types of content are appropriate.

For information about moderation labels, see Detecting Unsafe Content in the Amazon Rekognition Developer Guide.

You pass the input image either 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.

See also: AWS API Documentation

Request Syntax

client.detect_moderation_labels(
    Image={
        'Bytes': b'bytes',
        'S3Object': {
            'Bucket': 'string',
            'Name': 'string',
            'Version': 'string'
        }
    },
    MinConfidence=...,
    HumanLoopConfig={
        'HumanLoopName': 'string',
        'FlowDefinitionArn': 'string',
        'DataAttributes': {
            'ContentClassifiers': [
                'FreeOfPersonallyIdentifiableInformation'|'FreeOfAdultContent',
            ]
        }
    }
)
type Image:

dict

param Image:

[REQUIRED]

The input image as base64-encoded bytes or an S3 object. If you use the AWS CLI to call Amazon Rekognition operations, passing base64-encoded image bytes is not supported.

If you are using an AWS SDK to call Amazon Rekognition, you might not need to base64-encode image bytes passed using the Bytes field. For more information, see Images in the Amazon Rekognition developer guide.

  • Bytes (bytes) --

    Blob of image bytes up to 5 MBs.

  • S3Object (dict) --

    Identifies an S3 object as the image source.

    • 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 MinConfidence:

float

param MinConfidence:

Specifies the minimum confidence level for the labels to return. Amazon Rekognition doesn't return any labels with a confidence level lower than this specified value.

If you don't specify MinConfidence, the operation returns labels with confidence values greater than or equal to 50 percent.

type HumanLoopConfig:

dict

param HumanLoopConfig:

Sets up the configuration for human evaluation, including the FlowDefinition the image will be sent to.

  • HumanLoopName (string) -- [REQUIRED]

    The name of the human review used for this image. This should be kept unique within a region.

  • FlowDefinitionArn (string) -- [REQUIRED]

    The Amazon Resource Name (ARN) of the flow definition.

  • DataAttributes (dict) --

    Sets attributes of the input data.

    • ContentClassifiers (list) --

      Sets whether the input image is free of personally identifiable information.

      • (string) --

rtype:

dict

returns:

Response Syntax

{
    'ModerationLabels': [
        {
            'Confidence': ...,
            'Name': 'string',
            'ParentName': 'string'
        },
    ],
    'ModerationModelVersion': 'string',
    'HumanLoopActivationOutput': {
        'HumanLoopArn': 'string',
        'HumanLoopActivationReasons': [
            'string',
        ],
        'HumanLoopActivationConditionsEvaluationResults': 'string'
    }
}

Response Structure

  • (dict) --

    • ModerationLabels (list) --

      Array of detected Moderation labels and the time, in milliseconds from the start of the video, they were detected.

      • (dict) --

        Provides information about a single type of unsafe content found in an image or video. Each type of moderated content has a label within a hierarchical taxonomy. For more information, see Detecting Unsafe Content in the Amazon Rekognition Developer Guide.

        • Confidence (float) --

          Specifies the confidence that Amazon Rekognition has that the label has been correctly identified.

          If you don't specify the MinConfidence parameter in the call to DetectModerationLabels, the operation returns labels with a confidence value greater than or equal to 50 percent.

        • Name (string) --

          The label name for the type of unsafe content detected in the image.

        • ParentName (string) --

          The name for the parent label. Labels at the top level of the hierarchy have the parent label "".

    • ModerationModelVersion (string) --

      Version number of the moderation detection model that was used to detect unsafe content.

    • HumanLoopActivationOutput (dict) --

      Shows the results of the human in the loop evaluation.

      • HumanLoopArn (string) --

        The Amazon Resource Name (ARN) of the HumanLoop created.

      • HumanLoopActivationReasons (list) --

        Shows if and why human review was needed.

        • (string) --

      • HumanLoopActivationConditionsEvaluationResults (string) --

        Shows the result of condition evaluations, including those conditions which activated a human review.