Table of contents

Custom Tags - Amazon Rekognition

The Custom Tags - Amazon Rekognition API allows you to build Projects to classify or detect custom objects in your content.

Model - Project

{
    "id": "5df434f8031fdd45f669e39b42f2221a",
    "name": "foo",
    "description": "my model",
    "arn": "an amazon resource number",
    "type": "detection",
    "created_at": "2019-12-14T01:03:52.454906Z",
    "updated_at": "2019-12-14T01:03:52.454906Z",
    "needs_training": false,
    "needs_labeling": false,
    "num_files": 10,
    "num_labeled_files": 8,
    "num_labels": 20,
    "num_project_versions": 2,
    "num_unlabeled_files": 2
}

• id - (string) The projects’s unique identifier
• name - (string) The name of the project
• description - (string) A brief description of the project
• arn - (string) The AWS ARN that identifies the project at AWS
• type - (string) The model’s type. One of classification, detection, or imported
• created_at - (string) The timestamp when the project was created or imported
• updated_at - (string) The timestamp when the project was last updated
• needs_training - (bool) Whether or not the project needs to be retrained. This will be true when new labels are added to the project, labels are added or removed to/from files, or files are removed from the project.
• needs_labeling - (bool) Whether or not any unlabeled images exist in the project. This will be true when at least one image in the project doesn’t have any labels applied to it.
• num_files - (int) The number of non-deleted files associated with the project.
• num_labels - (int) The number of labels associated with the project.
• num_labeled_files - (int) The number of files that have labels applied to them within the project.
• num_project_versions - (int) The number of project versions associated with the project.
• num_unlabeled_files - (int) The number of files that do not have labels applied to them within the project.

Model - ProjectInfo

{
    "project": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "foo",
        "description": "my model",
        "arn": "an amazon resource number",
        "type": "detection",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z",
        "needs_training": false,
        "needs_labeling": false
    },
    "groups": [
        "group1",
        "group2"
    ],
}

• project - Project - A Project model
• groups - []string - A list of group ids assigned to the project

Model - ExistingProject

{
    "name": "some name",
    "arn": "some amazon resource number"
}

• name - (string) The name of the project
• arn - (string) The Amazon Resource Number that uniquely identifies the project at AWS

Model - Label

{
    "id": "somelabelid",
    "project_id": "abc123",
    "name": "Blue Jay",
    "deleted": false,
    "num_files": 10,
    "num_instances": 20,
    "created_at": "2020-01-22T19:52:10.509479Z",
    "updated_at": "2020-01-22T19:52:10.509479Z"
}

• id - (string) The label’s unique identifier
• project_id - (string) The project identifier to which this label belongs
• name - (string) The name of the label
• deleted - (bool) Whether or not this label has been deleted
• num_files - (int) The number of distinct files this label has been applied to
• num_instances - (int) The number of distinct instances of this label
• created_at - (string) The timestamp of when this label was created
• updated_at - (string) The timestamp of when this label was last modified

Model - LabelInfo

{
    "label": {
        "id": "somelabelid",
        "project_id": "abc123",
        "name": "Blue Jay",
        "deleted": false,
        "created_at": "2020-01-22T19:52:10.509479Z",
        "updated_at": "2020-01-22T19:52:10.509479Z"
    }
}

• label - (Label) A label object

Model - File

{
    "id": "5e30b6461f16430821a56f3239b56326",
    "project_id": "p1234",
    "mime_type": "image/jpeg",
    "deleted": false,
    "created_at": "2020-01-28T22:31:35.035882Z",
    "original_width": 1080,
    "original_height": 1080,
    "large_width": 1000,
    "large_height": 1000,
    "small_width": 200,
    "small_height": 200
}

• id - (string) The file’s unique identifier
• project_id - (string) The project’s unique identifier to which this file belongs
• mime_type - (string) The mime type of the originally uploaded file
• deleted - (string) Whether or not this file has been deleted
• created_at - (string) The timestamp when this file was uploaded
• original_width - (int) The width of the originally uploaded image
• original_height - (int) The height of the originally uploaded image
• large_width - (int) The width of the large size image
• large_height - (int) The height of the large size image
• small_width - (int) The width of the small size image
• small_height - (int) The height of the small size image

Model - FileInfo

{
    "file": {
        "created_at": "2020-02-28T17:55:22.071366Z",
        "deleted": false,
        "filename": "f1.jpg",
        "id": "f1",
        "large_height": 600,
        "large_width": 800,
        "mime_type": "image/jpeg",
        "original_height": 600,
        "original_width": 800,
        "project_id": "p1234",
        "small_height": 600,
        "small_width": 800
    },
    "labels": [
        {
            "label": {
                "created_at": "2020-02-28T17:52:53.252489Z",
                "deleted": false,
                "id": "l1",
                "name": "Cat",
                "num_files": 2,
                "num_instances": 2,
                "project_id": "p1234",
                "updated_at": "2020-02-28T17:52:53.252489Z"
            },
            "label_instances": [
                {
                    "file_id": "f1",
                    "label_id": "l1",
                    "top": 0.15567766,
                    "left": 0.3922065,
                    "width": 0.284666,
                    "height": 0.2930403
                }
            ]
        },
        {
            "label": {
                "created_at": "2020-02-28T17:52:53.252489Z",
                "deleted": false,
                "id": "l2",
                "name": "Dog",
                "num_files": 1,
                "num_instances": 2,
                "project_id": "p1234",
                "updated_at": "2020-02-28T17:52:53.252489Z"
            },
            "label_instances": [
                {
                    "file_id": "f1",
                    "label_id": "l2",
                    "top": 0.15567766,
                    "left": 0.3922065,
                    "width": 0.284666,
                    "height": 0.2930403
                }
            ]
        }
    ]
}

• file - (File) A file model
• labels - ([]LabelInstanceInfo) A list of LabelInstanceInfo models which represent a list of labels applied to this model

Model - LabelInstance

A LabelInstance is an instance of a label as applied to a specific file. It can contain a bounding box depending on the project’s type.

{
    "label_id": "somelabelid",
    "file_id": "somefileid",
    "top": 0.15567766,
    "left": 0.3922065,
    "width": 0.284666,
    "height": 0.2930403
}

• label_id - (string) A label identifier
• file_id - (string) A file identifier
• top - (float) The top coordinate of the bounding box as a ratio of overall image height
• left - (float) The left coordinate of the bounding box as a ratio of overall image width
• width - (float) The width of the bounding box as a ratio of the overall image width
• height - (float) The height of the bounding box as a ratio of the overall image height

Model - LabelInstanceInfo

{
    "label_instances": [
        {
        "file_id": "f1",
        "label_id": "l1"
        }
    ],
    "label": {
        "id": "l1",
        "project_id": "p1234",
        "name": "Cat",
        "deleted": false,
        "num_files": 2,
        "num_instances": 2,
        "created_at": "2020-02-28T17:52:53.252489Z",
        "updated_at": "2020-02-28T17:52:53.252489Z"
    }
}

• label_instances - ([]LabelInstance) A list of label instances
• label - (Label) The label that is associated with the label_instances

Model - BulkResponseError

{
    "message": "some error message",
    "type": "an error category"
}

• message - (string) An error message
• type - (string) An error category. One of NotFound, Forbidden, or InternalServerError

Model - BulkLabelRead

{
    "error": {
        "message": "some error message",
        "type": "an error category"
    },
    "object": {
        "id": "somelabelid",
        "project_id": "abc123",
        "name": "Blue Jay",
        "deleted": false,
        "created_at": "2020-01-22T19:52:10.509479Z",
        "updated_at": "2020-01-22T19:52:10.509479Z"
    }
}

• error - (BulkResponseError) An error object. Will be omitted if an error did not occur
• object - (Label) A label object. Will be omitted if an error occured

Model - ProjectVersion

{
    "id": "pv1",
    "arn": "arn:aws:rekognition:us-west-2:913397769129:project/Arthur/version/v0/1575184617111",
    "project_id": "p1234",
    "name": "v0",
    "notes": "initial version",
    "active": true,
    "created_at": "2020-02-07T22:32:35.276407Z",
    "heartbeat": "2020-02-07T22:32:35.276407Z"
}

• id - (string) The project version’s unique identifier
• arn - (string) The ARN that uniquely identifies this model at AWS
• project_id - (string) The unique id of the project this version belongs to
• name - (string) The auto-generated name assigned to this version of the model
• notes - (string) The notes assigned to this model at creation time
• active - (bool) Whether or not this project version is the active version. Only one project version can be active at a time
• created_at - (string) The timestamp of when the project version was created
• heartbeat - (string) The last received heartbeat of the project version

Model - TrainingInfo

The TrainingInfo model returns some info from training the project version.

{
    "billable_training_time_seconds": 4089,
    "f1_score": 0.7576923370361328,
    "evaluation_results": {
        "AggregatedEvaluationResults": {
            "AveragePrecision": 0.7361307559327361,
            "AverageRecall": 0.8666666666666667,
            "F1Score": 0.7576923076923077,
            "Precision": 0.8190476190476191,
            "Recall": 0.7333333333333334
        },
        "EvaluationDetails": {
            "EvaluationEndTimestamp": "2019-12-01T07:26:05.467607",
            "Labels": [
                "Arthur",
                "Buster",
                "Francine"
            ],
            "NumberOfTestingImages": 14,
            "NumberOfTrainingImages": 52,
            "ProjectVersionArn": "arn:aws:rekognition:us-west-2:913397769129:project/Arthur/version/v0/1575184617111"
        },
        "LabelEvaluationResults": [
            {
                "Label": "Francine",
                "Metrics": {
                    "F1Score": 0.923076923076923,
                    "Precision": 0.8571428571428571,
                    "Recall": 1,
                    "Threshold": 0.80989
                },
                "NumberOfTestingImages": 14
            },
            {
                "Label": "Arthur",
                "Metrics": {
                    "F1Score": 0.7499999999999999,
                    "Precision": 1,
                    "Recall": 0.6,
                    "Threshold": 0.85915
                },
                "NumberOfTestingImages": 14
            },
            {
                "Label": "Buster",
                "Metrics": {
                    "F1Score": 0.6,
                    "Precision": 0.6,
                    "Recall": 0.6,
                    "Threshold": 0.88773
                },
                "NumberOfTestingImages": 14
            }
        ],
        "Version": 1
    }
}

• billable_training_time_seconds - (int) The amount of time (in seconds) that it took to train the model and that will be billed to the account
• f1_score - (float) The overall f1 score of the model
• evaluation_results.AggregatedEvaluationResults - Contains statistics on the overall performance of this version of the model
• evaluation_results.EvaluationDetails - Gives a summary of the training
• []evaluation_results.LabelEvaluationResults - Gives a breakdown of the training statistics for each label

Model - ProjectVersionInfo

{
    "project_version": {
        "id": "pv1",
        "arn": "arn:aws:rekognition:us-west-2:913397769129:project/Arthur/version/v0/1575184617111",
        "project_id": "p1234",
        "name": "v0",
        "notes": "initial version",
        "active": true,
        "created_at": "2020-02-07T22:32:35.276407Z",
        "heartbeat": "2020-02-07T22:32:35.276407Z"
    },
    "status": "STOPPED",
    "training_info": {
        "billable_training_time_seconds": 4089,
        "f1_score": 0.7576923370361328,
        "evaluation_results": {
            "AggregatedEvaluationResults": {
                "AveragePrecision": 0.7361307559327361,
                "AverageRecall": 0.8666666666666667,
                "F1Score": 0.7576923076923077,
                "Precision": 0.8190476190476191,
                "Recall": 0.7333333333333334
            },
            "EvaluationDetails": {
                "EvaluationEndTimestamp": "2019-12-01T07:26:05.467607",
                "Labels": [
                    "Arthur",
                    "Buster",
                    "Francine"
                ],
                "NumberOfTestingImages": 14,
                "NumberOfTrainingImages": 52,
                "ProjectVersionArn": "arn:aws:rekognition:us-west-2:913397769129:project/Arthur/version/v0/1575184617111"
            },
            "LabelEvaluationResults": [
                {
                    "Label": "Francine",
                    "Metrics": {
                        "F1Score": 0.923076923076923,
                        "Precision": 0.8571428571428571,
                        "Recall": 1,
                        "Threshold": 0.80989
                    },
                    "NumberOfTestingImages": 14
                },
                {
                    "Label": "Arthur",
                    "Metrics": {
                        "F1Score": 0.7499999999999999,
                        "Precision": 1,
                        "Recall": 0.6,
                        "Threshold": 0.85915
                    },
                    "NumberOfTestingImages": 14
                },
                {
                    "Label": "Buster",
                    "Metrics": {
                        "F1Score": 0.6,
                        "Precision": 0.6,
                        "Recall": 0.6,
                        "Threshold": 0.88773
                    },
                    "NumberOfTestingImages": 14
                }
            ],
            "Version": 1
        }
    }
}

• project_version - (ProjectVersion) A ProjectVersion model
• status - (string) The current state the model is in. One of TRAINING_IN_PROGRESS, TRAINING_COMPLETED, TRAINING_FAILED, STARTING, RUNNING, FAILED, STOPPING, STOPPED, DELETING
• training_info - (TrainingInfo) A TrainingInfo model that captures some of the results from training the model. Will only be present if the model was successfully trained

List Projects

GET /api/data/v3/customtags/amazonrek/projects?limit={limit}&page-token={page-token}

• limit - (int) Optional. Number of projects to return. Min: 1. Max: 1000. Default: 10.
• page-token - (string) Optional. The token to retrieve another page of results.

List Projects Response

{
    "projects": [
        {
            "project": {
                "id": "5df434f8031fdd45f669e39b42f2221a",
                "name": "foo",
                "description": "my model",
                "arn": "an amazon resource number",
                "type": "detection",
                "created_at": "2019-12-14T01:03:52.454906Z",
                "updated_at": "2019-12-14T01:03:52.454906Z",
                "needs_training": false,
                "needs_labeling": false
            },
            "groups": [
                "group1",
                "group2"
            ],
        }
        ...
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

• projects - []ProjectInfo A list of ProjectInfo objects.
• next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results.
• previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of results.

Create Project

POST /api/data/v3/customtags/amazonrek/projects
{
    "name": "My Cats Model",
    "description": "some description",
    "type": "detection",
}

• name - (string) Required. Human-readable name of the project
• description - (string) Required. Human-readable description of the project
• type - (string) Required. Either classification or detection

Create Project Response

Expect a 201 status code:

{
    "project": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "My Cats Model",
        "description": "some description",
        "arn": "an amazon resource number",
        "type": "detection",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z",
        "needs_training": false,
        "needs_labeling": false
    }
}

• project - Project - A Project model

Update a Project

Only the description field of a Project is mutable.

PATCH /api/data/v3/customtags/amazonrek/projects/{id}
{
    "description": "some new description",
}

• id - (string) Required. The unique identifier of the project
• description - (string) Required. Human-readable description of the project

Update Project Response

Expect a 200 status code:

{
    "project": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "My Cats Model",
        "description": "some new description",
        "arn": "an amazon resource number",
        "type": "detection",
        "created_at": "2019-12-12T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:09:17.123445Z",
        "needs_training": false,
        "needs_labeling": false
    }
}

• project - Project - A Project model

Import Project

POST /api/data/v3/customtags/amazonrek/projects/import
{
    "arn": "an amazon project arn",
}

• arn - (string) Required. An AWS Rekognition Custom Labels Project ARN. Must exist in AWS.

Import Project Response

Expect a 201 status code:

{
    "project": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "My Cats Model",
        "description": "some description",
        "arn": "an amazon project arn number",
        "type": "imported",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z",
        "needs_training": false,
        "needs_labeling": false
    }
}

• project - Project - A Project model

List Projects Available to Import

This endpoint will show you any projects that exist in AWS that haven’t been imported into Curio. This endopoint will 404 if project imports are disabled.

GET /api/data/v3/customtags/amazonrek/projects/import

• arn - (string) Required. An AWS Rekognition Custom Labels Project ARN. Must exist in AWS.

List Available Projects Response

Expect a 200 status code:

{
    "projects": [
        {
        "name": "Cats",
        "arn": "an amazon project arn number",
        },
        {
        "name": "Dogs",
        "arn": "another amazon project arn number",
        }
    ]
}

• projects - []ExistingProject - A list of ExistingProject models

Import Project Versions

Use this endpoint to pull in any project versions associated with a Project that were created after the project was originally imported. This endpoint will 404 if project imports are disabled.

POST /api/data/v3/customtags/amazonrek/projects/{id}/import-project-versions

• id - (string) Required. The Project’s unique identifier.

Import Project Versions Response

A successful response will return a 204 status code.

Read a Project

GET /api/data/v3/customtags/amazonrek/projects/{id}

• id - (string) Required. The unique identifier of the project

Read a Project Response

Expect a 200 status code:

{
    "project": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "My Cats Model",
        "description": "some description",
        "arn": "an amazon project arn number",
        "type": "imported",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z",
        "needs_training": false,
        "needs_labeling": false
    }
}

• project - Project - A Project model

Add User Groups to a Project

POST /api/data/v3/customtags/amazonrek/projects/{id}/groups
{
    "ids": ["group1", "group2", ..., "groupN"]
}

• id - (string) Required. The unique identifier of the project
• ids - ([]string) Required. The list of group identifiers to add to the project

Add User Groups Response

Expect a 204 status code.

Remove User Groups from a Project

DELETE /api/data/v3/customtags/amazonrek/projects/{id}/groups
{
    "ids": ["group1", "group2", ..., "groupN"]
}

• id - (string) Required. The unique identifier of the project
• ids - ([]string) Required. The list of group identifiers to remove from the project

Remove User Groups Response

Expect a 204 status code.

Replace User Groups on a Project

This action will add and remove user groups associated with a project. For example, if a project has group1 and group2 already added to it, and a replace is called with a list of groups (group1, group3), then group2 will be removed from the project and group3 will be added to the project.

PUT /api/data/v3/customtags/amazonrek/projects/{id}/groups
{
    "ids": ["group1", "group2", ..., "groupN"]
}

• id - (string) Required. The unique identifier of the project
• ids - ([]string) Required. The list of group identifiers to remove from the project

Replace User Groups Response

Expect a 204 status code.

Add one or more labels to a project

POST /api/data/v3/customtags/amazonrek/projects/{id}/labels
{
    "names": ["the first label name", "the second label name"]
}

• id - (string) Required. The unique identifier of the project
• names - ([]string) Required. The names of the label to create. Labels are case insensitive and must be unique per project

Add labels response

Expect a 201 status code plus the following response body:

{
    "labels": [
        {
            "id": "label1",
            "project_id": "abc123",
            "name": "the first label name",
            "deleted": false,
            "created_at": "2020-01-22T19:52:10.509479Z",
            "updated_at": "2020-01-22T19:52:10.509479Z"
        },
        {
            "id": "label2",
            "project_id": "abc123",
            "name": "the second label name",
            "deleted": false,
            "created_at": "2020-01-22T19:52:10.509479Z",
            "updated_at": "2020-01-22T19:52:10.509479Z"
        },
    ]
}

• labels - ([]Label) A list of Label objects

Remove a label from a project

DELETE /api/data/v3/customtags/amazonrek/labels/{id}

• id - (string) The unique identifier of the label

Remove label response

Expect a 204 response.

Update a label

PATCH /api/data/v3/customtags/amazonrek/labels/{id}
{
    "name": "the label name",
    "deleted": false
}

• id - (string) The unique identifier of the label
• name - (string) Optional. The name of the label to create. Labels are case insensitive and must be unique per project
• deleted - (string) Optional. Whether or not the label has been deleted. By setting this to false you can un-delete a previously deleted label

One of name or deleted must be specified in the request.

Label update response

Expect a 200 response code with an update Label model in the response body.

List labels that belong to a project

GET /api/data/v3/customtags/amazonkrek/projects/{project_id}/labels?deleted={deleted}&limit={limit}&page-token={page-token}

• project_id - (string) The project’s unique identifier
• deleted - (bool) Optional. Default: false. Returns only deleted or non-deleted labels
• limit - (int) Optional. Default: 10. Maximum: 1000. The number of labels to return per page
• page-token - (string) Optional. The token to retrieve another page of results

Labels list response

{
    "labels": [
        {
            "label": {
                "id": "somelabelid",
                "project_id": "abc123",
                "name": "Blue Jay",
                "deleted": false,
                "created_at": "2020-01-22T19:52:10.509479Z",
                "updated_at": "2020-01-22T19:52:10.509479Z"
            }
        }
        ...
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

• labels - ([]LabelInfo) a list of LabelInfo models
• next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results
• previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of results

Read one label

GET /api/data/v3/customtags/amazonrek/labels/{id}

• id - (string) The unique identifier of the label

Label read response

Expect a 200 response code with a Label model in the response body.

Read multiple labels

This endpoint allows you to read multiple labels in a single request.

POST /api/data/v3/customtags/amazonrek/labels/bulk/read
{
    "ids": ["id1", "id2", ... "idN"]
}

• ids - ([]string) Required. The list of label identifiers to retrieve

Label bulk read response

{
    "has_errors": false,
    "results": {
        "id1": {
            "error": {
                "message": "some error message",
                "type": "an error category"
            },
            "object": {
                "id": "id1",
                "project_id": "abc123",
                "name": "Blue Jay",
                "deleted": false,
                "created_at": "2020-01-22T19:52:10.509479Z",
                "updated_at": "2020-01-22T19:52:10.509479Z"
            }
        },
        "id2": {
            "error": {
                "message": "some error message",
                "type": "an error category"
            },
            "object": {
                "id": "id2",
                "project_id": "abc123",
                "name": "Robin",
                "deleted": false,
                "created_at": "2020-01-22T19:52:10.509479Z",
                "updated_at": "2020-01-22T19:52:10.509479Z"
            }
        }
    }
}

• has_errors - (bool) An indicator that one or more ids has an error
• results - (map[string]BulkLabelRead) A map of responses for each id in the request

Upload a file

POST /api/data/v3/customtags/amazonrek/projects/{id}/files

To upload a file, POST a multipart form requst to the above address. The file should be included in the file parameter. Files must be a minimum of 64 pixels wide by 64 pixels high, maximum of 4096 pixels wide by 4096 pixels tall, and the aspect ratio must not exceed a maximum of 4:1. Files must be in either JPEG or PNG format.

File upload response

Expect a 201 response with a File model in the body of the response

{
    "id": "5e30b6461f16430821a56f3239b56326",
    "project_id": "p1234",
    "mime_type": "image/jpeg",
    "deleted": false,
    "created_at": "2020-01-28T22:31:35.035882Z",
    "original_width": 1080,
    "original_height": 1080,
    "large_width": 1000,
    "large_height": 1000,
    "small_width": 200,
    "small_height": 200
}

Delete a file

DELETE /api/data/v3/customtags/amazonrek/files/{id}

• id - The unique identifier of the file

File delete response

Expect a 204 response.

Read a file

GET /api/data/v3/customtags/amazonrek/files/{id}

• id - The unique identifier of the file

File read response

Expect a 200 response with a FileInfo model in the body of the response.

{
    "file": {
        "created_at": "2020-02-28T17:55:22.071366Z",
        "deleted": false,
        "filename": "f1.jpg",
        "id": "f1",
        "large_height": 600,
        "large_width": 800,
        "mime_type": "image/jpeg",
        "original_height": 600,
        "original_width": 800,
        "project_id": "p1234",
        "small_height": 600,
        "small_width": 800
    },
    "labels": [
        {
            "label": {
                "created_at": "2020-02-28T17:52:53.252489Z",
                "deleted": false,
                "id": "l1",
                "name": "Cat",
                "num_files": 2,
                "num_instances": 2,
                "project_id": "p1234",
                "updated_at": "2020-02-28T17:52:53.252489Z"
            },
            "label_instances": [
                {
                    "file_id": "f1",
                    "label_id": "l1"
                }
            ]
        },
        {
            "label": {
                "created_at": "2020-02-28T17:52:53.252489Z",
                "deleted": false,
                "id": "l2",
                "name": "Dog",
                "num_files": 1,
                "num_instances": 2,
                "project_id": "p1234",
                "updated_at": "2020-02-28T17:52:53.252489Z"
            },
            "label_instances": [
                {
                    "file_id": "f1",
                    "label_id": "l2"
                },
                {
                    "file_id": "f1",
                    "label_id": "l2"
                }
            ]
        }
    ]
}

Download the file image or one of the thumbnails

GET /api/data/v3/customtags/amazonrek/files/{id}/{size}

• id - The id of the file
• size - One of original, large, or small

Download file response

Expect a 200 response with the correct Content-Type header (either image/jpeg or image/png depending on the original uploaded content type), and the binary image data in the body of the response.

List files belonging to a project

GET /api/data/v3/customtags/amazonrek/projects/{id}/files?limit={limit}&page-token={page-token}&unlabeled={unlabeled}&label_id={label_id}

• unlabeled - (bool) Optional. If not set, returns all non-deleted files. If set to true, only returns files that do not have any labels applied to them. If set to false, returns files that have one or more labels applied to them.
• label_id - (string) Optional. If set, only files with the specified label_id will be returned.
• limit - (int) Optional. Default: 10. Maximum: 1000. The number of labels to return per page
• page-token - (string) Optional. The token to retrieve another page of results

List files response

{
    "files": [
        {
            "file": {
                "id": "5e30b6461f16430821a56f3239b56326",
                "project_id": "p1234",
                "mime_type": "image/jpeg",
                "deleted": false,
                "created_at": "2020-01-28T22:31:35.035882Z",
                "original_width": 1080,
                "original_height": 1080,
                "large_width": 1000,
                "large_height": 1000,
                "small_width": 200,
                "small_height": 200
            },
            "labels": [
               {
                    "label_id": "somelabelid",
                    "file_id": "5e30b6461f16430821a56f3239b56326",
                    "top": 0.15567766,
                    "left": 0.3922065,
                    "width": 0.284666,
                    "height": 0.2930403,
                },
                ...
            ]
        }
        ...
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

• files - ([]FileInfo) a list of FileInfo models
• next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results
• previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of results

Search files belonging to a project

You can search files based on their original filename. The search looks for partial matches in a case-insensitive manner.

Example: You uploaded “foo.jpg” and “FOO.png” and then searched for “foo”. You would get back a set of results containing both files.

POST /api/data/v3/customtags/amazonrek/projects/{id}/files/search?limit={limit}&page-token={page-token}
{
    "query": "foo"
}

• query - (string) Required. The search string. Must be a minimum of two characters
• limit - (int) Optional. Default: 10. Maximum: 1000. The number of labels to return per page
• page-token - (string) Optional. The token to retrieve another page of results

Search files response

{
    "files": [
        {
            "file": {
                "id": "5e30b6461f16430821a56f3239b56326",
                "project_id": "p1234",
                "mime_type": "image/jpeg",
                "deleted": false,
                "created_at": "2020-01-28T22:31:35.035882Z",
                "original_width": 1080,
                "original_height": 1080,
                "large_width": 1000,
                "large_height": 1000,
                "small_width": 200,
                "small_height": 200
            },
            "labels": [
               {
                    "label_id": "somelabelid",
                    "file_id": "5e30b6461f16430821a56f3239b56326",
                    "top": 0.15567766,
                    "left": 0.3922065,
                    "width": 0.284666,
                    "height": 0.2930403,
                },
                ...
            ]
        }
        ...
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

• files - ([]FileInfo) a list of FileInfo models
• next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results
• previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of results

Replace labels on a file

This endpoint will allow you to replace labels on a file. All existing labels on the file are deleted and labels from the request will be added.

PUT /api/data/v3/customtags/amazonrek/files/{id}/label
{
    "labels": [
        {
            "label_id": "somelabelid",
            "top": 0.15567766,
            "left": 0.3922065,
            "width": 0.284666,
            "height": 0.2930403,
        },
        ...
    ]
}

• id - (string) The unique identifier of the file
• labels - []Object:
  • label_id - (string) Required. The id of the label
  • top - (float) Required if the project type is detection. If the project type is not detection, omit this key from the request. The top coordinate of the bounding box as a ratio of overall image height
  • left - (float) Required if the project type is detection. If the project type is not detection, omit this key from the request. The left coordinate of the bounding box as a ratio of overall image width
  • width - (float) Required if the project type is detection. If the project type is not detection, omit this key from the request. The width of the bounding box as a ratio of the overall image width
  • height - (float) Required if the project type is detection. If the project type is not detection, omit this key from the request. The height of the bounding box as a ratio of the overall image height

Replace labels response

Expect a 200 response with a FileInfo model in the body of the response.

{
    "file": {
        "id": "f1",
        "project_id": "p1234",
        "mime_type": "image/jpeg",
        "filename": "f1.jpg",
        "deleted": false,
        "created_at": "2020-02-28T17:55:22.071366Z",
        "original_width": 800,
        "original_height": 600,
        "large_width": 800,
        "large_height": 600,
        "small_width": 800,
        "small_height": 600
    },
    "labels": [
        {
            "label_instances": [
                {
                    "file_id": "f1",
                    "label_id": "l2"
                }
            ],
            "label": {
                "id": "l2",
                "project_id": "p1234",
                "name": "Dog",
                "deleted": false,
                "num_files": 1,
                "num_instances": 1,
                "created_at": "2020-02-28T17:52:53.252489Z",
                "updated_at": "2020-02-28T17:52:53.252489Z"
            }
        }
    ]
}

Create a project version

Creating a project version initiates the training of a model. This process can take several hours to complete and incurs cost.

POST /api/data/v3/customtags/amazonrek/projects/{id}/projectversions
{
    "notes": "some notes"
}

• id - (string) The unique identifier of the project for which you want to create a new project version
• notes - (string) A description of this version of the project. Perhaps you added new training data, a new label, etc.

Project version create response

A successful response will issue an HTTP 201 status code and a ProjectVersion model in the body of the response.

Reading a project version

GET /api/data/v3/customtags/amazonrek/projectversions/{id}

• id - (string) The project version unique identifier

Project version read response

A successful response will issue an HTTP 200 status code and a ProjectVersionInfo model in the response body.

List project versions for a project

GET /api/data/v3/customtags/amazonrek/projects/{id}/projectversions?limit={limit}&page-token={page-token}

• id - (string) The id of the project
• limit - (int) Optional. Default: 10. Maximum: 100. The number of project versions to return per page
• page-token - (string) Optional. The token to retrieve another page of results

Project version list response

{
    "project_versions": [
       {
            "project_version": {
                "id": "pv1",
                "arn": "arn:aws:rekognition:us-west-2:913397769129:project/Arthur/version/v0/1575184617111",
                "project_id": "p1234",
                "name": "v0",
                "notes": "initial version",
                "active": true,
                "created_at": "2020-02-07T22:32:35.276407Z",
                "heartbeat": "2020-02-07T22:32:35.276407Z"
            },
            "status": "STOPPED",
            "training_info": {
                "billable_training_time_seconds": 4089,
                "f1_score": 0.7576923370361328,
            }
        }
    ],
    "next_page": "",
    "previous_page": ""
}

• project_versions - ([]ProjectVersionInfo) An array of ProjectVersion models. Note that while this endpoint will return some of the training_info fields, it will not return the evaluation_results object even if it is available. Use the Project version read endpoint to get the detailed evaluation_results object for a project version.
• next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results.
• previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of results.

Activating a project version

Activating a project version approves that specific version of the project for use when analying your content.

POST /api/data/v3/customtags/amazonrek/projectversions/{id}/activate

• id - (string) The project version unique identifier

Activating a project version response

A successful response will issue an HTTP 204 status code and an empty response body.

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

© 2021 GrayMeta, Inc.