# 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

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

Parameters

 * `name` (`str`): Human-readable instance name.
 * `variant_id` (`UUID | str`): UUID of the model variant that owns this instance.
 * `model_type` (`ModelType`): Source or exported artifact type.
 * `parent_id` (`UUID | str | None`): Source instance UUID when this instance is an export.
 * `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.
 * `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.
 * `tags` (`list[str] | None`): Tags for the model instance.
 * `input_shape` (`list[int] | None`): Input shape for the model instance.
 * `is_deployable` (`bool | None`): Whether the model instance is deployable.
 * `yolo_version` (`YoloVersion | None`): YOLO version for the model instance if it is a YOLO model.

Returns

 * `ModelInstanceResponse`: The created model instance resource.

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

### delete_instance

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

Delete a model instance from HubAI.

Parameters

 * `identifier` (`UUID | str`): The model instance ID or slug.

### delete_instance_cli

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

Deletes a model instance.

### download_instance

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

Download every file attached to a model instance.

Parameters

 * `identifier` (`UUID | str`): The model instance ID or slug.
 * `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.
 * `force` (`bool`): Whether to force download the files even if they already exist.

Returns

 * `Path`: Path to the downloaded file. When the instance has multiple files, this is the last file processed.

Raises

 * `ResourceNotFoundError`: If `identifier` cannot be resolved.
 * `HubApiError`: If the instance has no files or a download fails.

### download_instance_cli

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

Downloads files from a model instance.

### get_config

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

Return the NN Archive configuration of a model instance.

Parameters

 * `identifier` (`UUID | str`): The model instance ID or slug.

Returns

 * `ArchiveConfigurationResponse`: The NN archive configuration for the model instance.

### get_config_cli

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

Returns the configuration of a model instance.

### get_files

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

Return metadata for files attached to a model instance.

Parameters

 * `identifier` (`UUID | str`): The model instance ID or slug.

Returns

 * `list[ModelInstanceFileResponse]`: File metadata for the model instance.

### get_files_cli

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

Returns the files of a model instance.

### get_instance

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

Get one model instance by UUID or slug.

Parameters

 * `identifier` (`UUID | str`): The model instance ID or slug.

Returns

 * `ModelInstanceResponse`: The resolved model instance resource.

### get_instance_info_cli

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

Returns information about a model instance.

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

Parameters

 * `platforms` (`list[ModelType] | None`): Filter the listed model instances by platform.
 * `search` (`str | None`): Search the listed model instances by a free-text query.
 * `model_id` (`UUID | str | None`): Filter the listed model instances by model ID.
 * `variant_id` (`UUID | str | None`): Filter the listed model instances by variant ID.
 * `model_type` (`ModelType | None`): Filter the listed model instances by model type.
 * `parent_id` (`UUID | str | None`): Filter the listed model instances by parent ID.
 * `model_class` (`ModelClass | None`): Filter the listed model instances by model class.
 * `name` (`str | None`): Filter the listed model instances by name.
 * `hash` (`str | None`): Filter the listed model instances by hash.
 * `status` (`Status | None`): Filter the listed model instances by status.
 * `is_public` (`bool | None`): Filter the listed model instances by visibility.
 * `compression_level` (`Literal[0, 1, 2, 3, 4, 5] | None`): Filter the listed model instances by compression level. Only relevant for Hailo models.
 * `optimization_level` (`Literal[-100, 0, 1, 2, 3, 4] | None`): Filter the listed model instances by optimization level. Only relevant for Hailo models.
 * `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.
 * `limit` (`int`): Maximum number of model instances to return.
 * `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"`.
 * `order` (`Order`): Sort order. Must be `"asc"` or `"desc"`.

Returns

 * `list[ModelInstanceResponse]`: A list of matching model instance resources.

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

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

Parameters

 * `file_path` (`str`): Path to the file to upload.
 * `identifier` (`UUID | str`): The model instance ID or slug.

Raises

 * `FileNotFoundError`: If `file_path` does not exist.
 * `ResourceNotFoundError`: If `identifier` cannot be resolved.
 * `HubApiError`: If the signed upload or its asynchronous job fails.

### upload_file_cli

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

Uploads a file to a model instance using async upload.

### upload_quantization_zip

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

Upload a custom calibration archive for an export job.

Parameters

 * `file_path` (`str`): Path to a local ZIP archive containing calibration inputs.
 * `job_id` (`UUID | str`): Export job UUID returned by HubAI.

Raises

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

## Attributes

### app

### INSTANCE_INFO_KEYS

### INSTANCE_LIST_KEYS

### INSTANCE_LIST_KEYS_WITH_MODEL