2022/08/16 - Amazon Rekognition - 4 new4 updated api methods
Changes This release adds APIs which support copying an Amazon Rekognition Custom Labels model and managing project policies across AWS account.
Copies a version of an Amazon Rekognition Custom Labels model from a source project to a destination project. The source and destination projects can be in different AWS accounts but must be in the same AWS Region. You can't copy a model to another AWS service.
To copy a model version to a different AWS account, you need to create a resource-based policy known as a project policy. You attach the project policy to the source project by calling PutProjectPolicy. The project policy gives permission to copy the model version from a trusting AWS account to a trusted account.
For more information creating and attaching a project policy, see Attaching a project policy (SDK) in the Amazon Rekognition Custom Labels Developer Guide.
If you are copying a model version to a project in the same AWS account, you don't need to create a project policy.
Copying a model version takes a while to complete. To get the current status, call DescribeProjectVersions and check the value of Status in the ProjectVersionDescription object. The copy operation has finished when the value of Status is COPYING_COMPLETED.
See also: AWS API Documentation
Request Syntax
client.copy_project_version(
SourceProjectArn='string',
SourceProjectVersionArn='string',
DestinationProjectArn='string',
VersionName='string',
OutputConfig={
'S3Bucket': 'string',
'S3KeyPrefix': 'string'
},
Tags={
'string': 'string'
},
KmsKeyId='string'
)
string
[REQUIRED]
The ARN of the source project in the trusting AWS account.
string
[REQUIRED]
The ARN of the model version in the source project that you want to copy to a destination project.
string
[REQUIRED]
The ARN of the project in the trusted AWS account that you want to copy the model version to.
string
[REQUIRED]
A name for the version of the model that's copied to the destination project.
dict
[REQUIRED]
The S3 bucket and folder location where the training output for the source model version is placed.
S3Bucket (string) --
The S3 bucket where training output is placed.
S3KeyPrefix (string) --
The prefix applied to the training output files.
dict
The key-value tags to assign to the model version.
(string) --
(string) --
string
The identifier for your AWS Key Management Service key (AWS KMS key). You can supply the Amazon Resource Name (ARN) of your KMS key, the ID of your KMS key, an alias for your KMS key, or an alias ARN. The key is used to encrypt training results and manifest files written to the output Amazon S3 bucket ( OutputConfig).
If you choose to use your own KMS key, you need the following permissions on the KMS key.
kms:CreateGrant
kms:DescribeKey
kms:GenerateDataKey
kms:Decrypt
If you don't specify a value for KmsKeyId, images copied into the service are encrypted using a key that AWS owns and manages.
dict
Response Syntax
{
'ProjectVersionArn': 'string'
}
Response Structure
(dict) --
ProjectVersionArn (string) --
The ARN of the copied model version in the destination project.
Deletes an existing project policy.
To get a list of project policies attached to a project, call ListProjectPolicies. To attach a project policy to a project, call PutProjectPolicy.
See also: AWS API Documentation
Request Syntax
client.delete_project_policy(
ProjectArn='string',
PolicyName='string',
PolicyRevisionId='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the project that the project policy you want to delete is attached to.
string
[REQUIRED]
The name of the policy that you want to delete.
string
The ID of the project policy revision that you want to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Gets a list of the project policies attached to a project.
To attach a project policy to a project, call PutProjectPolicy. To remove a project policy from a project, call DeleteProjectPolicy.
See also: AWS API Documentation
Request Syntax
client.list_project_policies(
ProjectArn='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The ARN of the project for which you want to list the project policies.
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.
integer
The maximum number of results to return per paginated call. The largest value you can specify is 5. If you specify a value greater than 5, a ValidationException error occurs. The default value is 5.
dict
Response Syntax
{
'ProjectPolicies': [
{
'ProjectArn': 'string',
'PolicyName': 'string',
'PolicyRevisionId': 'string',
'PolicyDocument': 'string',
'CreationTimestamp': datetime(2015, 1, 1),
'LastUpdatedTimestamp': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
ProjectPolicies (list) --
A list of project policies attached to the project.
(dict) --
Describes a project policy in the response from ListProjectPolicies.
ProjectArn (string) --
The Amazon Resource Name (ARN) of the project to which the project policy is attached.
PolicyName (string) --
The name of the project policy.
PolicyRevisionId (string) --
The revision ID of the project policy.
PolicyDocument (string) --
The JSON document for the project policy.
CreationTimestamp (datetime) --
The Unix datetime for the creation of the project policy.
LastUpdatedTimestamp (datetime) --
The Unix datetime for when the project policy was last updated.
NextToken (string) --
If the response is truncated, Amazon Rekognition returns this token that you can use in the subsequent request to retrieve the next set of project policies.
Attaches a project policy to a Amazon Rekognition Custom Labels project in a trusting AWS account. A project policy specifies that a trusted AWS account can copy a model version from a trusting AWS account to a project in the trusted AWS account. To copy a model version you use the CopyProjectVersion operation.
For more information about the format of a project policy document, see Attaching a project policy (SDK) in the Amazon Rekognition Custom Labels Developer Guide.
The response from PutProjectPolicy is a revision ID for the project policy. You can attach multiple project policies to a project. You can also update an existing project policy by specifying the policy revision ID of the existing policy.
To remove a project policy from a project, call DeleteProjectPolicy. To get a list of project policies attached to a project, call ListProjectPolicies.
You copy a model version by calling CopyProjectVersion.
See also: AWS API Documentation
Request Syntax
client.put_project_policy(
ProjectArn='string',
PolicyName='string',
PolicyRevisionId='string',
PolicyDocument='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the project that the project policy is attached to.
string
[REQUIRED]
A name for the policy.
string
The revision ID for the Project Policy. Each time you modify a policy, Amazon Rekognition Custom Labels generates and assigns a new PolicyRevisionId and then deletes the previous version of the policy.
string
[REQUIRED]
A resource policy to add to the model. The policy is a JSON structure that contains one or more statements that define the policy. The policy must follow the IAM syntax. For more information about the contents of a JSON policy document, see IAM JSON policy reference.
dict
Response Syntax
{
'PolicyRevisionId': 'string'
}
Response Structure
(dict) --
PolicyRevisionId (string) --
The ID of the project policy.
{'Status': {'COPYING_COMPLETED', 'COPYING_IN_PROGRESS', 'COPYING_FAILED'}}
Deletes an Amazon Rekognition Custom Labels model.
You can't delete a model if it is running or if it is training. To check the status of a model, use the Status field returned from DescribeProjectVersions. To stop a running model call StopProjectVersion. If the model is training, wait until it finishes.
This operation requires permissions to perform the rekognition:DeleteProjectVersion action.
See also: AWS API Documentation
Request Syntax
client.delete_project_version(
ProjectVersionArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the model version that you want to delete.
dict
Response Syntax
{
'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING'|'COPYING_IN_PROGRESS'|'COPYING_COMPLETED'|'COPYING_FAILED'
}
Response Structure
(dict) --
Status (string) --
The status of the deletion operation.
{'ProjectVersionDescriptions': {'SourceProjectVersionArn': 'string',
'Status': {'COPYING_COMPLETED',
'COPYING_FAILED',
'COPYING_IN_PROGRESS'}}}
Lists and describes the versions of a model 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 model versions in the project 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
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the project that contains the models you want to describe.
list
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. A version name is part of a model (ProjectVersion) ARN. For example, my-model.2020-01-21T09.10.15 is the version name in the following ARN. arn:aws:rekognition:us-east-1:123456789012:project/getting-started/version/my-model.2020-01-21T09.10.15/1234567890123.
(string) --
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.
integer
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.
dict
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'|'COPYING_IN_PROGRESS'|'COPYING_COMPLETED'|'COPYING_FAILED',
'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'
}
}
},
]
},
'Validation': {
'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
},
'Validation': {
'Assets': [
{
'GroundTruthManifest': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
}
},
]
}
},
'EvaluationResult': {
'F1Score': ...,
'Summary': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
}
},
'ManifestSummary': {
'S3Object': {
'Bucket': 'string',
'Name': 'string',
'Version': 'string'
}
},
'KmsKeyId': 'string',
'MaxInferenceUnits': 123,
'SourceProjectVersionArn': '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) --
A description of a version of an Amazon Rekognition Custom Labels 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 you were billed for a successful training of the model version. 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) --
Contains information about 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 can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
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 can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
Validation (dict) --
The location of the data validation manifest. The data validation manifest is created for the training dataset during model training.
Assets (list) --
The assets that comprise the validation data.
(dict) --
Assets are the images that you use to train and evaluate a model version. Assets can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
TestingDataResult (dict) --
Contains information about 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 can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
AutoCreate (boolean) --
If specified, Amazon Rekognition Custom Labels temporarily splits the training dataset (80%) to create a test dataset (20%) for the training job. After training completes, the test dataset is not stored and the training dataset reverts to its previous size.
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 can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
AutoCreate (boolean) --
If specified, Amazon Rekognition Custom Labels temporarily splits the training dataset (80%) to create a test dataset (20%) for the training job. After training completes, the test dataset is not stored and the training dataset reverts to its previous size.
Validation (dict) --
The location of the data validation manifest. The data validation manifest is created for the test dataset during model training.
Assets (list) --
The assets that comprise the validation data.
(dict) --
Assets are the images that you use to train and evaluate a model version. Assets can also contain validation information that you use to debug a failed model training.
GroundTruthManifest (dict) --
The S3 bucket that contains an Amazon Sagemaker Ground Truth format 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 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.
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 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.
ManifestSummary (dict) --
The location of the summary manifest. The summary manifest provides aggregate data validation results for the training and test datasets.
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.
KmsKeyId (string) --
The identifer for the AWS Key Management Service key (AWS KMS key) that was used to encrypt the model during training.
MaxInferenceUnits (integer) --
The maximum number of inference units Amazon Rekognition Custom Labels uses to auto-scale the model. For more information, see StartProjectVersion.
SourceProjectVersionArn (string) --
If the model version was copied from a different project, SourceProjectVersionArn contains the ARN of the source model 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.
{'Status': {'COPYING_COMPLETED', 'COPYING_IN_PROGRESS', 'COPYING_FAILED'}}
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.
For more information, see Running a trained Amazon Rekognition Custom Labels model in the Amazon Rekognition Custom Labels Guide.
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,
MaxInferenceUnits=123
)
string
[REQUIRED]
The Amazon Resource Name(ARN) of the model version that you want to start.
integer
[REQUIRED]
The minimum number of inference units to use. A single inference unit represents 1 hour of processing.
For information about the number of transactions per second (TPS) that an inference unit can support, see Running a trained Amazon Rekognition Custom Labels model in the Amazon Rekognition Custom Labels Guide.
Use a higher number to increase the TPS throughput of your model. You are charged for the number of inference units that you use.
integer
The maximum number of inference units to use for auto-scaling the model. If you don't specify a value, Amazon Rekognition Custom Labels doesn't auto-scale the model.
dict
Response Syntax
{
'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING'|'COPYING_IN_PROGRESS'|'COPYING_COMPLETED'|'COPYING_FAILED'
}
Response Structure
(dict) --
Status (string) --
The current running status of the model.
{'Status': {'COPYING_COMPLETED', 'COPYING_IN_PROGRESS', 'COPYING_FAILED'}}
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'
)
string
[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.
dict
Response Syntax
{
'Status': 'TRAINING_IN_PROGRESS'|'TRAINING_COMPLETED'|'TRAINING_FAILED'|'STARTING'|'RUNNING'|'FAILED'|'STOPPING'|'STOPPED'|'DELETING'|'COPYING_IN_PROGRESS'|'COPYING_COMPLETED'|'COPYING_FAILED'
}
Response Structure
(dict) --
Status (string) --
The current status of the stop operation.