ModelAPI¶

class ModelAPI(api=None, task_id=None, url=None)[source]¶

Bases: object

Client for interacting with a deployed model (load settings/metadata, run inference).

The instance can be created either from a Supervisely Task ID (to resolve the deployment URL automatically) or from a direct deployment URL.

Parameters:

api=None¶: API client. Required when task_id is used.
task_id : int, optional¶: Supervisely task id of a deployed model.
url : str, optional¶: Direct URL to a deployed model endpoint (e.g. https://.../net/<token>).

Raises:

AssertionError – If both task_id and url are provided, or neither is provided.
ValueError – If task_id is provided but the task is not found.

Task based usage:

import os
from dotenv import load_dotenv

import supervisely as sly
from supervisely.nn.model.model_api import ModelAPI

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

model = ModelAPI(api=api, task_id=12345)
meta = model.get_model_meta()
classes = model.get_classes()
predictions = model.predict(image_id=100500, classes=classes)

Direct URL usage:

from supervisely.nn.model.model_api import ModelAPI

model = ModelAPI(url='https://app.supervisely.com/net/<sessionToken>')
predictions = model.predict(input='/path/to/image.jpg')

Methods

`freeze_model`	Freeze the model to free up resources.
`get_classes`	Convenience wrapper to return output class names from `get_model_meta()`.
`get_info`	Return deployment info for the current model.
`get_model_meta`	Return output `ProjectMeta` for the deployed model.
`get_settings`	Return custom inference settings for the deployed model.
`get_tracking_settings`	Return tracking settings for the deployed model.
`is_deployed`	Check whether the deployment is ready.
`list_experiments`	Return a list of training experiments in Supervisely.
`list_pretrained_model_infos`	Return a list of pretrained model infos with full information about each model.
`list_pretrained_models`	Return a list of pretrained model names available for deployment.
`load`	Load a model into the deployment.
`predict`	Run inference and return predictions as a list.
`predict_detached`	Create a prediction session (lazy iterator).
`shutdown`	Stop the deployment task (task-based mode) or request shutdown (URL-based mode).
`status`	Return deployment status JSON.

freeze_model()[source]¶

Freeze the model to free up resources.

Returns:: Backend response.
Return type:: dict

get_classes()[source]¶

Convenience wrapper to return output class names from get_model_meta().

Returns:: List of class names.
Return type:: List[str]

get_info()[source]¶

Return deployment info for the current model.

For task-based mode this calls internal deploy API, for URL-based mode it calls get_deploy_info endpoint of the deployment.

Returns:: Deployment info (raw JSON returned by the backend).
Return type:: dict

get_model_meta()[source]¶

Return output ProjectMeta for the deployed model.

The meta typically includes object classes and tags that the model predicts.

Returns:: Model output meta.
Return type:: ProjectMeta

get_settings()[source]¶

Return custom inference settings for the deployed model.

Returns:: Settings dict.
Return type:: dict

get_tracking_settings()[source]¶

Return tracking settings for the deployed model.

Currently returns settings for the botsort tracker.

Returns:: Tracking settings dict.
Return type:: dict

is_deployed()[source]¶

Check whether the deployment is ready.

Returns:: True if ready.
Return type:: bool

list_experiments()[source]¶

Return a list of training experiments in Supervisely.

Note

This method is not implemented.

Returns:: Experiments list.
Return type:: List[ExperimentInfo]
Raises:: NotImplementedError – Always.

list_pretrained_model_infos()[source]¶

Return a list of pretrained model infos with full information about each model.

Returns:: List of model info dicts.
Return type:: List[dict]

list_pretrained_models()[source]¶

Return a list of pretrained model names available for deployment.

Returns:: Pretrained model names.
Return type:: List[str]

load(model, device=None, runtime=None)[source]¶

Load a model into the deployment.

Behavior depends on the connection mode:

URL-based Mode (task_id is None): if model points to an existing local file, it is treated as a custom checkpoint; otherwise it is treated as a pretrained model name.
Task-based Mode: if model starts with / it is treated as a path to a custom checkpoint in team files; otherwise it is treated as a pretrained model name.

Parameters:

model : str¶: Pretrained model name or checkpoint path (depending on the mode).
device : str, optional¶: Optional device spec (passed to deploy backend).
runtime : str, optional¶: Optional runtime spec (passed to deploy backend).

Returns:

Backend response (URL-based mode) or None (task-based mode).

Return type:

dict or None

Raises:

ValueError – If pretrained model name is not found (URL-based mode).

predict(input=None, image_id=None, video_id=None, dataset_id=None, project_id=None, batch_size=None, conf=None, img_size=None, classes=None, upload_mode=None, recursive=False, tracking=None, tracking_config=None, **kwargs)[source]¶

Run inference and return predictions as a list.

This is a convenience wrapper over predict_detached() that consumes the session and returns list(session).

Parameters are forwarded to PredictionSession.

Returns:: Predictions list.
Return type:: List[Prediction]

predict_detached(input=None, image_id=None, video_id=None, dataset_id=None, project_id=None, batch_size=None, conf=None, img_size=None, classes=None, upload_mode=None, recursive=False, tracking=None, tracking_config=None, **kwargs)[source]¶

Create a prediction session (lazy iterator).

Use this method when you want to iterate predictions as they are produced, or if you need direct access to PredictionSession.

Parameters are forwarded to PredictionSession.

Returns:: Prediction session.
Return type:: PredictionSession

shutdown()[source]¶

Stop the deployment task (task-based mode) or request shutdown (URL-based mode).

Returns:: Status info. In task-based mode returns task stop response, in URL-based mode returns status enum value if supported by the backend.

status()[source]¶

Return deployment status JSON.

Returns:: Status dict.
Return type:: dict