OverviewHardwareSoftwareCloud
Getting started
Fleet Management
AI & Models
Tutorials
Platform Integration
Organization
Advanced

ON THIS PAGE

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

HubAI SDK

Overview

The hubai-sdk package provides programmatic access to the AI & Models area of Luxonis Hub. Use it to manage models, variants, and instances, or to trigger online conversion from Python or the command line.Key capabilities:
  • Manage models, variants, and instances in Hub AI
  • Run online conversion for RVC2, RVC3, RVC4, and Hailo targets
  • Use the same workflows from Python scripts or the hubai CLI
  • Access advanced conversion options that are not exposed in the Hub UI

Installation

The package works on Python 3.10 and above.
Command Line
1pip install hubai-sdk
You can also install it from source:
Command Line
1git clone https://github.com/luxonis/hubai-sdk.git
2cd hubai-sdk
3pip install -e .

Authentication

Create an API key in your team settings, then expose it as an environment variable:
Command Line
1export HUBAI_API_KEY="your-api-key"
Initialize the client in Python:
Python
1import os
2
3from hubai_sdk import HubAIClient
4
5client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
All SDK workflows are also available through the hubai CLI. Start by logging in:
Command Line
1hubai login

Quick Start

The example below shows a minimal end-to-end flow: list a few models and run an online conversion.
Python
1models = client.models.list_models(limit=5)
2print(f"Found {len(models)} models")
3
4response = client.convert.RVC4(
5    path="path/to/model.onnx",
6    name="my-converted-model",
7)
8
9print(f"Converted model downloaded to: {response.downloaded_path}")

Model Management

Model is the basic element of the AI & Models area 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    new_model.id,
23    license_type="Apache 2.0",
24    description="Updated description"
25)
26
27# Delete a model
28client.models.delete_model(new_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    quantization_mode="INT8_STANDARD",
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 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    quantization_mode="INT8_STANDARD",
6    quantization_data="GENERAL",
7    yolo_input_shape=[512, 288],
8    yolo_class_names=["list", "of", "class", "names"],
9    yolo_version="yolov8",  # optional override
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. You do not need to set yolo_version explicitly. If it is omitted, the backend attempts to detect the version automatically from the PyTorch model file, but the file still needs to come from one of the supported YOLO versions. The current explicit yolo_version values exposed by the SDK are yolov5, yolov6r1, yolov6r3, yolov6r4, yolov7, yolov8, yolov9, yolov10, yolov11, yolov12, yolov26, and goldyolo. For the exact set of supported YOLO families, variants, and current limitations, see the upstream supported models table.For more information about online conversion, please refer to the Hub Online Conversion guide.