2024/01/16 - Amazon Rekognition - 4 updated api methods
Changes This release adds ContentType and TaxonomyLevel attributes to DetectModerationLabels and GetMediaAnalysisJob API responses.
{'ContentTypes': [{'Confidence': 'float', 'Name': 'string'}],
'ModerationLabels': {'TaxonomyLevel': 'integer'}}
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.
You can specify an adapter to use when retrieving label predictions by providing a ProjectVersionArn to the ProjectVersion argument.
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',
]
}
},
ProjectVersion='string'
)
dict
[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. Note that the maximum image size you can pass to DetectCustomLabels is 4MB.
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.
float
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.
dict
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. You can create a flow definition by using the Amazon Sagemaker CreateFlowDefinition Operation.
DataAttributes (dict) --
Sets attributes of the input data.
ContentClassifiers (list) --
Sets whether the input image is free of personally identifiable information.
(string) --
string
Identifier for the custom adapter. Expects the ProjectVersionArn as a value. Use the CreateProject or CreateProjectVersion APIs to create a custom adapter.
dict
Response Syntax
{
'ModerationLabels': [
{
'Confidence': ...,
'Name': 'string',
'ParentName': 'string',
'TaxonomyLevel': 123
},
],
'ModerationModelVersion': 'string',
'HumanLoopActivationOutput': {
'HumanLoopArn': 'string',
'HumanLoopActivationReasons': [
'string',
],
'HumanLoopActivationConditionsEvaluationResults': 'string'
},
'ProjectVersion': 'string',
'ContentTypes': [
{
'Confidence': ...,
'Name': '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 inappropriate, unwanted, or offensive content found in an image or video. Each type of moderated content has a label within a hierarchical taxonomy. For more information, see Content moderation 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 "" .
TaxonomyLevel (integer) --
The level of the moderation label with regard to its taxonomy, from 1 to 3.
ModerationModelVersion (string) --
Version number of the base 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.
ProjectVersion (string) --
Identifier of the custom adapter that was used during inference. If during inference the adapter was EXPIRED, then the parameter will not be returned, indicating that a base moderation detection project version was used.
ContentTypes (list) --
A list of predicted results for the type of content an image contains. For example, the image content might be from animation, sports, or a video game.
(dict) --
Contains information regarding the confidence and name of a detected content type.
Confidence (float) --
The confidence level of the label given
Name (string) --
The name of the label
{'ModerationLabels': {'ModerationLabel': {'TaxonomyLevel': 'integer'}}}
Gets the inappropriate, unwanted, or offensive content analysis results for a Amazon Rekognition Video analysis started by StartContentModeration. For a list of moderation labels in Amazon Rekognition, see Using the image and video moderation APIs.
Amazon Rekognition Video inappropriate or offensive content detection in a stored video is an asynchronous operation. You start analysis by calling StartContentModeration which returns a job identifier ( JobId ). When analysis finishes, Amazon Rekognition Video publishes a completion status to the Amazon Simple Notification Service topic registered in the initial call to StartContentModeration . To get the results of the content analysis, first check that the status value published to the Amazon SNS topic is SUCCEEDED . If so, call GetContentModeration and pass the job identifier ( JobId ) from the initial call to StartContentModeration .
For more information, see Working with Stored Videos in the Amazon Rekognition Devlopers Guide.
GetContentModeration returns detected inappropriate, unwanted, or offensive content moderation labels, and the time they are detected, in an array, ModerationLabels , of ContentModerationDetection objects.
By default, the moderated labels are returned sorted by time, in milliseconds from the start of the video. You can also sort them by moderated label by specifying NAME for the SortBy input parameter.
Since video analysis can return a large number of results, use the MaxResults parameter to limit the number of labels returned in a single call to GetContentModeration . If there are more results than specified in MaxResults , the value of NextToken in the operation response contains a pagination token for getting the next set of results. To get the next page of results, call GetContentModeration and populate the NextToken request parameter with the value of NextToken returned from the previous call to GetContentModeration .
For more information, see moderating content in the Amazon Rekognition Developer Guide.
See also: AWS API Documentation
Request Syntax
client.get_content_moderation(
JobId='string',
MaxResults=123,
NextToken='string',
SortBy='NAME'|'TIMESTAMP',
AggregateBy='TIMESTAMPS'|'SEGMENTS'
)
string
[REQUIRED]
The identifier for the inappropriate, unwanted, or offensive content moderation job. Use JobId to identify the job in a subsequent call to GetContentModeration .
integer
Maximum number of results to return per paginated call. The largest value you can specify is 1000. If you specify a value greater than 1000, a maximum of 1000 results is returned. The default value is 1000.
string
If the previous response was incomplete (because there is more data to retrieve), Amazon Rekognition returns a pagination token in the response. You can use this pagination token to retrieve the next set of content moderation labels.
string
Sort to use for elements in the ModerationLabelDetections array. Use TIMESTAMP to sort array elements by the time labels are detected. Use NAME to alphabetically group elements for a label together. Within each label group, the array element are sorted by detection confidence. The default sort is by TIMESTAMP .
string
Defines how to aggregate results of the StartContentModeration request. Default aggregation option is TIMESTAMPS. SEGMENTS mode aggregates moderation labels over time.
dict
Response Syntax
{
'JobStatus': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED',
'StatusMessage': 'string',
'VideoMetadata': {
'Codec': 'string',
'DurationMillis': 123,
'Format': 'string',
'FrameRate': ...,
'FrameHeight': 123,
'FrameWidth': 123,
'ColorRange': 'FULL'|'LIMITED'
},
'ModerationLabels': [
{
'Timestamp': 123,
'ModerationLabel': {
'Confidence': ...,
'Name': 'string',
'ParentName': 'string',
'TaxonomyLevel': 123
},
'StartTimestampMillis': 123,
'EndTimestampMillis': 123,
'DurationMillis': 123
},
],
'NextToken': 'string',
'ModerationModelVersion': 'string',
'JobId': 'string',
'Video': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
'JobTag': 'string',
'GetRequestMetadata': {
'SortBy': 'NAME'|'TIMESTAMP',
'AggregateBy': 'TIMESTAMPS'|'SEGMENTS'
}
}
Response Structure
(dict) --
JobStatus (string) --
The current status of the content moderation analysis job.
StatusMessage (string) --
If the job fails, StatusMessage provides a descriptive error message.
VideoMetadata (dict) --
Information about a video that Amazon Rekognition analyzed. Videometadata is returned in every page of paginated responses from GetContentModeration .
Codec (string) --
Type of compression used in the analyzed video.
DurationMillis (integer) --
Length of the video in milliseconds.
Format (string) --
Format of the analyzed video. Possible values are MP4, MOV and AVI.
FrameRate (float) --
Number of frames per second in the video.
FrameHeight (integer) --
Vertical pixel dimension of the video.
FrameWidth (integer) --
Horizontal pixel dimension of the video.
ColorRange (string) --
A description of the range of luminance values in a video, either LIMITED (16 to 235) or FULL (0 to 255).
ModerationLabels (list) --
The detected inappropriate, unwanted, or offensive content moderation labels and the time(s) they were detected.
(dict) --
Information about an inappropriate, unwanted, or offensive content label detection in a stored video.
Timestamp (integer) --
Time, in milliseconds from the beginning of the video, that the content moderation label was detected. Note that Timestamp is not guaranteed to be accurate to the individual frame where the moderated content first appears.
ModerationLabel (dict) --
The content moderation label detected by in the stored video.
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 "" .
TaxonomyLevel (integer) --
The level of the moderation label with regard to its taxonomy, from 1 to 3.
StartTimestampMillis (integer) --
The time in milliseconds defining the start of the timeline segment containing a continuously detected moderation label.
EndTimestampMillis (integer) --
The time in milliseconds defining the end of the timeline segment containing a continuously detected moderation label.
DurationMillis (integer) --
The time duration of a segment in milliseconds, I.e. time elapsed from StartTimestampMillis to EndTimestampMillis.
NextToken (string) --
If the response is truncated, Amazon Rekognition Video returns this token that you can use in the subsequent request to retrieve the next set of content moderation labels.
ModerationModelVersion (string) --
Version number of the moderation detection model that was used to detect inappropriate, unwanted, or offensive content.
JobId (string) --
Job identifier for the content moderation operation for which you want to obtain results. The job identifer is returned by an initial call to StartContentModeration.
Video (dict) --
Video file stored in an Amazon S3 bucket. Amazon Rekognition video start operations such as StartLabelDetection use Video to specify a video for analysis. The supported file formats are .mp4, .mov and .avi.
S3Object (dict) --
The Amazon S3 bucket name and file name for the video.
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.
JobTag (string) --
A job identifier specified in the call to StartContentModeration and returned in the job completion notification sent to your Amazon Simple Notification Service topic.
GetRequestMetadata (dict) --
Information about the paramters used when getting a response. Includes information on aggregation and sorting methods.
SortBy (string) --
The sorting method chosen for a GetContentModeration request.
AggregateBy (string) --
The aggregation method chosen for a GetContentModeration request.
{'Results': {'ModelVersions': {'Moderation': 'string'}}}
Retrieves the results for a given media analysis job. Takes a JobId returned by StartMediaAnalysisJob.
See also: AWS API Documentation
Request Syntax
client.get_media_analysis_job(
JobId='string'
)
string
[REQUIRED]
Unique identifier for the media analysis job for which you want to retrieve results.
dict
Response Syntax
{
'JobId': 'string',
'JobName': 'string',
'OperationsConfig': {
'DetectModerationLabels': {
'MinConfidence': ...,
'ProjectVersion': 'string'
}
},
'Status': 'CREATED'|'QUEUED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED',
'FailureDetails': {
'Code': 'INTERNAL_ERROR'|'INVALID_S3_OBJECT'|'INVALID_MANIFEST'|'INVALID_OUTPUT_CONFIG'|'INVALID_KMS_KEY'|'ACCESS_DENIED'|'RESOURCE_NOT_FOUND'|'RESOURCE_NOT_READY'|'THROTTLED',
'Message': 'string'
},
'CreationTimestamp': datetime(2015, 1, 1),
'CompletionTimestamp': datetime(2015, 1, 1),
'Input': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
'OutputConfig': {
'S3Bucket': 'string',
'S3KeyPrefix': 'string'
},
'KmsKeyId': 'string',
'Results': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
},
'ModelVersions': {
'Moderation': 'string'
}
},
'ManifestSummary': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
}
}
Response Structure
(dict) --
JobId (string) --
The identifier for the media analysis job.
JobName (string) --
The name of the media analysis job.
OperationsConfig (dict) --
Operation configurations that were provided during job creation.
DetectModerationLabels (dict) --
Contains configuration options for a DetectModerationLabels job.
MinConfidence (float) --
Specifies the minimum confidence level for the moderation labels to return. Amazon Rekognition doesn't return any labels with a confidence level lower than this specified value.
ProjectVersion (string) --
Specifies the custom moderation model to be used during the label detection job. If not provided the pre-trained model is used.
Status (string) --
The current status of the media analysis job.
FailureDetails (dict) --
Details about the error that resulted in failure of the job.
Code (string) --
Error code for the failed job.
Message (string) --
Human readable error message.
CreationTimestamp (datetime) --
The Unix date and time when the job was started.
CompletionTimestamp (datetime) --
The Unix date and time when the job finished.
Input (dict) --
Reference to the input manifest that was provided in the job creation request.
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 How Amazon Rekognition works with IAM 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.
OutputConfig (dict) --
Output configuration that was provided in the creation request.
S3Bucket (string) --
Specifies the Amazon S3 bucket to contain the output of the media analysis job.
S3KeyPrefix (string) --
Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for storage.
KmsKeyId (string) --
KMS Key that was provided in the creation request.
Results (dict) --
Output manifest that contains prediction results.
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 How Amazon Rekognition works with IAM 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.
ModelVersions (dict) --
Information about the model versions for the features selected in a given job.
Moderation (string) --
The Moderation base model version.
ManifestSummary (dict) --
The summary manifest provides statistics on input manifest and errors identified in the input manifest.
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 How Amazon Rekognition works with IAM 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.
{'MediaAnalysisJobs': {'Results': {'ModelVersions': {'Moderation': 'string'}}}}
Returns a list of media analysis jobs. Results are sorted by CreationTimestamp in descending order.
See also: AWS API Documentation
Request Syntax
client.list_media_analysis_jobs(
NextToken='string',
MaxResults=123
)
string
Pagination token, if the previous response was incomplete.
integer
The maximum number of results to return per paginated call. The largest value user can specify is 100. If user specifies a value greater than 100, an InvalidParameterException error occurs. The default value is 100.
dict
Response Syntax
{
'NextToken': 'string',
'MediaAnalysisJobs': [
{
'JobId': 'string',
'JobName': 'string',
'OperationsConfig': {
'DetectModerationLabels': {
'MinConfidence': ...,
'ProjectVersion': 'string'
}
},
'Status': 'CREATED'|'QUEUED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED',
'FailureDetails': {
'Code': 'INTERNAL_ERROR'|'INVALID_S3_OBJECT'|'INVALID_MANIFEST'|'INVALID_OUTPUT_CONFIG'|'INVALID_KMS_KEY'|'ACCESS_DENIED'|'RESOURCE_NOT_FOUND'|'RESOURCE_NOT_READY'|'THROTTLED',
'Message': 'string'
},
'CreationTimestamp': datetime(2015, 1, 1),
'CompletionTimestamp': datetime(2015, 1, 1),
'Input': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
'OutputConfig': {
'S3Bucket': 'string',
'S3KeyPrefix': 'string'
},
'KmsKeyId': 'string',
'Results': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
},
'ModelVersions': {
'Moderation': 'string'
}
},
'ManifestSummary': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
}
},
]
}
Response Structure
(dict) --
NextToken (string) --
Pagination token, if the previous response was incomplete.
MediaAnalysisJobs (list) --
Contains a list of all media analysis jobs.
(dict) --
Description for a media analysis job.
JobId (string) --
The identifier for a media analysis job.
JobName (string) --
The name of a media analysis job.
OperationsConfig (dict) --
Operation configurations that were provided during job creation.
DetectModerationLabels (dict) --
Contains configuration options for a DetectModerationLabels job.
MinConfidence (float) --
Specifies the minimum confidence level for the moderation labels to return. Amazon Rekognition doesn't return any labels with a confidence level lower than this specified value.
ProjectVersion (string) --
Specifies the custom moderation model to be used during the label detection job. If not provided the pre-trained model is used.
Status (string) --
The status of the media analysis job being retrieved.
FailureDetails (dict) --
Details about the error that resulted in failure of the job.
Code (string) --
Error code for the failed job.
Message (string) --
Human readable error message.
CreationTimestamp (datetime) --
The Unix date and time when the job was started.
CompletionTimestamp (datetime) --
The Unix date and time when the job finished.
Input (dict) --
Reference to the input manifest that was provided in the job creation request.
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 How Amazon Rekognition works with IAM 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.
OutputConfig (dict) --
Output configuration that was provided in the creation request.
S3Bucket (string) --
Specifies the Amazon S3 bucket to contain the output of the media analysis job.
S3KeyPrefix (string) --
Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for storage.
KmsKeyId (string) --
KMS Key that was provided in the creation request.
Results (dict) --
Output manifest that contains prediction results.
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 How Amazon Rekognition works with IAM 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.
ModelVersions (dict) --
Information about the model versions for the features selected in a given job.
Moderation (string) --
The Moderation base model version.
ManifestSummary (dict) --
Provides statistics on input manifest and errors identified in the input manifest.
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 How Amazon Rekognition works with IAM 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.