Use custom models on HubAI

Use this tutorial when you want the shortest path from a prepared model uploaded to HubAI to seeing real model output on an OAK device.alidate a custom mod

Do not start with Viewer for this workflow

OAK Viewer and the default visualizer are useful for trying built-in models, checking streams, and adjusting visualization or depth settings. They are not the editable path for validating a custom HubAI model workflow. For that, start with oak-examples so you control the model reference, authentication, and output handling.

When this tutorial fits

This flow works best for models that can run with the generic-example app: a single-image input model with a compatible parser path. If your model needs custom post-processing or multiple heads, use this tutorial to validate conversion first, then move to a custom example or app.

1. Prepare and upload the model

First make sure the model is ready for HubAI and uploaded to the Model Registry.Start with Model Preparation to prepare the model files and model card in a supported format.Then follow Upload/Download to add the model to HubAI. During upload:

Choose the right upload format

For custom YOLO models use the YOLO upload path with PyTorch (.pt) weights. For most other custom models, export to ONNX and use the Custom upload path. ONNX is the general interchange format for non-YOLO models and usually preserves the original architecture, while the YOLO-specific path standardizes outputs for native parsing and more on-device post-processing. See Conversion to ONNX for more detail.

Once the base model is uploaded, continue with conversion.

2. Convert the model in HubAI

Continue with Quick Conversion for the fastest path to a deployable RVC output. When converting, enable Add to Model so the converted output stays attached to the uploaded model entry.The output of the finished conversion step:

a converted model available in HubAI
a copyable HubAI model reference that you can pass to generic-example

The easiest handoff is to keep the converted result attached to a Model Registry entry so you can reference it later from HubAI or oak-examples.After that, copy the model reference from the Model Registry page as shown in Upload/Download.

Need more control?

If you want deeper conversion settings or more detail about the managed workflow for uploaded models, see Detailed Conversion.

3. Create a team API key

If the model is public, you can skip this step. If it is team-owned and private, create a key from API Keys.For local scripts such as generic-example, prefer setting the key at runtime with DEPTHAI_HUB_API_KEY instead of hardcoding it in source files. The recommended handling patterns are documented in API Key Good Practices.

4. Run `generic-example` and inspect the output

The generic example from oak-examples is the fastest editable path for validating a model coming from HubAI. It expects a HubAI model reference through --model, and for private models it can read the key from DEPTHAI_HUB_API_KEY or --api_key.

Command Line

1git clone --depth 1 --branch main https://github.com/luxonis/oak-examples.git
2cd oak-examples/neural-networks/generic-example
3python3 -m venv venv
4source venv/bin/activate
5pip install -r requirements.txt
6export DEPTHAI_HUB_API_KEY="<YOUR_TEAM_API_KEY>"
7python3 main.py --model "<YOUR_MODEL_REFERENCE>"

On Windows, use python instead of python3, activate the virtual environment with venv\\Scripts\\activate, and set the variable with set DEPTHAI_HUB_API_KEY=<YOUR_TEAM_API_KEY>.When the script starts successfully, it downloads the model from HubAI, creates the pipeline, and gives you the viewer instructions for the local visualizer session. Use that session to confirm the model output is correct on device.Common variations:

Add --overlay_mode for array outputs such as segmentation or depth-like maps.
Add --media_path <PATH_TO_IMAGE_OR_VIDEO> if you want to test on a file instead of live camera input.
Pass --api_key "<YOUR_TEAM_API_KEY>" if you prefer not to export DEPTHAI_HUB_API_KEY.

ON THIS PAGE

Use custom models on HubAIView as Markdown

1. Prepare and upload the model

2. Convert the model in HubAI

3. Create a team API key

4. Run generic-example and inspect the output

Use custom models on HubAI

4. Run `generic-example` and inspect the output