Label Studio Python SDK

An interface is a JSX module where the final expression returns an object containing a default React component and several optional metadata/logic exports.

Important Constraints:

• No import statements: Use globals provided by the Label Studio runtime (e.g., React, getField, EditorUI, hooks).
• The default export must be a React function component.

Required and Optional Exports

• default: The React component (receives task, regions, setRegions, and params as props).
• getResults(regions, relations): Serializes interface state into Label Studio annotation results.
• parseResults(results): Deserializes Label Studio results back into { regions: [...] }.
• inputSchema: Declares task data fields used by the interface.
• outputSchema: Declares fields produced by the interface (used by Prompter-style auto-labeling).
• paramsSchema: Declares per-project configuration passed into the component as params.
• regionSchema: (Optional) Metadata for custom region shapes.
• specVersion: (Optional) Numeric compatibility marker.

function Screen({ task, regions, setRegions, params }) {
  return <div>{task.data.text}</div>;
}

function getResults(regions) {
  return regions;
}

function parseResults(results) {
  return { regions: results };
}

({
  default: Screen,
  getResults,
  parseResults,
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "dataField", default: "text" },
    },
  },
  outputSchema: {
    type: "object",
    properties: {
      sentiment: { type: "string", enum: ["Positive", "Negative"] },
    },
  },
  paramsSchema: {
    type: "object",
    properties: {
      mode: { type: "string", default: "review" },
    },
  },
});

The project_templates attribute on the LabelStudio client allows you to manage project templates for an organization.

Note: These endpoints are only available in Label Studio Enterprise and are not available in the Community Edition.

Available operations:

• list(): Retrieve all project templates.
• create(request, request_options): Create a new template.
• get(id, request_options): Retrieve a specific template by ID.
• update(id, ...): Update an existing template's details.
• delete(id, request_options): Remove a template.
• create_project_from_template(id, title, ...): Instantiate a new project using an existing template.

from label_studio_sdk import LabelStudio
from label_studio_sdk.environment import LabelStudioEnvironment

client = LabelStudio(
    api_key="<value>",
    environment=LabelStudioEnvironment.DEFAULT,
)

# Example: List templates
client.project_templates.list()

# Example: Create a template
client.project_templates.create(
    name="name",
    project_id=1,
)

# Example: Create a project from a template
client.project_templates.create_project_from_template(
    id=1,
    title="title",
)

Label Studio tools use a specific flow to resolve media URLs to local files via get_local_path. The process follows these logic paths based on the URL shape:

• Upload Keys (upload/project/file): The downloader first attempts to use the /storage-data/uploaded/?filepath=... proxy. If that fails (common with Nginx + FileSystemStorage), it falls back to /data/upload/project/file.
• Local Storage (/data/local-files?d=...): The tool attempts to read from the LOCAL_FILES_DOCUMENT_ROOT or downloads from the host.
• Cloud Storage (s3://, gs://, azure-blob://): These are resolved via the /tasks/{taskId}/presign?fileuri=... endpoint to obtain a downloadable URL.
• Direct HTTP: Standard http(s):// URLs are downloaded directly.
• Proxy Endpoints: Handles various LS proxy endpoints like /api/storages/... or /api/projects/.../file-proxy.

When download_resources=True is used, the files are downloaded and stored in the provided cache_dir.

The client.import_storage.gcs_sa namespace provides methods to manage Google Cloud Storage (GCS) import storage connections that use Service Account (SA) Impersonation.

Note: These features are exclusive to Label Studio Enterprise and are not available in the Community Edition.

Available operations:

• list(project=...): Retrieve all GCS import storage connections for a specific project.
• create(request=...): Create a new GCS import storage connection using SA Impersonation.
• get(id=...): Retrieve details for a specific storage connection.
• update(id=..., **kwargs): Update an existing connection's configuration (e.g., bucket, prefix, target_service_account_email).
• delete(id=...): Remove a storage connection.
• validate(request=...): Validate a specific connection configuration.
• sync(id=...): Manually trigger a task synchronization from the storage connection.

The Label Studio Converter allows you to encode Label Studio annotations into various machine learning formats (JSON, CSV, COCO, etc.). You can use it via the Command Line Interface (CLI) or the Python API.

Python API Usage

To use the Python API, instantiate a Converter with your Label Studio configuration XML file, then call the specific conversion method for your desired format.

CLI Usage

Use the label-studio-converter command with the appropriate subcommands (e.g., export) and flags to specify input, configuration, output, and format.

from label_studio_converter import Converter

# Initialize with the project configuration XML
c = Converter('examples/sentiment_analysis/config.xml')

# Convert completions to JSON
c.convert_to_json('examples/sentiment_analysis/completions/', 'tmp/output.json')

# Convert completions to CSV
c.convert_to_csv('examples/sentiment_analysis/completions/', 'output_dir', sep='\t', header=True)