SuperAnnotate Python SDK

4.5.4 verified Fri May 01 auth: no python

Python SDK for the SuperAnnotate platform, enabling programmatic management of annotation projects, items, classes, exports, and team workflows. Current version 4.5.4, supports Python >=3.10, released approximately every 1-2 months.

pip install superannotate

Common errors

error AttributeError: module 'superannotate' has no attribute 'SAClient' ↓

cause Importing from superannotate before v4.0 where SAClient didn't exist, or incorrect import path.

fix

Run pip install --upgrade superannotate to get v4.x. Then use from superannotate import SAClient.

error ValueError: The api_token must be provided either as an argument or via the SA_API_TOKEN environment variable. ↓

cause Initializing SAClient without API token.

fix

Set SA_API_TOKEN environment variable or pass api_token='...' to SAClient constructor.

error pydantic.errors.PydanticUserError: Field name "project_name" shadows an attribute in parent model ↓

cause Using Pydantic v1 with SAClient >=4.5.3 which now uses Pydantic v2.

fix

Upgrade Pydantic to v2 (pip install pydantic>=2.0) or downgrade superannotate to 4.5.2.

Warnings

breaking In v4.x the synchronous client SAClient replaces the legacy sa module. All method calls must go through SAClient instance. ↓

fix Migrate from `import superannotate as sa` to `from superannotate import SAClient` and instantiate with `sa = SAClient(...)`. Function signatures changed.

breaking Pydantic v2 migration in v4.5.3. If you rely on Pydantic v1 compatibility, your code may break when using SAClient models directly. ↓

fix If pinning Pydantic v1, stay on 4.5.2 or upgrade Pydantic to v2. Refrain from direct manipulation of SAClient response pydantic models.

gotcha API token must be valid and passed as parameter or set via SA_API_TOKEN environment variable. Missing token raises ValueError with unclear message. ↓

fix Always set API token via environment variable SA_API_TOKEN or constructor argument api_token. Verify token is active in SuperAnnotate UI.

Imports

SAClient
```
from superannotate import SAClient
```
Main client class introduced in v4.x. Legacy import sa.SAClient is obsolete.

Quickstart

Initialize SAClient and list projects. Replace SA_API_TOKEN with your token.

from superannotate import SAClient
import os

# Initialize client with API token
sa = SAClient(api_token=os.environ.get('SA_API_TOKEN', ''))

# Example: list projects
projects = sa.list_projects()
for p in projects:
    print(p['name'], p['id'])