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 = "eabdde840de8c8853329c086bc4165591cb3d74c"
client = SegmentsClient(api_key)


Get all samples in a dataset

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": ""
sample = client.add_sample(dataset, name, attributes)

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.


Get a label

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

Create or update a label for a sample

A label can be added to a sample in relation to a task defined on the dataset, such as an image classification task or an image segmentation task.

The task specifies the format that is required for the label: for a classification task, the attributesfield should contain different fields than for a segmentation task.

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
task_name = "segmentation"
attributes = {
"segmentation_bitmap_url": ""
"objects": [
"instance_id": 1
"category_id": 2
"instance_id": 2
"category_id": 3
client.add_label(sample_uuid, task_name, attributes)

For a segmentation task, thesegmentation_bitmap_urlfield should refer to a 32-bit RGBA png image with alpha channel set to 255 and values corresponding toinstance_id

Upload a file as an asset

Example with an image:

from PIL import Image
from io import BytesIO
image ="/home/jane/flowers/violet.jpg")
file = BytesIO(), 'PNG')
asset = client.upload_asset(file, filename="violet.jpg")
image_url = asset["url"]