Uploading assets to the S3 bucket

The annotation tasks that you create are most likely going to require assets, such as images and videos. Before you get started creating those tasks, you need to make sure that your assets are stored somewhere that the platform can access.

You can either upload your assets to our infrastructure, or keep the assets on your infrastructure and generate pre-signed URLs to allow the platform to fetch them. Of course, you can also use URLs that point to publicly available assets on the internet.

Gather your Sama info


How to get your API key?

  • Go to the clients tab
  • Look for your client
  • Click on show API key

Project ID

How to get your Project ID?

  • Go to the projects page
  • Use the filters and search for the client you are working with (i.e., BDD)
  • Click on view
  • Choose the BDD project
  • Take the ID from the URL (i.e., app.sama.com/projects/12345)

Uploading your assets with the AWS CLI


You can also upload your assets directly and create tasks using the Sama CLI.

Using the AWS CLI will give you the best performance when uploading your assets. The AWS CLI does have Python 3 as a requirement.

Install Python 3

Installation instructions directly from Python

On macOS, make sure to run Install Certificates.command after the installation.

Install the AWS CLI

Installation instructions directly from Amazon

Configure sama-aws tool

Download sama-aws.py

Start a terminal.The configure command creates a sama profile and AWS CLI will fetch temporary credentials from https://app.sama.com using your API key. It will auto-renew the credentials every hour.

python3 sama-aws.py configure

Look for Assets S3 URL in the command output, you will need it later.

Test AWS CLI sama profile.

aws --profile sama sts get-caller-identity 
aws --profile sama s3 ls <Assets S3 URL>

Uploads assets

This command uploads the desired folder to your S3 dedicated prefix.

aws --profile sama s3 sync ./<folder_name> <Assets S3 URL>/<folder_name>



Alternatively, you can install CyberDuck (third-party software) and use the local client on your computer to upload your assets. For more information, talk to your Sama project manager.

Generating URLs to your assets

If you already have your assets hosted on your infrastructure, you can generate pre-signed URLs instead to save time and avoid having to upload them to the S3 bucket. By default, when your assets are referenced during task creation, the platform will access each asset and store a copy of it in the S3 bucket.