# instances

Python API: `hubai_sdk.services.instances`

Manage concrete model artifacts and their files.

An instance belongs to one model variant and represents a specific artifact format, for example ONNX input or an RVC4 export. The
service supports listing and creating instances, uploading source files, reading NN Archive configuration, and downloading output
files.

 * `Download behavior:`:
   [download_instance](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md)
   writes all files associated with an instance. If `output_dir` is omitted it creates a directory named after the instance slug
   in the current working directory. Existing destination files are reused unless `force=True`.

> **Example**
> ```python
from hubai_sdk.utils.types import ModelType

instance = client.instances.create_instance(
    "network",
    variant_id=variant.id,
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 640, 640],
)
client.instances.upload_file("network.onnx", instance.id)
```

> **Note**
> Most users do not need to create and upload instances manually. The functions in [hubai_sdk.services.convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md) coordinate these steps for a complete hosted conversion.

## Functions

| Name | Description |
| --- | --- |
| [`create_instance`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Create a model artifact beneath a variant. |
| [`create_instance_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Creates a new model instance. |
| [`delete_instance`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Delete a model instance from HubAI. |
| [`delete_instance_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Deletes a model instance. |
| [`download_instance`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Download every file attached to a model instance. |
| [`download_instance_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Downloads files from a model instance. |
| [`get_config`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Return the NN Archive configuration of a model instance. |
| [`get_config_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Returns the configuration of a model instance. |
| [`get_files`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Return metadata for files attached to a model instance. |
| [`get_files_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Returns the files of a model instance. |
| [`get_instance`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Get one model instance by UUID, slug, or resource path. |
| [`get_instance_info_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Returns information about a model instance. |
| [`list_instances`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | List model instances visible to the authenticated team. |
| [`list_instances_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | List the model instances in the HubAI. |
| [`upload_file`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Upload a file directly to storage for a model instance. |
| [`upload_file_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Uploads a file to a model instance using async upload. |
| [`upload_quantization_zip`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | Upload a custom calibration archive for an export job. |

### function `create_instance`

```python
def create_instance(
    name: str,
    *,
    variant_id: UUID | str,
    model_type: ModelType,
    parent_id: UUID | str | None = None,
    quantization_mode: QuantizationMode | None = None,
    quantization_data: QuantizationData | None = None,
    tags: list[str] | None = None,
    input_shape: list[int] | None = None,
    is_deployable: bool | None = None,
    yolo_version: YoloVersion | None = None,
) -> ModelInstanceResponse
```

Create a model artifact beneath a variant.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Human-readable instance name. | required |
| `variant_id` | `UUID | str` | UUID of the model variant that owns this instance. | required |
| `model_type` | `ModelType` | Source or exported artifact type. | required |
| `parent_id` | `UUID | str | None` | Source instance UUID when this instance is an export. | `None` |
| `quantization_mode` | `QuantizationMode | None` | Quantization mode for the model. Must be one of `INT8_STANDARD`, `INT8_ACCURACY_FOCUSED`, `INT8_INT16_MIXED`, `INT8_INT16_MIXED_ACCURACY_FOCUSED`, or `FP16_STANDARD`. `INT8_STANDARD` is standard INT8 quantization with calibration for optimal performance and model size. `INT8_ACCURACY_FOCUSED` is INT8 quantization with calibration that may improve accuracy without reducing performance or increasing model size, depending on the model. `INT8_INT16_MIXED` uses 8-bit weights and 16-bit activations across all layers for improved numeric stability and accuracy at the cost of performance and model size. `INT8_INT16_MIXED_ACCURACY_FOCUSED` is a mixed INT8 and INT16 calibration-based mode that prioritizes accuracy over throughput. `FP16_STANDARD` is FP16 quantization without calibration for models that require higher accuracy and numeric stability at the cost of performance and model size. | `None` |
| `quantization_data` | `QuantizationData | None` | Quantization data for the model. This can be one of the predefined domains `DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `CUSTOM`, or `UNKNOWN`, or a dataset ID. For conversion helpers, pass the local `.zip` path itself instead of `CUSTOM`; the SDK normalizes that input before instance creation. | `None` |
| `tags` | `list[str] | None` | Tags for the model instance. | `None` |
| `input_shape` | `list[int] | None` | Input shape for the model instance. | `None` |
| `is_deployable` | `bool | None` | Whether the model instance is deployable. | `None` |
| `yolo_version` | `YoloVersion | None` | YOLO version for the model instance if it is a YOLO model. | `None` |

Returns

| Type | Description |
| --- | --- |
| `ModelInstanceResponse` | The created model instance resource. |

### function `create_instance_cli`

```python
def create_instance_cli(
    name: str,
    *,
    variant_id: UUID | str,
    model_type: ModelType,
    parent_id: UUID | str | None = None,
    quantization_mode: QuantizationMode | None = None,
    quantization_data: QuantizationData | None = None,
    tags: list[str] | None = None,
    input_shape: list[int] | None = None,
    is_deployable: bool | None = None,
    yolo_version: YoloVersion | None = None,
)
```

Creates a new model instance.

### function `delete_instance`

```python
def delete_instance(identifier: UUID | str)
```

Delete a model instance from HubAI.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | The model instance ID, raw slug, or exact instance resource path. | required |

### function `delete_instance_cli`

```python
def delete_instance_cli(identifier: UUID | str)
```

Deletes a model instance.

### function `download_instance`

```python
def download_instance(
    identifier: UUID | str,
    output_dir: str | None = None,
    force: bool = False,
    model_type: ModelType | None = None,
) -> Path
```

Download every file attached to a model instance.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | When `model_type` is omitted, the ID, raw slug, or `<model>:<variant>:<instance-hash>` resource path, optionally prefixed with `<team>/`, of the instance to download. When `model_type` is provided, the model-version ID, raw model-version slug, or `<model>:<variant>[:<version>]` resource path, optionally prefixed with `<team>/`, whose instance should be downloaded. | required |
| `output_dir` | `str | None` | Directory path to save the downloaded files. If not specified, the downloader creates a directory named after the model instance slug under the current working directory. | `None` |
| `force` | `bool` | Whether to force download the files even if they already exist. | `False` |
| `model_type` | `ModelType | None` | Select an instance of this type from the identified variant. The match must be unique. | `None` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Path to the downloaded file. When the instance has multiple files, this is the last file processed. |

Raises

| Type | Description |
| --- | --- |
| `ResourceNotFoundError` | If `identifier` cannot be resolved. |
| `InputError` | If `model_type` is provided and no instance, or more than one instance, matches it. |
| `HubApiError` | If the instance has no files or a download fails. |

### function `download_instance_cli`

```python
def download_instance_cli(
    identifier: UUID | str,
    output_dir: str | None = None,
    force: bool = False,
    model_type: ModelType | None = None,
)
```

Downloads files from a model instance.

### function `get_config`

```python
def get_config(identifier: UUID | str) -> ArchiveConfigurationResponse
```

Return the NN Archive configuration of a model instance.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | The model instance ID, raw slug, or exact instance resource path. | required |

Returns

| Type | Description |
| --- | --- |
| `ArchiveConfigurationResponse` | The NN archive configuration for the model instance. |

### function `get_config_cli`

```python
def get_config_cli(identifier: UUID | str)
```

Returns the configuration of a model instance.

### function `get_files`

```python
def get_files(identifier: UUID | str) -> list[ModelInstanceFileResponse]
```

Return metadata for files attached to a model instance.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | The model instance ID, raw slug, or exact instance resource path. | required |

Returns

| Type | Description |
| --- | --- |
| `list[ModelInstanceFileResponse]` | File metadata for the model instance. |

### function `get_files_cli`

```python
def get_files_cli(identifier: UUID | str)
```

Returns the files of a model instance.

### function `get_instance`

```python
def get_instance(identifier: UUID | str) -> ModelInstanceResponse
```

Get one model instance by UUID, slug, or resource path.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | The model instance ID, raw slug, or `<model>:<variant>:<instance-hash>` resource path, optionally prefixed with `<team>/`. | required |

Returns

| Type | Description |
| --- | --- |
| `ModelInstanceResponse` | The resolved model instance resource. |

### function `get_instance_info_cli`

```python
def get_instance_info_cli(identifier: UUID | str)
```

Returns information about a model instance.

### function `list_instances`

```python
def list_instances(
    *,
    platforms: list[ModelType] | None = None,
    search: str | None = None,
    model_id: UUID | str | None = None,
    variant_id: UUID | str | None = None,
    model_type: ModelType | None = None,
    parent_id: UUID | str | None = None,
    model_class: ModelClass | None = None,
    name: str | None = None,
    hash: str | None = None,
    status: Status | None = None,
    is_public: bool | None = None,
    compression_level: Literal[0, 1, 2, 3, 4, 5] | None = None,
    optimization_level: Literal[-100, 0, 1, 2, 3, 4] | None = None,
    include_model_name: bool = False,
    limit: int = 50,
    sort: str = 'updated',
    order: Order = 'desc',
) -> list[ModelInstanceResponse]
```

List model instances visible to the authenticated team.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `platforms` | `list[ModelType] | None` | Filter the listed model instances by platform. | `None` |
| `search` | `str | None` | Search the listed model instances by a free-text query. | `None` |
| `model_id` | `UUID | str | None` | Filter the listed model instances by model ID. | `None` |
| `variant_id` | `UUID | str | None` | Filter the listed model instances by variant ID. | `None` |
| `model_type` | `ModelType | None` | Filter the listed model instances by model type. | `None` |
| `parent_id` | `UUID | str | None` | Filter the listed model instances by parent ID. | `None` |
| `model_class` | `ModelClass | None` | Filter the listed model instances by model class. | `None` |
| `name` | `str | None` | Filter the listed model instances by name. | `None` |
| `hash` | `str | None` | Filter the listed model instances by hash. | `None` |
| `status` | `Status | None` | Filter the listed model instances by status. | `None` |
| `is_public` | `bool | None` | Filter the listed model instances by visibility. | `None` |
| `compression_level` | `Literal[0, 1, 2, 3, 4, 5] | None` | Filter the listed model instances by compression level. Only relevant for Hailo models. | `None` |
| `optimization_level` | `Literal[-100, 0, 1, 2, 3, 4] | None` | Filter the listed model instances by optimization level. Only relevant for Hailo models. | `None` |
| `include_model_name` | `bool` | If `True`, include the model name and model variant name in the response. Otherwise, [ModelInstanceResponse.model_name](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) and [ModelInstanceResponse.model_variant_name](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) are `None`. Enabling this performs two additional API requests per result. | `False` |
| `limit` | `int` | Maximum number of model instances to return. | `50` |
| `sort` | `str` | Field to sort the model instances by. It should be a field name from [ModelInstanceResponse](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md), such as `"name"`, `"id"`, or `"updated"`. | `'updated'` |
| `order` | `Order` | Sort order. Must be `"asc"` or `"desc"`. | `'desc'` |

Returns

| Type | Description |
| --- | --- |
| `list[ModelInstanceResponse]` | A list of matching model instance resources. |

### function `list_instances_cli`

```python
def list_instances_cli(
    *,
    platforms: list[ModelType] | None = None,
    search: str | None = None,
    model_id: UUID | str | None = None,
    variant_id: UUID | str | None = None,
    model_type: ModelType | None = None,
    parent_id: UUID | str | None = None,
    model_class: ModelClass | None = None,
    name: str | None = None,
    hash: str | None = None,
    status: Status | None = None,
    is_public: bool | None = None,
    compression_level: Literal[0, 1, 2, 3, 4, 5] | None = None,
    optimization_level: Literal[-100, 0, 1, 2, 3, 4] | None = None,
    include_model_name: bool = False,
    limit: int = 50,
    sort: str = 'updated',
    order: Order = 'desc',
    field: Annotated[list[str] | None, Parameter(name=['--field', '-f'])] = None,
)
```

List the model instances in the HubAI.

### function `upload_file`

```python
def upload_file(file_path: str, identifier: UUID | str)
```

Upload a file directly to storage for a model instance.

This function initiates an async upload by first obtaining a signed upload policy from the server, then uploading the file directly to cloud storage.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `file_path` | `str` | Path to the file to upload. | required |
| `identifier` | `UUID | str` | The model instance ID, raw slug, or exact instance resource path. | required |

Raises

| Type | Description |
| --- | --- |
| `FileNotFoundError` | If `file_path` does not exist. |
| `ResourceNotFoundError` | If `identifier` cannot be resolved. |
| `HubApiError` | If the signed upload or its asynchronous job fails. |

### function `upload_file_cli`

```python
def upload_file_cli(file_path: str, identifier: UUID | str)
```

Uploads a file to a model instance using async upload.

### function `upload_quantization_zip`

```python
def upload_quantization_zip(file_path: str, job_id: UUID | str)
```

Upload a custom calibration archive for an export job.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `file_path` | `str` | Path to a local ZIP archive containing calibration inputs. | required |
| `job_id` | `UUID | str` | Export job UUID returned by HubAI. | required |

Raises

| Type | Description |
| --- | --- |
| `FileNotFoundError` | If `file_path` does not exist. |
| `InputError` | If the file does not have a `.zip` extension. |
| `HubApiError` | If HubAI cannot issue or complete the upload. |

## Module Attributes

| Name | Type | Description |
| --- | --- | --- |
| [`app`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) |  |  |
| [`INSTANCE_INFO_KEYS`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | `list[str]` |  |
| [`INSTANCE_LIST_KEYS`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | `list[str]` |  |
| [`INSTANCE_LIST_KEYS_WITH_MODEL`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md) | `list[str]` |  |

### variable `app`

```python
app = App(
    name='instance',
    help='Model instances Interactions',
    group='Resource Management',
)
```

### constant `INSTANCE_INFO_KEYS`

```python
INSTANCE_INFO_KEYS: list[str] = ...
```

### constant `INSTANCE_LIST_KEYS`

```python
INSTANCE_LIST_KEYS: list[str] = [
    'slug',
    'id',
    'model_type',
    'is_nn_archive',
    'model_precision_type',
]
```

### constant `INSTANCE_LIST_KEYS_WITH_MODEL`

```python
INSTANCE_LIST_KEYS_WITH_MODEL: list[str] = [
    'model_name',
    'model_variant_name',
    'slug',
    'id',
    'model_type',
    'is_nn_archive',
    'model_precision_type',
]
```
