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

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.