Segments.ai Python SDK

1.25.0 verified Sat May 09 auth: no python

Official Python client for the Segments.ai annotation platform. Enables dataset management, sample upload/download, annotation export, and integration with labeling workflows. Current version 1.25.0, release cadence approximately monthly.

pip install segments-ai

Common errors

error ModuleNotFoundError: No module named 'segments' ↓

cause Package not installed or installed in a different environment.

fix

Run pip install segments-ai in your current Python environment.

error segments.exceptions.AuthenticationError: Invalid API key ↓

cause Missing or incorrect API key passed to SegmentsClient.

fix

Pass a valid API key via SegmentsClient(api_key='your-api-key') or set the SEGMENTS_API_KEY environment variable.

error TypeError: __init__() got an unexpected keyword argument 'hub_token' ↓

cause Hugging Face Hub token argument is no longer supported as of v1.20.0.

fix

Remove hub_token argument. Use SegmentsClient(api_key=...) instead.

Warnings

breaking In version 1.20.0, Hugging Face integration was dropped. Any code relying on huggingface_hub integration will break. ↓

fix Remove any usage of SegmentsClient with Hugging Face Hub; use direct API key authentication instead.

deprecated The `Client` class was renamed to `SegmentsClient` in v1.0.0. `Client` may be removed in future. ↓

fix Use `from segments import SegmentsClient` instead of `from segments import Client`.

gotcha Rate limiting is enforced. Scripts that make many parallel requests may hit 429 errors. ↓

fix Implement exponential backoff or limit concurrency. The SDK raises `RateLimitError` (version >=1.20.0).

Imports

SegmentsClient
wrong
```
import segments
```
correct
```
from segments import SegmentsClient
```
Use explicit import to avoid attribute confusion.
SegmentsDataset
wrong
```
from segments import Dataset
```
correct
```
from segments import SegmentsDataset
```
Dataset is not exported; use SegmentsDataset.

Quickstart

Initialize client and list datasets.

from segments import SegmentsClient
import os

client = SegmentsClient(api_key=os.environ.get('SEGMENTS_API_KEY', ''))
# List datasets
datasets = client.get_datasets()
print(datasets)