Python SDK

The Python SDK is a convenient wrapper for the API.


Please refer to this blog post for a full example of working with the Python SDK.

First install the SDK.

pip install segments-ai --upgrade

Import the segments package in your python file and and set up a client with an API key. An API key can be created on your user account page.

from segments import SegmentsClient
api_key = "eabdde840de8c8853329c086bc4165591cb3d521"
client = SegmentsClient(api_key)


List datasets

user = "jane"
datasets = client.get_datasets(user)
for dataset in datasets:
print(dataset["name"], dataset["description"])

Get a dataset

dataset_identifier = "jane/flowers"
dataset = client.get_dataset(dataset_identifier)

Create a dataset

dataset_name = "flowers"
description = "A dataset containing flowers of all kinds."
category = "garden"
dataset = client.add_dataset(dataset_name, description, category)

Delete a dataset

dataset_identifier = "jane/flowers"


List samples

dataset = "jane/flowers"
samples = client.get_samples(dataset)
for sample in samples:
print(sample["name"], sample["uuid"])

Get a sample

sample = client.get_sample(uuid="602a3eec-a61c-4a77-9fcc-3037ce5e9606")

Create a sample

dataset = "jane/flowers"
name = "violet.jpg"
attributes = {
"image": {
"url": ""
# metadata and priority are optional fields
metadata = {
"city": "London",
"weather": "cloudy",
"robot_id": 3
priority = 10 # Samples with higher priority value will be labeled first. Default is 0.
sample = client.add_sample(dataset, name, attributes, metadata, priority)

If the image is on your local computer, you should first upload it to a cloud storage service like Amazon S3, Google Cloud Storage, Imgur, or our asset storage service.

If you create a sample with a URL from a public S3 bucket and you see an error on the platform, make sure to properly configure your bucket's CORS settings.

Delete a sample



Get a label

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
labelset = "ground-truth"
label = client.get_label(sample_uuid, labelset)

Create or update a label

A label can be added to a sample in relation to a label set, such as the default ground-truth label set, or a newly created label set for model predictions. You can create a new label set by clicking the "Add new label set" link on the Samples tab.

The content of the attributes field depends on the label type.

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
labelset = "ground-truth"
attributes = {
"format_version": "0.1",
"annotations": [
"id": 1,
"category_id": 2
"id": 2,
"category_id": 3
"segmentation_bitmap": {
"url": ""
client.add_label(sample_uuid, labelset, attributes)

Thesegmentation_bitmap_urlrefers to a 32-bit RGBA png image. The alpha channel is set to 255, and the remaining 24-bit values in the RGB channels correspond toinstance_ids.

The easiest way to transform a segmentation bitmap into this format and upload it is by using the util functionbitmap2file:

from segments.utils import bitmap2file
# segmentation_bitmap is a numpy array of type np.uint32, with values corresponding to instance_ids
file = bitmap2file(segmentation_bitmap)
asset = client.upload_asset(file, "label.png")
segmentation_bitmap_url = asset["url"]

For a full example of uploading model-generated labels to, please refer to this blogpost.

Delete a label

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
labelset = "ground-truth"
client.delete_label(sample_uuid, labelset)

Upload a file as an asset

Example with an image:

filename = "/home/jane/flowers/violet.jpg"
with open(filename, "rb") as f:
asset = client.upload_asset(f, filename="violet.jpg")
image_url = asset["url"]