Quickstart

Get started with the CVAT Python SDK in minutes

This quickstart guide covers the essential operations to get you up and running with the CVAT Python SDK.

Creating a Client

The Client class is your main entry point for interacting with CVAT:

from cvat_sdk import Client, Config

# Create a client (auto-detects HTTPS/HTTP)
client = Client(url="cvat.example.com")

# Or specify the protocol explicitly
client = Client(url="https://cvat.example.com")

Authentication

Password Authentication

Log in with username and password:

client.login(("username", "password"))

Token Authentication

Use a Personal Access Token (PAT):

from cvat_sdk import make_client

client = make_client(
    host="cvat.example.com",
    access_token="your_personal_access_token"
)

Context Manager

Use the client as a context manager for automatic cleanup:

with Client(url="cvat.example.com") as client:
    client.login(("username", "password"))
    # Perform operations
    # Connection automatically closed when done

Basic Operations

Listing Projects and Tasks

# List all projects
projects = client.projects.list()
for project in projects:
    print(f"Project: {project.name} (ID: {project.id})")

# List all tasks
tasks = client.tasks.list()
for task in tasks:
    print(f"Task: {task.name} (ID: {task.id})")

Creating a Task

from cvat_sdk import models

# Define task specification
task_spec = models.TaskWriteRequest(
    name="My First Task",
    labels=[
        models.PatchedLabelRequest(
            name="car",
            color="#ff0000",
            attributes=[]
        ),
        models.PatchedLabelRequest(
            name="person",
            color="#00ff00",
            attributes=[]
        )
    ]
)

# Create task with local images
task = client.tasks.create_from_data(
    spec=task_spec,
    resources=["image1.jpg", "image2.jpg", "image3.jpg"],
    resource_type=models.ResourceType.LOCAL
)

print(f"Created task ID: {task.id}")

Retrieving a Task

# Get task by ID
task = client.tasks.retrieve(task_id=123)

print(f"Task name: {task.name}")
print(f"Task size: {task.size}")
print(f"Task status: {task.status}")

Working with Annotations

# Get annotations
annotations = task.get_annotations()

print(f"Shapes: {len(annotations.shapes)}")
print(f"Tags: {len(annotations.tags)}")
print(f"Tracks: {len(annotations.tracks)}")

# Add new annotations
new_annotations = models.PatchedLabeledDataRequest(
    shapes=[
        models.LabeledShapeRequest(
            type="rectangle",
            frame=0,
            label_id=task.labels[0].id,
            points=[100, 100, 200, 200],  # x1, y1, x2, y2
            attributes=[]
        )
    ]
)

task.update_annotations(new_annotations)

Downloading Frames

from pathlib import Path

# Download specific frames
output_dir = Path("frames")
task.download_frames(
    frame_ids=[0, 1, 2],
    outdir=output_dir,
    quality="original"
)

Exporting Annotations

# Export annotations in YOLO format
task.export_dataset(
    format_name="YOLO 1.1",
    filename="annotations.zip"
)

Working with Jobs

# Get jobs from a task
jobs = task.get_jobs()

for job in jobs:
    print(f"Job ID: {job.id}")
    print(f"Status: {job.status}")
    print(f"Stage: {job.stage}")
    print(f"Assignee: {job.assignee}")

Configuration Options

Customize client behavior with Config:

config = Config(
    status_check_period=3.0,  # Check operation status every 3 seconds
    allow_unsupported_server=True,  # Allow connecting to unsupported server versions
    verify_ssl=True  # Verify SSL certificates
)

client = Client(url="cvat.example.com", config=config)

Organization Context

Work within an organization context:

# Set organization context
client.organization_slug = "my-organization"

# All operations now use this organization context
tasks = client.tasks.list()

# Use organization context temporarily
with client.organization_context("another-org"):
    # Operations in this block use 'another-org'
    tasks = client.tasks.list()

# Back to 'my-organization' context

Complete Example

Here’s a complete example that creates a task, uploads images, and downloads annotations:

from cvat_sdk import Client, models
from pathlib import Path

def main():
    # Connect and authenticate
    with Client(url="cvat.example.com") as client:
        client.login(("username", "password"))
        
        # Create task
        task_spec = models.TaskWriteRequest(
            name="Detection Task",
            labels=[
                models.PatchedLabelRequest(
                    name="object",
                    color="#ff0000"
                )
            ]
        )
        
        # Upload images
        images_dir = Path("images")
        image_files = list(images_dir.glob("*.jpg"))
        
        task = client.tasks.create_from_data(
            spec=task_spec,
            resources=image_files
        )
        
        print(f"Created task {task.id}: {task.name}")
        
        # Export annotations after annotation work is done
        task.export_dataset(
            format_name="COCO 1.0",
            filename="export.zip"
        )
        
        print("Task created and ready for annotation!")

if __name__ == "__main__":
    main()

Next Steps

• Client Reference - Deep dive into Client configuration
• Core Operations - Detailed guide on projects, tasks, and jobs
• PyTorch Integration - Use CVAT data for training
• Auto-Annotation - Automate annotation with models