# Use custom models on HubAI

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

> **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](https://docs.luxonis.com/cloud/hubai/model-registry/preparation.md) to prepare the model files and
model card in a supported format.

Then follow [Upload/Download](https://docs.luxonis.com/cloud/hubai/model-registry/upload-download.md) 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](https://docs.luxonis.com/software-v3/ai-inference/conversion/onnx-conversion.md)
> for more detail.

Once the base model is uploaded, continue with conversion in the Model Registry workflow.

## 2. Convert the model in HubAI

Continue with [Detailed Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) to convert the
uploaded model into a deployable RVC output without uploading it again.

The output of the finished conversion step:

 * a converted model instance attached to the existing HubAI model entry
 * 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](https://docs.luxonis.com/cloud/hubai/model-registry/upload-download.md).

> **Quick Conversion is still available**
> [Quick Conversion](https://docs.luxonis.com/cloud/hubai/quick-conversion.md)
> is still useful for one-off jobs, especially when you want to upload, convert, and download a model in one place. In this
tutorial it is not the primary path because the model has already been uploaded to HubAI.

## 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](https://docs.luxonis.com/cloud/api/api-keys.md).

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](https://docs.luxonis.com/software-v3/oak-apps/apikey-good-practices.md).

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

The [generic example from oak-examples](https://github.com/luxonis/oak-examples/tree/main/neural-networks/generic-example) 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.

```bash
git clone --depth 1 --branch main https://github.com/luxonis/oak-examples.git
cd oak-examples/neural-networks/generic-example
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export DEPTHAI_HUB_API_KEY="<YOUR_TEAM_API_KEY>"
python3 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.