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

## 2. Convert the model in HubAI

Continue with [Quick Conversion](https://docs.luxonis.com/cloud/hubai/quick-conversion.md) 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](https://docs.luxonis.com/cloud/hubai/model-registry/upload-download.md).

> **Need more control?**
> If you want deeper conversion settings or more detail about the managed workflow for uploaded models, see
> [Detailed Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md)
> .

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