Vi SDK

What is Vi SDK?

The Vi SDK is a comprehensive Python library for interacting with the Datature Vi platform. It provides a clean, intuitive API for managing computer vision datasets, annotations, training models, and performing inference with state-of-the-art vision-language models.

📋
Prerequisites

Python 3.10 or later

A secret key for API authentication

Organization ID from your Datature account

Understanding of datasets and annotations

Get started with Vi SDK →

Key features

Dataset Management

Upload, download, and manage datasets with support for multiple annotation formats

Asset Operations

Handle images with concurrent upload/download, progress tracking, and automatic format detection

Annotation Workflows

Create and manage annotations for phrase grounding, VQA, and other vision tasks

Model Training

Train vision-language models on Datature's infrastructure

Inference

Run inference with Qwen2.5-VL, InternVL 3.5, Cosmos Reason1, and NVILA models

Type-Safe API

Complete type hints, comprehensive error handling, and structured logging

Quick example

import vi

# Initialize client
client = vi.Client(
    secret_key="your-secret-key",
    organization_id="your-org-id"
)

# List datasets
for dataset in client.datasets:
    print(f"📊 {dataset.name} (ID: {dataset.dataset_id})")

# Download a dataset
result = client.get_dataset(
    dataset_id="your-dataset-id",
    save_dir="./data"
)

# Load dataset for training
from vi.dataset.loaders import ViDataset

dataset = ViDataset("./data/your-dataset-id")
print(f"Total assets: {dataset.info().total_assets}")

# Iterate through training split
for asset, annotations in dataset.training.iter_pairs():
    print(f"Processing: {asset.filename}")

Installation

Install Vi SDK using pip:

pip install vi-sdk

For additional features:

# With inference support (Qwen2.5-VL, InternVL 3.5, and other models)
pip install vi-sdk[inference]

# Install all features
pip install vi-sdk[all]

Core concepts

Client and authentication

The ViClient is your entry point to the Datature Vi platform. It handles authentication, request management, and provides access to all API resources.

import vi

# Using API credentials
client = vi.Client(
    secret_key="your-secret-key",
    organization_id="your-org-id"
)

# Using environment variables
import os

client = vi.Client(
    secret_key=os.getenv("DATATURE_VI_SECRET_KEY"),
    organization_id=os.getenv("DATATURE_VI_ORGANIZATION_ID")
)

Resource hierarchy

Vi SDK follows the platform's resource hierarchy:

Organization
├── Datasets
│   ├── Assets
│   └── Annotations
├── Runs
│   └── Models
└── Flows

Access resources through the client:

# Access organization
org = client.organizations.info()

# Access datasets
datasets = client.datasets.list()

# Access assets within a dataset
assets = client.assets.list(dataset_id="...")

# Access models from runs
models = client.models.list(run_id="...")

Error handling

Vi SDK provides comprehensive error handling with structured error codes:

from vi import (
    ViError,
    ViAuthenticationError,
    ViNotFoundError,
    ViValidationError
)

try:
    dataset = client.datasets.get("invalid-id")
except ViNotFoundError as e:
    print(f"Dataset not found: {e.message}")
    print(f"Suggestion: {e.suggestion}")
except ViAuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ViError as e:
    print(f"Error: {e.error_code} - {e.message}")

Pagination

Automatic pagination support for listing resources:

# Iterate over all pages automatically
for page in client.datasets.list():
    for dataset in page.items:
        print(dataset.name)

# Access just the first page
first_page = client.datasets.list()
print(f"First page has {len(first_page.items)} items")

# Iterate over all items across all pages
for dataset in client.datasets.list().all_items():
    print(dataset.name)

Supported features

Feature	Status	Documentation
Dataset Management	✅	Datasets API
Asset Upload/Download	✅	Assets API
Annotation Management	✅	Annotations API
Model Training	✅	Runs API
Model Inference	✅	Models API
Phrase Grounding	✅	Models API
VQA (Visual Question Answering)	✅	Models API
Dataset Loaders	✅	Getting Started
Progress Tracking	✅	All download/upload operations
Concurrent Operations	✅	Asset upload/download