# 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.

To get started quickly, we've made videos on conversion steps:

The same process as in the videos is described below in more detail.

## 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`.