Training & Tutorials

How to Use the Modzy Python SDK in a Jupyter Notebook


To date, the Modzy team has developed Software Developer Kits (SDKs) for Python, Java, and JavaScript, all of which make leveraging the Modzy API quick and easy. These SDKs ease the creation of applications by reducing the amount of work the user must perform to both submit inference jobs and extract results.

What You Need to Know

The Modzy Python SDK makes it possible to access the Modzy API and add AI functionality to any Python environment with one pip-installable package. A data scientist or software developer can leverage the API Client class within this SDK to bring Modzy capabilities to their existing workflows without having to manually generate a Modzy compliant http POST request according to our documentation. The use of this SDK therefore reduces the amount of time and in-depth technical understanding needed to leverage Modzy in your own applications.

In this tutorial, we will walk through a demonstration of submitting a processing request to a model from a Jupyter Notebook. More specifically, this tutorial will implement an Open Source Automobile Classification model to predict the make and model of a car in an image. To complete this tutorial, you will need to install the following:



Setting up for this Tutorial

Before beginning this tutorial, open a command line interface where you will open your Jupyter Notebook. This environment should include Jupyter Notebooks, Python 3.6>, and pip installations.

First, create and activate a virtual environment.

Next, clone the Modzy Python SDK to your environment. You can find the full set of installation instructions on the Modzy Github page.

After the sdk-python repository cloning process completes, use the pip package manager to install Modzy into your environment.

Upon the successful installation of Modzy, open your Jupyter Notebook to begin. Learn more about adding virtual environments to Jupyter Notebooks here.


Modzy Python SDK Initialization

In the first cell of your notebook, import the Modzy SDK followed more specifically by the Modzy API client and error objects that will allow you to submit jobs and identify errors, respectively.

Define two important variables that will be essential for submitting an API job request in the next cell. Replace “base Modzy instance URL” with your own instance URL and “api-key” with your API key.

After defining these variables, authenticate Modzy in the next cell by initializing a variable called “client” that leverages the SDK’s “ApiClient” class.

Once this cell executes, you are ready to connect to the Modzy platform and you can now use this “client” to query models, submit inference jobs, and return results directly to your notebook.

Submitting Jobs

Before you start submitting job requests, determine which model you are going to use by opening the marketplace within your instance. Here, select your model and navigate to its “Model Details Page” to gather some information you will need to submit a job.

Figure 1. Automobile Classification Model Details Page

This Automobile Classification model takes an image of a car as input and returns the car class (make and model) prediction along with the prediction probability as output.

To call a model in the Modzy platform, you will need both the model identifier and the model version, which you will find at the bottom of the model’s details page (highlighted in yellow in the below screenshot).

Figure 2. “How To” section of Model Details Page. The Model Identifier & Version are highlighted.


In the next cell of your notebook, create two string variables to represent the Model Identifier and Version.

Download the test car image from this tutorial’s Github page, import the image processing package Pillow, and view the image in the next cell.

Submit a job and catch any potential errors by wrapping the request inside a try except block of code. In the try block use the submit_files function to specify the model identifier, model version, and input file path that define your processing request.

When this cell successfully executes, a job has been sent to the Modzy platform. This means your request for the input data to be processed by the specified model has been received by the Modzy platform, and the request has been queued.

At this point the Modzy platform will process your request according to available resources and priorities. To help you with interfacing with the platform to retrieve your results, the SDK includes a block_until_complete function that communicates with the platform and checks on the status of your job once the job has finished. The method returns the result for your analysis.

To leverage the block_until_complete method, place it inside a series of error catching try-except statements. These different errors (Timeout, NetworkError, and Response Error), are the three types of errors that could occur during inference. When this cell completes, it means either inference has completed on the platform and our result has been retrieved, or an error occurred, causing inference to fail.

Extracting Results

Now that inference is complete, the results can be retrieved and printed to your notebook. The output for every model is different, but this model returns a json file that contains a list of the top car class (make and model) predictions accompanied by a confidence score.

This section of code takes the raw result output – a json file that looks analogous to the sample API response on the model details page – and extracts the part of the result that contains the model predictions.


Using the Python SDK allows you to leverage the Modzy platform with just a few lines of code to bring AI functionality to your existing applications like Jupyter Notebooks. It is important to note that while this process is repeatable for the use of other models, there is model-specific information that varies between models such as model identifier, version number, and input requirements.

For more information and how-to tutorials, visit our Developer Center to learn more about how Modzy can accelerate the process for building AI-powered applications.

Get Details on Quick Start Program