Getting started

This section walks you through the installation and initialization process of SuperAnnotate's Python SDK.

Installation

SuperAnnotate Python SDK is available on PyPI. Use the following command on your terminal to install our SDK.

pip install superannotate

The latest version supports Python 3.10+ and was tested under Linux and Windows (Anaconda) platforms.

You need to install the ffmpeg package for certain video-related functions to work. It can be installed on Ubuntu with the following command:

sudo apt-get install ffmpeg

To use the consensus functions on Windows and Mac platforms, you might also need to install the shapely package beforehand. The package works well only under the Anaconda distribution with:

conda install shapely

Initialization and authorization

To use the SDK, authenticate with a SuperAnnotate API key. You can provide the API key through the SA_TOKEN environment variable, the CLI, the token argument, or a configuration file. See API keys for information about creating and managing API keys.

SAClient can be used without arguments

Without arguments

from superannotate import SAClient
sa_client = SAClient()

Method 1: SA_TOKEN is defined as an environment variable.

Method 2: Generate a default location (~/.superannotate/config.ini) config file. CLI init should be used:

superannotatecli init --token <token>
                      [--logging_level <NOTSET/INFO/DEBUG/WARNING/ERROR/CRITICAL (Default=INFO)>]
                      [--logging_path <Default=/Users/username/.superannotate/logs>]

With arguments

Method 1: Use the token as an argument

from superannotate import SAClient
SAClient(token="<token>")

Method 2: Create a custom config file

from superannotate import SAClient
sa_client = SAClient(config_path="~/.superannotate/config.ini")

Custom config.ini example:

[DEFAULT]
SA_TOKEN = <token>
SA_TEAM_ID = <team ID>
LOGGING_LEVEL = DEBUG
LOGGING_PATH = /Users/username/data/superannotate_logs

Using a Personal API Key as a Contributor

Contributors can authenticate the SDK with their own Personal API key. When they do, the SDK acts as that contributor: every call is checked against the same role and permissions that apply to them in the SuperAnnotate UI. A Personal API key provides access within the team where it was created.

Project access

What a contributor can do in a project depends on their role in that project.

• Project Admin – A Project Admin can use the SDK functions that match what they can do in the UI for that project, such as managing folders, items, annotations, categories, and project settings. Project Admins cannot delete a project or remove other Project Admins from it.
• Project permissions – Some functions also need a project permission. For example, a Project Admin with the Download permission can use the export functions (prepare_export, get_exports, download_export, delete_exports). Without that permission, these calls are refused. Upload works the same way (for example attach_items, generate_items, and the upload_* functions), as does Delete (for example delete_folders and delete_items).
• Annotator and QA – Annotators and QAs do their work in the editor, so most SDK functions are not available to these roles.

A contributor can hold different roles and permissions in different projects, so the same function may work in one project and not in another.

Visibility

Contributors only see what they are assigned to:

• search_projects and list_projects return only the projects the contributor is assigned to.
• Folder and item functions return only the folders and items the contributor is assigned to within those projects.
• A request for a project the contributor is not assigned to fails as if the project does not exist.

Team-level functions

Team-level functions follow the contributor's team permissions in the UI. Each function works only if the contributor has the matching permission, for example Remove Contributors from team permission from the UI should be enabled for the user to be able to use: SAClient.remove_users(users)

Example

from superannotate import SAClient

sa_client = SAClient(token="<CONTRIBUTOR_PERSONAL_API_KEY>")

# Returns only the projects this contributor is assigned to
projects = sa_client.list_projects()

Authenticate with an Organization API key

Use SAORGClient to authenticate the SDK at the organization level. SAORGClient accepts an Organization API key and provides access to organization-level operations and teams within that organization.

from superannotate import SAORGClient
org_client = SAORGClient(token="<Organization API key>")

You can also initialize SAORGClient without arguments. In this case, the SDK checks the SA_TOKEN environment variable or the default ~/.superannotate/config.ini configuration file.

from superannotate import SAORGClient
org_client = SAORGClient()

You can also provide a custom configuration file:

org_client = SAORGClient(
    config_path="~/.superannotate/config.ini"
)

The configuration file uses the same SA_TOKEN key:

[DEFAULT]
SA_TOKEN = <Organization API key>

SA_TEAM_ID = <Team ID>
LOGGING_LEVEL = INFO
LOGGING_PATH = /Users/username/data/superannotate_logs

SAORGClient requires an Organization API key. Team and Personal API keys cannot be used to initialize an organization client.

Class SAClient

Create the SAClient instance to authorize SDK in a team scope. If no argument is provided, the SA_TOKEN environmental variable will be automatically checked, or $HOME/.superannotate/config.ini will be used.

# To instantiate SAClient using the team token:

team_1 = SAClient(
    token = "48c828b33e1a2a92fcdfccd54ecfebde1a1b787c741dd34935fe6c00430d80e78156c181c6e79759t=12759"
)

# To instantiate SAClient using the path to the config file that contains the team token:
team_1 = SAClient(config_path = "~/.superannotate/config.ini")

# No arguments:

team_1 = SAClient()

To get the name of the team you've instantiated the instance for:

team_1.get_team_metadata()['name']

To create an SAClient instance for another team in parallel (using another config.ini file/token):

team_2 = SAClient(config_path = "~/.superannotate/2_config.ini")

To get the name of the other team you've instantiated an SAClient for:

team_2.get_team_metadata()['name']

Class SAORGClient

Create an SAORGClient instance to authorize the SDK in an organization scope. An Organization API key allows you to perform organization-level operations and access multiple teams without creating a separate authenticated client for each team.

from superannotate import SAORGClient
org_client = SAORGClient(token="<Organization API key>")

SAORGClient can be used for organization-level operations such as managing teams, Team API keys, integrations, and team permissions.

To perform team-level SDK operations, create a team-scoped SAClient by calling get_team_client().

Get a team client

Use get_team_client() to create a team-scoped SAClient using the Organization API key.

team_client = org_client.get_team_client(team_id=12345)

The returned client is a standard SAClient and provides access to the full team-level SDK functionality.

team_client = org_client.get_team_client(team_id=12345)

team_client.list_projects(
    name__contains="My Project"
)

List teams

Use list_teams() to retrieve the teams that belong to the authenticated organization.

teams = org_client.list_teams()

If the organization has no teams, the method returns an empty list.