Getting started

Version 2.0 of the Label Studio SDK is here, and it’s packed with more functionality and a smoother developer experience!

If you’re using an older version, please review the breaking changes before upgrading.

You can use the Label Studio Python SDK to make annotating data a more integrated part of your data science and machine learning pipelines. This software development kit (SDK) lets you call the Label Studio API directly from scripts using predefined classes and methods.

For additional guidance on using our SDK, see 5 Tips and Tricks for Label Studio’s API and SDK

The following are basic examples. For more advanced examples, see Tutorials.

Install

Install the Label Studio SDK using pip:

pip install label-studio-sdk

or

poetry add label-studio-sdk

Authenticate and Connect to the API

In your Python scripts, you will need to do the following:

  • Import the SDK.

  • Define your Label Studio URL.

    For example, http://localhost:8080 or https://app.humansignal.com

    Note:

    • Do not including a trailing slash in your URL
    • LABEL_STUDIO_URL should start with https:// or http://
  • Define your API key.

    This should be available on the Account & Settings page, but you may need to enable it at the organization level first. See Access tokens.

    You can use either the Legacy Token or the Personal Access Token, but for the SDK we recommend the Personal Access Token.

  • Connect to the API.

Try this example:

1# Define the URL where Label Studio is accessible
2LABEL_STUDIO_URL = 'YOUR_BASE_URL'
3# API key is available at the Account & Settings page in Label Studio UI
4LABEL_STUDIO_API_KEY = 'YOUR_API_KEY'
5
6# Import the SDK and the client module
7from label_studio_sdk import LabelStudio
8
9# Connect to the Label Studio API
10client = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=LABEL_STUDIO_API_KEY)
11
12# A basic request to verify connection is working
13me = client.users.whoami()
14
15print("username:", me.username)
16print("email:", me.email)

You can set LABEL_STUDIO_URL and LABEL_STUDIO_API_KEY as environment variables:

$export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
>export LABEL_STUDIO_URL="YOUR_BASE_URL"

Tutorials

For examples of getting started using SDK, see the following tutorials:

Advanced tutorials focused on ML backends:

SDK versions and compatibility

SDK version < 1 is deprecated and no longer supported. We recommend upgrading to the latest version.

If you still want to use the older version, you can install it using pip install "label-studio-sdk<1".

You can also check out an older branch version in the GitHub repository:

1git clone https://github.com/HumanSignal/label-studio-sdk.git
2cd label-studio-sdk
3git fetch origin
4git checkout release/0.0.34

Or you can simply modify you code to change the import stream as follows:

1from label_studio_sdk import Client
2from label_studio_sdk.data_manager import Filters, Column, Operator, Type
3from label_studio_sdk._legacy import Project

If you’re looking for the documentation for the older version, you can find it here.

Advanced

Handling Errors

If you encounter an error while using the Label Studio Python SDK, you can catch the error and handle it in your script.

1from label_studio_sdk.core.api_error import ApiError
2
3try:
4 for annotated_task in annotated_tasks:
5 print(annotated_task.annotations)
6except ApiError as e:
7 print(e)

Annotations are exported in the format specified in the Label Studio JSON format.

Timeouts

By default, requests time out after 5 seconds. You can configure this with a timeout option at the client or request level.

1from label_studio_sdk import LabelStudio
2
3client = LabelStudio(
4 # All timeouts set to 20 seconds
5 timeout=20
6)
7
8ls.projects.create(..., request_options={
9 # Override timeout for a specific method
10 'timeout_in_seconds': 20
11})

Custom HTTP client

You can override the httpx client to customize it for your use case. Some common use cases include support for proxies and transports.

1custom_httpx_client = httpx.Client(
2 transport=httpx.HTTPTransport(
3 proxy="http://my.test.proxy.example.com",
4 local_address="0.0.0.0"
5 )
6)
7client = LabelStudio(
8 api_key="YOUR_API_KEY",
9 base_url="YOUR_LABEL_STUDIO_URL",
10 httpx_client=custom_httpx_client,
11)