CloudSoftwareHardware
Hub Control
Luxonis HubAI
Settings
Hub Original (Legacy)

ON THIS PAGE

  • HubAI SDK
  • Overview
  • Installation
  • Quick Start
  • Installation
  • Authentication
  • Model Management
  • Variant Management
  • New Verison of the Variant
  • Instance Management
  • Conversion

HubAI SDK

Overview

The HubAI SDK is a Python library for interacting with Luxonis HubAI programmatically. It enables automation of model management and conversion workflows directly from your Python code or Command Line Interface (CLI).Key Features:
  • Programmatic access to HubAI models, variants, and instances
  • Automated model conversion to RVC2, RVC3, RVC4, and Hailo formats
  • Command-line interface for all operations
  • Type-safe Python API with full type hints
  • Support for both Python scripts and CLI workflows

Installation

The package is hosted on PyPI so it can be installed with pip:
Command Line
1pip install hubai-sdk

Quick Start

In order to use the HubAI SDK, you first need to obtain an API key from HubAI. You can do this by signing up for a free account and generating an API key in the settings.
Python
1import os
2from hubai_sdk import HubAIClient
3
4client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
5
6# List all models
7models = client.models.list_models()
8print(f"Found {len(models)} models")
9
10# Get a specific model
11model = client.models.get_model(models[0].id)
12print(f"Model: {model.name}")
13
14# Convert a model to RVC4 format (for OAK4 devices)
15response = client.convert.RVC4(
16    path="/path/to/your/nn_archive.tar.xz",
17    name="my-converted-model",
18    target_precision="INT8",
19    quantization_data="GENERAL",
20)
21
22print(f"Converted model downloaded to: {response.downloaded_path}")
All the commands can also be run from the command line using the hubai command.
Command Line
1# Login first
2hubai login
3
4# List models
5hubai model ls
6
7# Get model info
8hubai model info <model-id-or-slug>
9
10# Convert model to RVC4 format
11hubai convert rvc4 <path-to-nn-archive.tar.xz> --name my-converted-model --target-precision INT8 --quantization-data GENERAL

Installation

The package works on Python 3.10 and above and can be installed using pip:
Command Line
1pip install hubai-sdk
Additionally, you can install the package from the source code:
Command Line
1git clone https://github.com/luxonis/hubai-sdk.git
2cd hubai-sdk
3pip install -e .

Authentication

To use the HubAI SDK, you need to create an account on HubAI and generate an API key in your team settings. Once you have the API key, you can set it as an environment variable:

Model Management

Model is the basic element of HubAI and can be managed programmatically using the HubAIClient.models namespace. You can list the models, retrieve information about a specific model, create a new model, update an existing model, and delete a model.
Python
1# Listing the models
2models = client.models.list_models(
3    tasks=["OBJECT_DETECTION"],
4    is_public=True,
5    limit=10
6)
7
8# Get model Info
9model = client.models.get_model("model-id-or-slug")
10
11# Create a new model
12new_model = client.models.create_model(
13    name="my-model",
14    license_type="MIT",
15    is_public=False,
16    description="My awesome model",
17    tasks=["OBJECT_DETECTION"]
18)
19
20# Update an existing model (pass only the fields you want to update)
21updated_model = client.models.update_model(
22    model_id,
23    license_type="Apache 2.0",
24    description="Updated description"
25)
26
27# Delete a model
28client.models.delete_model(model_id)
You have full type hints for the returned objects and you can use them to access the model properties.

Variant Management

Variant is a specific version of a model, typically distinguished by input resolution (e.g., 224x224), dataset used for training (e.g., COCO), or some smaller variation in model architecture.You can list the variants, retrieve information about a specific variant, create a new variant, and delete a variant.
Python
1# Listing the variants
2variants = client.variants.list_variants(model_id="model-id")
3
4# Get variant info
5variant = client.variants.get_variant("variant-id")
6
7new_variant = client.variants.create_variant(
8    name="my-variant",
9    model_id="model-id",
10    variant_version="1.0.0",
11    description="My first variant."
12)
13
14# Delete a variant
15client.variants.delete_variant("variant-id")

New Verison of the Variant

You can also create a new version of the variant. This is helpful if you have newer weights for the same model. New version can be created by providing the same variant name, the same model id and a new version number.
Python
1variant = client.variants.get_variant("variant-id")
2
3new_version_of_variant = client.variants.create_variant(
4    name=variant.name,
5    model_id=variant.model_id,
6    variant_version="new-version-number",
7)

Instance Management

Instance is a compiled, platform-targeted version of a Variant — the actual artifact deployed to hardware. For more information about the conversion to a platform-specific instance, see the Conversion guide.You can list the instances, retrieve information about a specific instance, create a new instance, download the instance, retrieve the files and the config of the instance, upload the file to an instance, and delete an instance.
Python
1# Listing the instances
2instances = client.instances.list_instances(model_id="model-id", variant_id="variant-id")
3
4# Get instance info
5instance = client.instances.get_instance("instance-id")
6
7# Download the instance
8downloaded_path = client.instances.download_instance("instance-id", output_dir="/path/to/output/directory")
9
10# Create a new instance
11from hubai_sdk.utils.types import ModelType
12
13instance = client.instances.create_instance(
14    name="my-instance",
15    variant_id="variant-id",
16    model_type=ModelType.ONNX,
17    input_shape=[1, 3, 288, 512]
18)
19
20# Retrieve the config of the instance
21config = client.instances.get_config("instance-id")
22
23# Retrieve the files of the instance
24files = client.instances.get_files("instance-id")
25
26# Upload a file to the instance
27client.instances.upload_file("path/to/nn_archive.tar.xz", "instance-id")
28
29# Delete an instance
30client.instances.delete_instance("instance-id")

Conversion

You can convert models to different formats using the HubAIClient.convert namespace.
Python
1# Convert a model to RVC4 format
2response = client.convert.RVC4(
3    path="/path/to/your/nn_archive.tar.xz",
4    name="my-converted-model",
5    target_precision="INT8",
6    quantization_data="GENERAL",
7)
8
9downloaded_path = response.downloaded_path
10instance = response.instance
This simple example shows how to convert a model to RVC4 format in INT8 precision using GENERAL quantization data. It will also create a HubAI Model with name my-converted-model. When conversion is finished, the converted model is downloaded to the downloaded_path and the Model Instance is returned in the instance variable.
Python
1# Convert YOLO model to RVC4 format
2response = client.convert.RVC4(
3    path="path/to/your/yolo-model.pt",
4    name="my-converted-yolo-model",
5    target_precision="INT8",
6    quantization_data="GENERAL",
7    yolo_input_shape=[512, 288],
8    yolo_class_names=["list", "of", "class", "names"],
9    yolo_version="yolov8",  # or any other YOLO version
10)
The example above demonstrates how to convert a YOLO model to the RVC4 format. You can directly provide the path to the model's .pt weights file. The input shape of the model must be specified, and you can optionally include the class names. Supplying the class names is recommended, otherwise, they will be automatically retrieved during the conversion process.For more information about the online conversion, please refer to the HubAI Online Conversion guide.