HubAI SDK

Python SDK for interacting with Luxonis HubAI, a platform for managing, converting, and deploying machine learning models for Luxonis OAK devices. If you want to convert models locally, check out modelconverter instead.

API documentation is available at https://luxonis.github.io/hubai-sdk/.

✨ Features

• Model Management: Create, list, update, and delete HubAI models
• Variant Management: Manage HubAI model variants and versions
• Instance Management: Create and manage HubAI model instances
• Model Conversion: Convert HubAI models to various formats including:
  • RVC2
  • RVC3
  • RVC4
  • Hailo
• CLI Tools: Command-line interface for all operations
• Type Safety: Full type hints for better developer experience

📦 Installation

Install the package using pip:

pip install hubai-sdk

Or install from source:

git clone https://github.com/luxonis/hubai-sdk.git
cd hubai-sdk
pip install -e .

📋 Requirements

• Python 3.10 or higher
• Valid Luxonis HubAI API key available from HubAI Team API Key Settings

🔐 Authentication

Get Your API Key

1. Visit HubAI Team API Key Settings
2. Generate or copy your API key

Set API Key

You can authenticate in several ways:

Option 1: Environment Variable

export HUBAI_API_KEY="your-api-key-here"

This will store the API key in your environment variable and will be used by the SDK automatically. It is valid for the current session only.

Option 2: CLI Login

hubai login

This opens a browser where you can generate a new API key and then prompts you to enter it for secure local storage. Use hubai login --relogin to replace an existing key, or hubai logout to remove it.

Option 3: Pass API Key Directly

from hubai_sdk import HubAIClient

client = HubAIClient(api_key="your-api-key-here")

🚀 Quick Start

Python SDK Usage

import os

from hubai_sdk import HubAIClient

# Initialize client
api_key = os.getenv("HUBAI_API_KEY")
client = HubAIClient(api_key=api_key)

# List all models
models = client.models.list_models()
print(f"Found {len(models)} models")

# Get a specific model
model = client.models.get_model(models[0].id)
print(f"Model: {model.name}")

# Convert a model to RVC2 format
response = client.convert.RVC2(
    path="/path/to/your/model.onnx",
    name="my-converted-model",
)

print(f"Converted model downloaded to: {response.downloaded_path}")

🛠️ Services

The SDK provides four main services accessible through the HubAIClient:

Using Slugs from HubAI

You can copy slugs directly from the HubAI platform and use them as identifiers in the SDK for models and variants:

hubai model info luxonis/yolov6-nano:r2-coco-512x384

🤖 Models Service (client.models)

Manage ML models in HubAI.

# List models
models = client.models.list_models(
    tasks=["OBJECT_DETECTION"],
    is_public=True,
    limit=10,
)

# Get model by ID or slug (e.g., "luxonis/yolov6-nano:r2-coco-512x384")
model = client.models.get_model("model-id-or-slug")

# Create a new model
new_model = client.models.create_model(
    name="my-model",
    license_type="MIT",
    is_public=False,
    description="My awesome model",
    tasks=["OBJECT_DETECTION"],
)

# Update a model
updated_model = client.models.update_model(
    model.id,
    license_type="Apache 2.0",
    description="Updated description",
)

# Delete a model
client.models.delete_model(model.id)

🔄 Variants Service (client.variants)

Manage model variants and versions.

# Assume `model` is a `ModelResponse`.

# List variants (optionally filtered by model)
variants = client.variants.list_variants(model_id=model.id)

# Get variant by ID or slug (e.g., "luxonis/yolov6-nano:r2-coco-512x384")
variant = client.variants.get_variant("variant-id-or-slug")

# Create a new variant
new_variant = client.variants.create_variant(
    name="my-variant",
    model_id=model.id,
    variant_version="1.0.0",
    description="First version",
)

# Delete a variant
client.variants.delete_variant("variant-id")

📦 Instances Service (client.instances)

Manage model instances (specific configurations of variants).

from hubai_sdk.utils.types import ModelType

# Create an instance
instance = client.instances.create_instance(
    name="my-instance",
    variant_id="variant-id",
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 288, 512],
)

# Upload a file to instance
client.instances.upload_file("/path/to/nn_archive.tar.xz", instance.id)

# Get instance config
config = client.instances.get_config(instance.id)

# Download instance
downloaded_path = client.instances.download_instance(instance.id)

# Delete instance
client.instances.delete_instance(instance.id)

⚡ Conversion Service (client.convert)

Convert models to various formats.

RVC2 Conversion

Convert models for Luxonis OAK devices:

response = client.convert.RVC2(
    path="/path/to/model.onnx",
    name="converted-model",
    compress_to_fp16=True,
    number_of_shaves=8,
    superblob=True,
)

RVC4 Conversion

Convert models to Qualcomm SNPE format:

response = client.convert.RVC4(
    path="/path/to/model.onnx",
    name="converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    use_per_channel_quantization=True,
    htp_socs=["sm8550"],
)

Generic Conversion

Convert to any supported target:

from hubai_sdk.utils.types import Target

response = client.convert.convert(
    target=Target.RVC4,  # or Target.RVC2, Target.HAILO, etc.
    path="/path/to/model.onnx",
    name="converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    input_shape=[1, 3, 288, 512],
)

💻 CLI Usage

The SDK also provides a command-line interface:

# Login
hubai login

# List models
hubai model ls

# Get model info
hubai model info <model-id-or-slug>

# Create a model
hubai model create "my-model" --license-type MIT --tasks OBJECT_DETECTION

# Convert a model
hubai convert RVC2 --path /path/to/model.onnx --name "my-model"

# List variants
hubai variant ls

# List instances
hubai instance ls

For more CLI options, use the --help flag:

hubai --help
hubai model --help
hubai convert --help
hubai convert RVC4 --help

📚 Examples

See the examples/ directory for more detailed usage examples:

• examples/models.py: Model management operations
• examples/variants.py: Variant management operations
• examples/instances.py: Instance management and file operations
• examples/conversion: Model conversion examples for different formats

Migration from blobconverter

BlobConverter is our previous library for converting models to the BLOB format usable with RVC2 and RVC3 devices. It is being replaced by modelconverter and HubAI SDK, which will eventually become the supported conversion path.

blobconverter is still available and can be used for conversion, but we recommend using HubAI SDK for new projects. The HubAI SDK API is similar to blobconverter, but there are differences in parameters and in how conversion is performed. Hosted HubAI conversion also replaces the older tools.luxonis.com YOLO conversion workflow.

blobconverter offers separate functions for different source frameworks, such as from_onnx, from_openvino, and from_tf. These are now replaced by convert.RVC2 or convert.RVC3 in HubAI SDK, both of which take a path to the source model.

The following table shows the mapping between blobconverter parameters and HubAI SDK parameters.

blobconverter	HubAI SDK	Notes
model	path	The model file path.
xml	path	The XML file path. Only for conversion from OpenVINO IR
bin	opts["input_bin"]	The BIN file path. Only for conversion from OpenVINO IR when it is not beside the XML file. See the example.
version	tool_version	The version of the conversion tool.
data_type	compress_to_fp16 / quantization_mode	RVC2 and RVC3 use compress_to_fp16. RVC4 uses quantization_mode.
shaves	number_of_shaves	The number of shaves to use.
optimizer_params	mo_args	The arguments to pass to the model optimizer.
compile_params	compile_tool_args	The arguments to pass to the BLOB compiler.

By default, HubAI SDK enables superblob, which is only supported on DepthAI v3. To produce the legacy RVC2 blob format, pass superblob=False to convert.RVC2.

Simple Conversion

Simple ONNX conversion using blobconverter

import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
)

Equivalent code using HubAI SDK

response = client.convert.RVC2(
    path="resnet18.onnx",
)

blob = response.downloaded_path

Conversion from OpenVINO IR

blobconverter example

import blobconverter

blob = blobconverter.from_openvino(
    xml="resnet18.xml",
    bin="resnet18.bin",
)

HubAI SDK example

# When the XML and BIN files are at the same location,
# only the XML needs to be specified
response = client.convert.RVC2("resnet18.xml")
blob = response.downloaded_path

# Otherwise, specify the BIN file explicitly using
# the `opts` parameter
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "/other/path/resnet18.bin",
    },
)
blob = response.downloaded_path

Conversion from tflite

[!WARNING] HubAI online conversion does not support frozen PB files. Only TFLite files are supported.

blobconverter

import blobconverter

blob = blobconverter.from_tf(
    frozen_pb="resnet18.tflite",
)

Equivalent code using HubAI SDK

response = client.convert.RVC2(
    path="resnet18.tflite",
)

blob = response.downloaded_path

Advanced Parameters

blobconverter.from_onnx with advanced parameters

import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
    data_type="FP16",
    version="2021.4",
    shaves=6,
    optimizer_params=[
        "--mean_values=[127.5,127.5,127.5]",
        "--scale_values=[255,255,255]",
    ],
    compile_params=["-ip U8"],
)

Equivalent code using HubAI SDK

response = client.convert.RVC2(
    path="resnet18.onnx",
    compress_to_fp16=True,
    tool_version="2021.4.0",
    number_of_shaves=6,
    mo_args=[
        "mean_values=[127.5,127.5,127.5]",
        "scale_values=[255,255,255]",
    ],
    compile_tool_args=["-ip", "U8"],
)

blob = response.downloaded_path

Caffe Conversion

Conversion from the Caffe framework is not supported.

📄 Available Parameters

See docs/available_parameters.md for the full conversion parameter reference.

🔨 Development

Setup Development Environment

git clone https://github.com/luxonis/hubai-sdk.git
cd hubai-sdk
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

💬 Support

• Issues: GitHub Issues
• Email: support@luxonis.com
• Documentation: HubAI Platform

🔗 Links

• Repository: https://github.com/luxonis/hubai-sdk
• HubAI Platform: https://hub.luxonis.com
• Luxonis: https://luxonis.com