# variants

Python API: `hubai_sdk.services.variants`

Manage named and versioned variants of HubAI models.

A variant groups related model instances under a semantic version. For example, a model can have separate variants for different
input resolutions or training datasets, and each variant can have versions such as `"1.0.0"` and `"1.1.0"`.

> **Example**
> ```python
variant = client.variants.create_variant(
    "coco-640x640",
    model_id=model.id,
    variant_version="1.0.0",
    tags=["coco"],
)
instances = client.instances.list_instances(variant_id=variant.id)
```

Functions accepting an `identifier` resolve UUIDs, raw model-version slugs, and model-variant resource paths. A resource path can include a version to select one exact model version. Deleting a variant removes the resource remotely and cannot be undone through the SDK.

## Functions

| Name | Description |
| --- | --- |
| [`create_variant`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Create a versioned variant beneath a model. |
| [`create_variant_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Creates a new variant of a model. |
| [`delete_variant`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Delete a model variant from HubAI. |
| [`delete_variant_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Deletes a model variant. |
| [`get_variant`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Get one model variant by identifier. |
| [`get_variant_info_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | Returns information about a model version. |
| [`list_variants`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | List model variants visible to the authenticated team. |
| [`list_variants_cli`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | List the model versions in the HubAI. |

### function `create_variant`

```python
def create_variant(
    name: str,
    *,
    model_id: UUID | str,
    variant_version: str,
    description: str | None = None,
    repository_url: str | None = None,
    commit_hash: str | None = None,
    domain: str | None = None,
    tags: list[str] | None = None,
) -> ModelVersionResponse
```

Create a versioned variant beneath a model.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Human-readable variant name. | required |
| `model_id` | `UUID | str` | UUID of the parent model. | required |
| `variant_version` | `str` | Version string for this variant. | required |
| `description` | `str | None` | Full description of the variant. | `None` |
| `repository_url` | `str | None` | Source repository URL. | `None` |
| `commit_hash` | `str | None` | Source revision used to produce the variant. | `None` |
| `domain` | `str | None` | Application or dataset domain. | `None` |
| `tags` | `list[str] | None` | Searchable labels for the variant. | `None` |

Returns

| Type | Description |
| --- | --- |
| `ModelVersionResponse` | The created model version resource. |

Raises

| Type | Description |
| --- | --- |
| `ResourceConflictError` | If the variant already exists for the model. |
| `HubApiError` | If HubAI rejects the request for another reason. |

### function `create_variant_cli`

```python
def create_variant_cli(
    name: str,
    *,
    model_id: UUID | str,
    variant_version: str,
    description: str | None = None,
    repository_url: str | None = None,
    commit_hash: str | None = None,
    domain: str | None = None,
    tags: list[str] | None = None,
)
```

Creates a new variant of a model.

### function `delete_variant`

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

Delete a model variant from HubAI.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | Variant UUID, raw model-version slug, or a variant resource path. Include its version segment when the variant slug identifies multiple model versions. | required |

### function `delete_variant_cli`

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

Deletes a model variant.

### function `get_variant`

```python
def get_variant(identifier: UUID | str) -> ModelVersionResponse
```

Get one model variant by identifier.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `identifier` | `UUID | str` | Variant UUID, raw model-version slug, or a `<model>:<variant>[:<version>]` resource path, optionally prefixed with `<team>/`. | required |

Returns

| Type | Description |
| --- | --- |
| `ModelVersionResponse` | The resolved model version resource. |

### function `get_variant_info_cli`

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

Returns information about a model version.

### function `list_variants`

```python
def list_variants(
    model_id: UUID | str | None = None,
    name: str | None = None,
    variant_slug: str | None = None,
    variant_version: str | None = None,
    is_public: bool | None = None,
    include_model_name: bool = False,
    limit: int = 50,
    sort: str = 'updated',
    order: Order = 'desc',
) -> list[ModelVersionResponse]
```

List model variants visible to the authenticated team.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `model_id` | `UUID | str | None` | Keep variants belonging to this model UUID. | `None` |
| `name` | `str | None` | Keep variants with this name. | `None` |
| `variant_slug` | `str | None` | Keep variants with this slug. | `None` |
| `variant_version` | `str | None` | Keep variants with this version string. | `None` |
| `is_public` | `bool | None` | Filter by visibility, or leave as `None` for no filter. | `None` |
| `include_model_name` | `bool` | Resolve and populate the parent `model_name`. This performs an additional request for each returned variant. | `False` |
| `limit` | `int` | Maximum number of variants to return. | `50` |
| `sort` | `str` | [ModelVersionResponse](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) field used for sorting. | `'updated'` |
| `order` | `Order` | Sort in ascending or descending order. | `'desc'` |

Returns

| Type | Description |
| --- | --- |
| `list[ModelVersionResponse]` | A list of matching model version resources. |

### function `list_variants_cli`

```python
def list_variants_cli(
    model_id: UUID | str | None = None,
    name: str | None = None,
    variant_slug: str | None = None,
    variant_version: str | None = None,
    is_public: bool | 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 versions in the HubAI.

## Module Attributes

| Name | Type | Description |
| --- | --- | --- |
| [`app`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) |  |  |
| [`VARIANT_INFO_KEYS`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | `list[str]` |  |
| [`VARIANT_LIST_KEYS`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | `list[str]` |  |
| [`VARIANT_LIST_KEYS_WITH_MODEL`](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/variants.md) | `list[str]` |  |

### variable `app`

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

### constant `VARIANT_INFO_KEYS`

```python
VARIANT_INFO_KEYS: list[str] = [
    'model_name',
    'name',
    'slug',
    'version',
    'id',
    'model_id',
    'created',
    'updated',
    'platforms',
    'exportable_to',
    'is_public',
]
```

### constant `VARIANT_LIST_KEYS`

```python
VARIANT_LIST_KEYS: list[str] = ['name', 'version', 'id', 'platforms']
```

### constant `VARIANT_LIST_KEYS_WITH_MODEL`

```python
VARIANT_LIST_KEYS_WITH_MODEL: list[str] = [
    'model_name',
    'name',
    'version',
    'id',
    'platforms',
]
```
