Python SDK

Search…
Python SDK
The Python SDK is a convenient wrapper for the API.
Setup
Please refer to the Python SDK quickstart for a full example of working with the Python SDK.
First install the SDK.
1
pip install segments-ai --upgrade
Copied!
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.
1
from segments import SegmentsClient
2
​
3
api_key = "YOUR_API_KEY"
4
client = SegmentsClient(api_key)
Copied!
Datasets
List datasets
Example
1
datasets = client.get_datasets()
2
​
3
for dataset in datasets:
4
    print(dataset["name"], dataset["description"])
Copied!
Signature
1
client.get_datasets(user=None)
2
​
3
"""Get a list of datasets.
4
​
5
Args:
6
    user (str, optional): The user for which to get the datasets. Leave empty to get datasets of current user. Defaults to None.
7
​
8
Returns:
9
    list: a list of dictionaries representing the datasets.
10
"""
Copied!
Get a dataset
Example
1
dataset_identifier = "jane/flowers"
2
dataset = client.get_dataset(dataset_identifier)
3
print(dataset)
Copied!
Signature
1
client.get_dataset(dataset_identifier)
2
​
3
"""Get a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
​
8
Returns:
9
    dict: a dictionary representing the dataset.
10
"""
Copied!
Create a dataset
Example
1
dataset_name = "flowers"
2
description = "A dataset containing flowers of all kinds."
3
task_type = "segmentation-bitmap"
4
​
5
dataset = client.add_dataset(dataset_name, description, task_type)
6
print(dataset)
Copied!
Task type
Value
Image segmentation labels (bitmap)
segmentation-bitmap
Image bounding box labels
bboxes
Image vector labels
vector
Pointcloud cuboid labels
pointcloud-cuboid
Pointcloud cuboid labels (sequence)
pointcloud-cuboid-sequence
Pointcloud segmentation labels
pointcloud-segmentation
Pointcloud segmentation labels (sequence)
pointcloud-segmentation-sequence
Text named entity labels
text-named-entities
Text span categorization labels
text-span-categorization
Signature
1
client.add_dataset(self, name, description='', task_type='segmentation-bitmap', task_attributes=None, category='other', public=False, readme='', enable_skip_labeling=True, enable_skip_reviewing=False, enable_ratings=False)
2
​
3
"""Add a dataset.
4
​
5
Args:
6
    name (str): The dataset name. Example: flowers.
7
    description (str, optional): The dataset description. Defaults to ''.
8
    task_type (str, optional): The dataset's task type. One of 'segmentation-bitmap', 'segmentation-bitmap-highres', 'vector', 'bboxes', 'keypoints'. Defaults to 'segmentation-bitmap', 'pointcloud-segmentation', 'pointcloud-detection'.
9
    task_attributes (dict, optional): The dataset's task attributes. Defaults to None.
10
    category (str, optional): The dataset category. Defaults to 'other'.
11
    public (bool, optional): The dataset visibility. Defaults to False.
12
    readme (str, optional): The dataset readme. Defaults to ''.
13
    enable_skip_labeling (bool, optional): Enable the skip button in the labeling workflow. Defaults to True.
14
    enable_skip_reviewing (bool, optional): Enable the skip button in the reviewing workflow. Defaults to False.
15
    enable_ratings: Enable star-ratings for labeled images. Defaults to False.
16
​
17
Returns:
18
    dict: a dictionary representing the newly created dataset.
19
"""
Copied!
Update a dataset
Example
1
dataset_identifier = "jane/flowers"
2
description = "A dataset containing flowers of all kinds."
3
​
4
dataset = client.update_dataset(dataset_identifier, description)
5
print(dataset)
Copied!
Signature
1
client.update_dataset(self, dataset_identifier, description=None, task_type=None, task_attributes=None, category=None, public=None, readme=None, enable_skip_labeling=None, enable_skip_reviewing=None, enable_ratings=None)
2
​
3
"""Update a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    description (str, optional): The dataset description.
8
    task_type (str, optional): The dataset's task type. One of 'segmentation-bitmap', 'segmentation-bitmap-highres', 'vector', 'bboxes', 'keypoints', 'pointcloud-segmentation', 'pointcloud-detection'.
9
    task_attributes (dict, optional): The dataset's task attributes.
10
    category (str, optional): The dataset category.
11
    public (bool, optional): The dataset visibility.
12
    readme (str, optional): The dataset readme.
13
    enable_skip_labeling (bool, optional): Enable the skip button in the labeling workflow.
14
    enable_skip_reviewing (bool, optional): Enable the skip button in the reviewing workflow.
15
    enable_ratings: Enable star-ratings for labeled images.
16
​
17
Returns:
18
    dict: a dictionary representing the updated dataset.
19
"""
Copied!
Delete a dataset
Example
1
dataset_identifier = "jane/flowers"
2
client.delete_dataset(dataset_identifier)
Copied!
Signature
1
client.delete_dataset(dataset_identifier)
2
​
3
"""Delete a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
"""
Copied!
Add a collaborator to a dataset
Example
1
dataset_identifier = "jane/flowers"
2
username = "john"
3
role = "reviewer"
4
client.add_dataset_collaborator(dataset_identifier, username, role)
Copied!
Signature
1
client.add_dataset_collaborator(dataset_identifier, username, role='labeler')
2
​
3
"""Add a collaborator to a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    username (str): The username of the collaborator to be added.
8
    role (str, optional): The role of the collaborator to be added. One of labeler, reviewer, admin. Defaults to labeler.
9
​
10
Returns:
11
    dict: a dictionary containing the newly added collaborator with its role.
12
"""
Copied!
Samples
List samples
Example
1
dataset_identifier = "jane/flowers"
2
samples = client.get_samples(dataset_identifier)
3
​
4
for sample in samples:
5
    print(sample["name"], sample["uuid"])
Copied!
Signature
1
get_samples(self, dataset_identifier, name=None, label_status=None, metadata=None, sort='name', direction='asc', per_page=1000, page=1)
2
​
3
"""Get the samples in a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str, optional): Name to filter by. Defaults to None (no filtering).
8
    label_status (list, optional): List of label statuses to filter by. Defaults to None (no filtering).
9
    metadata (list, optional): List of 'key:value' metadata attributes to filter by. Defaults to None (no filtering).
10
    sort (str, optional): What to sort results by. One of 'name', 'created', 'priority'. Defaults to 'name'.
11
    direction (str, optional): Sorting direction. One of 'asc' (ascending) or 'desc' (descending). Defaults to 'asc'.
12
    per_page (int, optional): Pagination parameter indicating the maximum number of samples to return. Defaults to 1000.
13
    page (int, optional): Pagination parameter indicating the page to return. Defaults to 1.
14
​
15
Returns:
16
    list: a list of dictionaries representing the samples.
17
"""
Copied!
Get a sample
Example
1
sample = client.get_sample(uuid="602a3eec-a61c-4a77-9fcc-3037ce5e9606")
2
print(sample)
Copied!
Signature
1
client.get_sample(uuid, labelset=None)
2
​
3
"""Get a sample.
4
​
5
Args:
6
    uuid (str): The sample uuid.
7
    labelset (str, optional): If defined, this additionally returns the label for the given labelset. Defaults to None. 
8
​
9
Returns:
10
    dict: a dictionary representing the sample.
11
"""
Copied!
Create a sample
The content of the attributes field depends on the sample type.
If the image file 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.
Example
1
dataset_identifier = "jane/flowers"
2
name = "violet.jpg"
3
attributes = {
4
    "image": {
5
        "url": "https://example.com/violet.jpg"
6
    }
7
}
8
​
9
# metadata and priority are optional fields
10
metadata = {
11
    "city": "London",
12
    "weather": "cloudy",
13
    "robot_id": 3
14
}
15
priority = 10 # Samples with higher priority value will be labeled first. Default is 0.
16
​
17
sample = client.add_sample(dataset_identifier, name, attributes, metadata, priority)
18
print(sample)
Copied!
Signature
1
client.add_sample(dataset_identifier, name, attributes, metadata=None, priority=None)
2
​
3
"""Add a sample to a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the sample.
8
    attributes (dict): The sample attributes. Please refer to the online documentation.
9
    metadata (dict, optional): Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.
10
    priority (float, optional): Priority in the labeling queue. Samples with higher values will be labeled first. Default is 0.
11
​
12
Returns:
13
    dict: a dictionary representing the newly created sample.
14
"""
Copied!
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.
Update a sample
Example
1
uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
2
metadata = {
3
    "city": "London",
4
    "weather": "cloudy",
5
    "robot_id": 3
6
}
7
priority = 10 # Samples with higher priority value will be labeled first. Default is 0.
8
​
9
sample = client.update_sample(uuid, metadata=metadata, priority=priority)
10
print(sample)
Copied!
Signature
1
client.update_sample(uuid, name=None, attributes=None, metadata=None, priority=None)
2
​
3
"""Update a sample.
4
​
5
Args:
6
    uuid (str): The sample uuid.
7
    name (str, optional): The name of the sample.
8
    attributes (dict, optional): The sample attributes. Please refer to the online documentation.
9
    metadata (dict, optional): Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.
10
    priority (float, optional): Priority in the labeling queue. Samples with higher values will be labeled first. Default is 0.
11
​
12
Returns:
13
    dict: a dictionary representing the updated sample.
14
"""
Copied!
Delete a sample
Example
1
client.delete_sample(uuid="602a3eec-a61c-4a77-9fcc-3037ce5e9606")
Copied!
Signature
1
client.delete_sample(uuid)
2
​
3
"""Delete a sample.
4
​
5
Args:
6
    uuid (str): The sample uuid.
7
"""
Copied!
Labels
Get a label
Example
1
sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
2
​
3
label = client.get_label(sample_uuid)
4
print(label)
Copied!
Signature
1
client.get_label(sample_uuid, labelset='ground-truth')
2
​
3
"""Get a label.
4
​
5
Args:
6
    sample_uuid (str): The sample uuid.
7
    labelset (str): The labelset this label belongs to. Defaults to 'ground-truth'.
8
​
9
Returns:
10
    dict: a dictionary representing the label.
11
"""
Copied!
Create a label
A label is 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 uploading 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.
Example
1
sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
2
labelset = "ground-truth"
3
attributes = {
4
    "format_version": "0.1",
5
    "annotations": [
6
        {
7
            "id": 1,
8
            "category_id": 1,
9
            "type": "bbox",
10
            "points": [
11
              [12.34, 56.78],
12
              [90.12, 34.56]
13
            ]
14
        },
15
    ]
16
}
17
​
18
client.add_label(sample_uuid, labelset, attributes)
Copied!
Signature
1
client.add_label(sample_uuid, labelset, attributes, label_status='PRELABELED')
2
​
3
"""Add a label to a sample.
4
​
5
Args:
6
    sample_uuid (str): The sample uuid.
7
    labelset (str): The labelset this label belongs to.
8
    attributes (dict): The label attributes. Please refer to the online documentation.
9
    label_status (str, optional): The label status. Defaults to 'PRELABELED'.
10
    score (float, optional): The label score. Defaults to None.
11
​
12
Returns:
13
    dict: a dictionary representing the newly created label.
14
"""
Copied!
Update a label
Example
1
sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
2
labelset = "ground-truth"
3
attributes = {
4
    "format_version": "0.1",
5
    "annotations": [
6
        {
7
            "id": 1,
8
            "category_id": 1,
9
            "type": "bbox",
10
            "points": [
11
              [12.34, 56.78],
12
              [90.12, 34.56]
13
            ]
14
        },
15
    ]
16
}
17
​
18
client.update_label(sample_uuid, labelset, attributes)
Copied!
Signature
1
client.update_label(sample_uuid, labelset, attributes=None, label_status='PRELABELED', score=None)
2
​
3
"""Update a label.
4
​
5
Args:
6
    sample_uuid (str): The sample uuid.
7
    labelset (str): The labelset this label belongs to.
8
    attributes (dict): The label attributes. Please refer to the online documentation.
9
    label_status (str, optional): The label status. Defaults to 'PRELABELED'.
10
    score (float, optional): The label score. Defaults to None.
11
​
12
Returns:
13
    dict: a dictionary representing the updated label.
14
"""
Copied!
Delete a label
Example
1
sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
2
labelset = "ground-truth"
3
client.delete_label(sample_uuid, labelset)
Copied!
Signature
1
client.delete_label(sample_uuid, labelset)
2
​
3
"""Delete a label.
4
​
5
Args:
6
    sample_uuid (str): The sample uuid.
7
    labelset (str): The labelset this label belongs to.
8
"""
Copied!
Label sets
A label is 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 uploading model predictions.
List label sets
Example
1
dataset_identifier = "jane/flowers"
2
labelsets = client.get_labelsets(dataset_identifier)
3
​
4
for labelset in labelsets:
5
    print(labelset["name"], labelset["description"])
Copied!
Signature
1
client.get_labelsets(dataset_identifier)
2
​
3
"""Get the labelsets in a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
​
8
Returns:
9
    list: a list of dictionaries representing the labelsets.
10
"""
Copied!
Get a label set
Example
1
dataset_identifier = "jane/flowers"
2
name = "model-predictions"
3
​
4
labelset = client.get_labelset(dataset_identifier, name)
5
print(labelset)
Copied!
Signature
1
client.get_labelset(dataset_identifier, name)
2
​
3
"""Get a labelset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the labelset.
8
​
9
Returns:
10
    dict: a dictionary representing the labelset.
11
"""
Copied!
Create a label set
You can also create a new label set by clicking the "Add new label set" link on the Samples tab.
Example
1
dataset_identifier = "jane/flowers"
2
name = "model-predictions-resnet50"
3
​
4
client.add_labelset(dataset_identifier, name)
Copied!
Signature
1
client.add_labelset(dataset_identifier, name, description='')
2
​
3
"""Add a labelset to a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the labelset.
8
    description (str, optional): The labelset description.
9
​
10
Returns:
11
    dict: a dictionary representing the labelset.
12
"""
Copied!
Delete a label set
Example
1
dataset_identifier = "jane/flowers"
2
name = "model-predictions"
3
​
4
client.delete_labelset(dataset_identifier, name)
Copied!
Signature
1
client.delete_labelset(dataset_identifier, name)
2
​
3
"""Delete a labelset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the labelset.
8
"""
Copied!
Releases
List releases
Example
1
dataset_identifier = "jane/flowers"
2
releases = client.get_releases(dataset_identifier)
3
​
4
for release in releases:
5
    print(release["name"], release["description"], release["attributes"]["url"])
Copied!
Signature
1
client.get_releases(dataset_identifier)
2
​
3
"""Get the releases in a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
​
8
Returns:
9
    list: a list of dictionaries representing the releases.
10
"""
Copied!
Get a release
Example
1
dataset_identifier = "jane/flowers"
2
name = "v0.1"
3
​
4
release = client.get_release(dataset_identifier, name)
5
print(release)
Copied!
Signature
1
client.get_release(dataset_identifier, name)
2
​
3
"""Get a release.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the release.
8
​
9
Returns:
10
    dict: a dictionary representing the release.
11
"""
Copied!
Create a release
Example
1
dataset_identifier = "jane/flowers"
2
name = "v0.1"
3
description = "My first release."
4
​
5
release = client.add_release(dataset_identifier, name, description)
6
print(release)
Copied!
Signature
1
client.add_release(dataset_identifier, name, description='')
2
​
3
"""Add a release to a dataset.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the release.
8
    description (str, optional): The release description.
9
​
10
Returns:
11
    dict: a dictionary representing the newly created release.
12
"""
Copied!
Delete a release
Example
1
dataset_identifier = "jane/flowers"
2
name = "v0.1"
3
​
4
client.delete_release(dataset_identifier, name)
Copied!
Signature
1
client.delete_release(dataset_identifier, name)
2
​
3
"""Delete a release.
4
​
5
Args:
6
    dataset_identifier (str): The dataset identifier, consisting of the name of the dataset owner followed by the name of the dataset itself. Example: jane/flowers.
7
    name (str): The name of the release.
8
"""
Copied!
Upload a file as an asset
Example
1
filename = "/home/jane/flowers/violet.jpg"
2
with open(filename, "rb") as f:
3
    asset = client.upload_asset(f, filename="violet.jpg")
4
    
5
image_url = asset["url"]
Copied!
Signature
1
client.upload_asset(file, filename='label.png')
2
​
3
"""Upload an asset.
4
​
5
Args:
6
    file (object): A file object.
7
    filename (str, optional): The file name. Defaults to label.png.
8
​
9
Returns:
10
    dict: a dictionary representing the uploaded file.
11
"""
Copied!
​
Reference - Previous
Categories and task attributes
Next - Reference
API
Last modified 5d ago