Introduction

Getting started

Endpoints with sparkles ✨ next to them are only available for Label Studio Enterprise and, in many cases, Starter Cloud users.

Version 2.0 is here!

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.

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

If you are using our SDK with an LLM, you can use this: https://api.labelstud.io/llms.txt

Install

Install the Label Studio SDK using pip:

or

Authenticate and Connect to the API

“API keys” vs. “Access tokens”

In Label Studio, “access tokens” and “API keys” mean the same thing and are used interchangeably.

For example, if you set the LABEL_STUDIO_API_KEY environment variable, you will set it to your access token.

Python SDK

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 access token/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:

You can set LABEL_STUDIO_URL and LABEL_STUDIO_API_KEY as environment variables:

HTTP API

If you are calling endpoints using HTTP (such as with cUrl commands), you will need to adjust your authorization header depending on which type of access token you are using.

Personal access tokens:

Legacy tokens:

Tutorials

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

Advanced tutorials focused on ML backends:

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

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:

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

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.

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.

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.