# convert Python API: `hubai_sdk.services.convert` Run hosted model conversion and download deployable artifacts. The target-specific helpers [RVC2](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md), [RVC3](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md), [RVC4](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md), and [Hailo](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md) are the recommended conversion API. Each helper prepares target options and delegates to [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md), which coordinates the complete HubAI workflow: 1. Read model metadata from a model file, YAML config, or NN Archive. 2. Create or reuse model and variant resources. 3. Upload the source model as an instance. 4. Start an export job and wait for it to finish. 5. Download the exported instance. > **Example** > Convert an ONNX model for RVC4 with HubAI's general calibration data. ```python result = client.convert.RVC4( path="detector.onnx", name="detector", quantization_mode="INT8_STANDARD", quantization_data="GENERAL", ) print(result.downloaded_path) ``` * `Input configuration:`: `path` may point to a model file, an NN Archive, or a YAML configuration. Additional `opts` override values loaded from that configuration. A dictionary is usually easiest in Python; the flat list form exists for the command-line interface. * `Resource reuse:`: Pass `model_id` or `variant_id` to attach the conversion to existing resources. Without them, [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md) creates resources and reuses a model with the same slug if one already exists. * `Quantization:`: RVC4 and Hailo accept a built-in calibration domain, a dataset ID beginning with `aid_`, or a local ZIP file. Passing a ZIP path uploads it for the export job. RVC2 and RVC3 ignore quantization inputs because those helpers expose their platform-specific precision controls instead. ## Conversion parameters The conversion API accepts parameters for the input, HubAI resources, and the selected target. The function signatures below provide exact types and defaults; this overview groups the parameters by purpose. ### General parameters * `path`: Input model file, YAML configuration, or NN Archive. * `tool_version`: Version of the conversion tool. * `quantization_mode`: RVC4 quantization mode. `FP16_STANDARD` skips calibration. * `output_dir`: Directory for downloaded output files. If omitted, the downloader creates a directory named after the exported instance slug in the current working directory. ### YOLO parameters * `yolo_input_shape`: YOLO input shape. It defaults to `[640, 640]` when omitted or invalid. * `yolo_version`: YOLO version, such as `"yolov8"`. Prefer auto-detection and set this only when detection fails. * `yolo_class_names`: Model class names. ### Model parameters These parameters create a HubAI Model resource unless `model_id` is supplied. * `model_id`: ID of an existing model to reuse. * `name`: Model name. It defaults to the configured or input model name. * `license_type`: License type for the model. * `is_public`: Whether the model is public, private, or team-scoped. * `description` and `description_short`: Full and short model descriptions. The short description defaults to `""`. * `architecture_id`: Model architecture ID. * `tasks`: Tasks the model supports. * `links`: Additional links for the model. * `is_yolo`: Whether the model is a YOLO model. ### Model variant parameters * `model_id`: ID of an existing model to which to add a variant. * `variant_version`: Version of the model variant. HubAI uses the next version automatically when it is omitted. * `variant_description`: Full variant description. * `repository_url` and `commit_hash`: Related repository URL and commit. * `domain`: Variant domain. * `variant_tags`: Variant tags. ### Model instance parameters * `variant_id`: ID of an existing model variant to reuse. * `quantization_data`: Predefined calibration domain, an `aid_` dataset ID, or a local custom `.zip` path. Pass the ZIP path rather than `CUSTOM`. * `max_quantization_images`: Maximum number of images for quantization. * `instance_tags`: Model-instance tags. * `input_shape`: Model input shape. * `is_deployable`: Whether the model instance is deployable. ### RVC2 parameters * `mo_args`: Arguments for the Model Optimizer. * `compile_tool_args`: Arguments for the BLOB compiler. * `compress_to_fp16`: Whether to compress model weights to FP16. Defaults to `True`. * `number_of_shaves`: Number of shaves to use. Defaults to `8`. * `superblob`: Whether to create a superblob. Defaults to `True`; disable it to use legacy RVC2 conversion. ### RVC3 parameters * `mo_args`: Arguments for the Model Optimizer. * `compile_tool_args`: Arguments for the BLOB compiler. * `compress_to_fp16`: Whether to compress model weights to FP16. Defaults to `True`. * `pot_target_device`: Target device for post-training optimization. Defaults to `"VPU"`. ### RVC4 parameters * `snpe_onnx_to_dlc_args`: Arguments for `snpe-onnx-to-dlc`. * `snpe_dlc_quant_args`: Arguments for `snpe-dlc-quant`. * `snpe_dlc_graph_prepare_args`: Arguments for `snpe-dlc-graph-prepare`. * `use_per_channel_quantization`: Whether to use per-channel quantization. Defaults to `True`. * `use_per_row_quantization`: Whether to use per-row quantization. Defaults to `False`. * `htp_socs`: HTP SoCs to use. Defaults to `["sm8550"]`. ### Hailo parameters * `optimization_level`: Optimization level. Defaults to `2`. * `compression_level`: Compression level. Defaults to `2`. * `batch_size`: Quantization batch size. Defaults to `8`. * `alls`: Additional ALLS parameters. ## Functions ### convert ```python def convert(target: Target, opts: list[str] | None = None, /, *, path: str, name: str | None = None, license_type: License = 'undefined', is_public: bool | None = False, description_short: str = '', description: str | None = None, architecture_id: UUID | str | None = None, tasks: list[Task] | None = None, links: list[str] | None = None, is_yolo: bool = False, model_id: UUID | str | None = None, variant_version: str | None = None, variant_description: str | None = None, repository_url: str | None = None, commit_hash: str | None = None, quantization_mode: QuantizationMode | None = None, domain: str | None = None, variant_tags: list[str] | None = None, variant_id: UUID | str | None = None, quantization_data: QuantizationData | PathType | None = None, max_quantization_images: int | None = None, instance_tags: list[str] | None = None, input_shape: list[int] | None = None, is_deployable: bool | None = None, output_dir: str | None = None, tool_version: str | None = None, yolo_input_shape: list[int] | None = None, yolo_version: YoloVersion | None = None, yolo_class_names: list[str] | None = None) -> ConvertResponse: ``` Starts the online conversion process. Parameters * `target` (`Target`): Target platform. * `opts` (`list[str] | None`): Additional options for the conversion process. * `path` (`str`): Path to the input model file, NN Archive, or YAML configuration file. * `name` (`str | None`): Model name. If not specified, the name is taken from the configuration file or the model file. * `license_type` (`License`): License type for a newly created model. * `is_public` (`bool | None`): Whether the model is public (`True`), private (`False`), or team-scoped (`None`). * `description_short` (`str`): Short description of the model. Defaults to `""`. * `description` (`str | None`): Full description of the model. * `architecture_id` (`UUID | str | None`): Architecture ID. * `tasks` (`list[Task] | None`): Tasks the model supports. * `links` (`list[str] | None`): Additional links for the model. * `is_yolo` (`bool`): Whether the model is a YOLO model. * `model_id` (`UUID | str | None`): ID of an existing model resource. If specified, that model is used instead of creating a new one. * `variant_version` (`str | None`): Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`. * `variant_description` (`str | None`): Full description of the model variant. * `repository_url` (`str | None`): URL of the repository. * `commit_hash` (`str | None`): Commit hash. * `quantization_mode` (`QuantizationMode | None`): Quantization mode to use during RVC4 conversion. 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. `FP16_STANDARD` skips calibration. * `domain` (`str | None`): Domain of the model variant. * `variant_tags` (`list[str] | None`): Tags for the model variant. * `variant_id` (`UUID | str | None`): ID of an existing model version resource. If specified, that version is used instead of creating a new one. * `quantization_data` (`QuantizationData | PathType | None`): Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file. Pass the `.zip` path itself instead of `CUSTOM`; the SDK normalizes local zip inputs automatically. * `max_quantization_images` (`int | None`): Maximum number of images to use for quantization. * `instance_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. * `output_dir` (`str | None`): Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory. * `tool_version` (`str | None`): Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version. * `yolo_input_shape` (`list[int] | None`): Input shape for YOLO models. It defaults to `[640, 640]` when omitted or invalid. * `yolo_version` (`YoloVersion | None`): YOLO version, such as `"yolov8"`. Usually omit this to use auto-detection; specify it only if detection fails. * `yolo_class_names` (`list[str] | None`): Class names for YOLO models. Returns * `ConvertResponse`: Conversion result containing the downloaded output path, export job, and exported model instance. ### Hailo ```python def Hailo(path: PathType, optimization_level: Literal[-100, 0, 1, 2, 3, 4] = 2, compression_level: Literal[0, 1, 2, 3, 4, 5] = 2, batch_size: int = 8, alls: list[str] | None = None, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ``` Convert a model to Hailo format. Parameters * `path` (`PathType`): Path to the model file to convert. * `optimization_level` (`Literal[-100, 0, 1, 2, 3, 4]`): Optimization level for the conversion. Defaults to `2`. * `compression_level` (`Literal[0, 1, 2, 3, 4, 5]`): Compression level for the conversion. Defaults to `2`. * `batch_size` (`int`): Batch size for quantization. Defaults to `8`. * `alls` (`list[str] | None`): Additional Hailo ALLS parameters to apply during conversion. * `opts` (`Kwargs | list[str] | None`): Additional conversion options. These can override config values. * `name`: Model name. If not specified, the name is taken from the configuration file or the model file. * `license_type`: License type. * `is_public`: Whether the model is public (`True`), private (`False`), or team-scoped (`None`). * `description_short`: Short description of the model. * `description`: Full description of the model. * `architecture_id`: Architecture ID. * `tasks`: Tasks this model supports. * `links`: Links to related resources. * `is_yolo`: Whether the model is a YOLO model. * `model_id`: ID of an existing model resource. If specified, that model is used instead of creating a new one. * `variant_version`: Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`. * `variant_description`: Full description of the model variant. * `repository_url`: URL of the repository. * `commit_hash`: Commit hash. * `quantization_mode`: Quantization mode. * `quantization_data`: Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file. * `max_quantization_images`: Maximum number of quantization images. * `domain`: Domain of the model. * `variant_tags`: Tags for the model variant. * `variant_id`: ID of an existing model version resource. If specified, that version is used instead of creating a new one. * `input_shape`: Input shape for the model instance. * `is_deployable`: Whether the model instance is deployable. * `output_dir`: Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory. * `tool_version`: Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version. * `yolo_input_shape`: Input shape for YOLO models. * `yolo_version`: YOLO version. * `yolo_class_names`: Class names for YOLO models. * `**hub_kwargs`: Additional keyword arguments passed to [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md). Returns * `ConvertResponse`: Conversion result containing the downloaded output path, export job, and exported model instance. ### RVC2 ```python def RVC2(path: PathType, mo_args: list[str] | None = None, compile_tool_args: list[str] | None = None, compress_to_fp16: bool = True, number_of_shaves: int = 8, superblob: bool = True, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ``` Convert a model to RVC2 format. Parameters * `path` (`PathType`): Path to the model file to convert. * `mo_args` (`list[str] | None`): Additional arguments for the Model Optimizer. * `compile_tool_args` (`list[str] | None`): Additional arguments for the compile tool. * `compress_to_fp16` (`bool`): Whether to compress model weights to FP16. Defaults to `True`. * `number_of_shaves` (`int`): Number of shaves to use for the conversion. Defaults to `8`. * `superblob` (`bool`): Whether to create a superblob for the model. Defaults to `True`. Disable it to use legacy RVC2 conversion. * `opts` (`Kwargs | list[str] | None`): Additional conversion options. These can override config values. * `name`: Model name. If not specified, the name is taken from the configuration file or the model file. * `license_type`: License type. * `is_public`: Whether the model is public (`True`), private (`False`), or team-scoped (`None`). * `description_short`: Short description of the model. * `description`: Full description of the model. * `architecture_id`: Architecture ID. * `tasks`: Tasks this model supports. * `links`: Links to related resources. * `is_yolo`: Whether the model is a YOLO model. * `model_id`: ID of an existing model resource. If specified, that model is used instead of creating a new one. * `variant_version`: Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`. * `variant_description`: Full description of the model variant. * `repository_url`: URL of the repository. * `commit_hash`: Commit hash. * `domain`: Domain of the model. * `variant_tags`: Tags for the model variant. * `variant_id`: ID of an existing model version resource. If specified, that version is used instead of creating a new one. * `input_shape`: Input shape for the model instance. * `is_deployable`: Whether the model instance is deployable. * `output_dir`: Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory. * `tool_version`: Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version. * `yolo_input_shape`: Input shape for YOLO models. * `yolo_version`: YOLO version. * `yolo_class_names`: Class names for YOLO models. * `**hub_kwargs`: Additional keyword arguments passed to [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md). Returns * `ConvertResponse`: Conversion result containing the downloaded output path, export job, and exported model instance. ### RVC3 ```python def RVC3(path: PathType, mo_args: list[str] | None = None, compile_tool_args: list[str] | None = None, compress_to_fp16: bool = True, pot_target_device: PotDevice | Literal['VPU', 'ANY'] = PotDevice.VPU, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ``` Convert a model to RVC3 format. Parameters * `path` (`PathType`): Path to the model file to convert. * `mo_args` (`list[str] | None`): Additional arguments for the Model Optimizer. * `compile_tool_args` (`list[str] | None`): Additional arguments for the compile tool. * `compress_to_fp16` (`bool`): Whether to compress model weights to FP16. Defaults to `True`. * `pot_target_device` (`PotDevice | Literal['VPU', 'ANY']`): Target device for post-training optimization. Defaults to `"VPU"`. * `opts` (`Kwargs | list[str] | None`): Additional conversion options. These can override config values. * `name`: Model name. If not specified, the name is taken from the configuration file or the model file. * `license_type`: License type. * `is_public`: Whether the model is public (`True`), private (`False`), or team-scoped (`None`). * `description_short`: Short description of the model. * `description`: Full description of the model. * `architecture_id`: Architecture ID. * `tasks`: Tasks this model supports. * `links`: Links to related resources. * `is_yolo`: Whether the model is a YOLO model. * `model_id`: ID of an existing model resource. If specified, that model is used instead of creating a new one. * `variant_version`: Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`. * `variant_description`: Full description of the model variant. * `repository_url`: URL of the repository. * `commit_hash`: Commit hash. * `domain`: Domain of the model. * `variant_tags`: Tags for the model variant. * `variant_id`: ID of an existing model version resource. If specified, that version is used instead of creating a new one. * `input_shape`: Input shape for the model instance. * `is_deployable`: Whether the model instance is deployable. * `output_dir`: Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory. * `tool_version`: Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version. * `yolo_input_shape`: Input shape for YOLO models. * `yolo_version`: YOLO version. * `yolo_class_names`: Class names for YOLO models. * `**hub_kwargs`: Additional keyword arguments passed to [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md). Returns * `ConvertResponse`: Conversion result containing the downloaded output path, export job, and exported model instance. ### RVC4 ```python def RVC4(path: PathType, snpe_onnx_to_dlc_args: list[str] | None = None, snpe_dlc_quant_args: list[str] | None = None, snpe_dlc_graph_prepare_args: list[str] | None = None, use_per_channel_quantization: bool = True, use_per_row_quantization: bool = False, htp_socs: list[Literal['sm8350', 'sm8450', 'sm8550', 'sm8650', 'qcs6490', 'qcs8550']] | None = None, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ``` Convert a model to RVC4 format. Parameters * `path` (`PathType`): Path to the model file to convert. * `snpe_onnx_to_dlc_args` (`list[str] | None`): Additional arguments for the SNPE ONNX to DLC conversion. * `snpe_dlc_quant_args` (`list[str] | None`): Additional arguments for SNPE DLC quantization. * `snpe_dlc_graph_prepare_args` (`list[str] | None`): Additional arguments for SNPE DLC graph preparation. * `use_per_channel_quantization` (`bool`): Whether to use per-channel quantization. Defaults to `True`. * `use_per_row_quantization` (`bool`): Whether to use per-row quantization. Defaults to `False`. * `htp_socs` (`list[Literal['sm8350', 'sm8450', 'sm8550', 'sm8650', 'qcs6490', 'qcs8550']] | None`): HTP SoCs for the final DLC graph. Defaults to `["sm8550"]`. * `opts` (`Kwargs | list[str] | None`): Additional conversion options. These can override config values. * `name`: Model name. If not specified, the name is taken from the configuration file or the model file. * `license_type`: License type. * `is_public`: Whether the model is public (`True`), private (`False`), or team-scoped (`None`). * `description_short`: Short description of the model. * `description`: Full description of the model. * `architecture_id`: Architecture ID. * `tasks`: Tasks this model supports. * `links`: Links to related resources. * `is_yolo`: Whether the model is a YOLO model. * `model_id`: ID of an existing model resource. If specified, that model is used instead of creating a new one. * `variant_version`: Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`. * `variant_description`: Full description of the model variant. * `repository_url`: URL of the repository. * `commit_hash`: Commit hash. * `quantization_mode`: Quantization mode to use during conversion. 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. * `domain`: Domain of the model. * `variant_tags`: Tags for the model variant. * `variant_id`: ID of an existing model version resource. If specified, that version is used instead of creating a new one. * `quantization_data`: Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file. Pass the `.zip` path itself instead of `CUSTOM`; the SDK normalizes local zip inputs automatically. * `max_quantization_images`: Maximum number of quantization images. * `input_shape`: Input shape for the model instance. * `is_deployable`: Whether the model instance is deployable. * `output_dir`: Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory. * `tool_version`: Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version. * `yolo_input_shape`: Input shape for YOLO models. * `yolo_version`: YOLO version. * `yolo_class_names`: Class names for YOLO models. * `**hub_kwargs`: Additional keyword arguments passed to [convert](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md). Returns * `ConvertResponse`: Conversion result containing the downloaded output path, export job, and exported model instance.