2. API Usage

Overview

This page shows the API-based workflow as a sequence of practical steps.

Use this path when you want to work through the DEEPaaS browser UI or call the API endpoints directly.

API workflow

The common order is:

1. install the package

2. create a project

3. validate the config

4. optionally download the pretrained model

5. optionally build an inference Docker image

6. start the API

7. use the training endpoint or prediction endpoint

8. inspect the outputs written by the package

Step 1: Install the package

pip install planktonclass

Step 2: Create a project

planktonclass init my_project

This creates a local config.yaml and the standard project folders.

Step 3: Validate the config

planktonclass validate-config my_project

Step 4: Optional pretrained model

If you want to start from a published pretrained model:

planktonclass pretrained my_project --model FlowCam

Available published pretrained names currently include FlowCam, FlowCyto, and PI10.

Step 5: Optional inference Docker image

After training a model, you can package it into a Docker image for a more stable inference runtime:

planktonclass docker my_project

Then run the API from Docker:

docker run -p 5001:5000 planktonclass-inference:<timestamp>

Inside the container, the API listens on port 5000. You can map any free host port.

Step 6: Start the API

The DEEPaaS entry point is defined in pyproject.toml:

[project.entry-points."deepaas.v2.model"]
planktonclass = "planktonclass.api"

The simplest way to start the API is:

planktonclass api my_project

Then open:

• http://127.0.0.1:5000/ui

• http://127.0.0.1:5000/api#/

Use 127.0.0.1 in the browser. 0.0.0.0 is only the bind address.

After a repository install, you can also start the API directly:

$env:planktonclass_CONFIG = (Resolve-Path .\my_project\config.yaml)
$env:DEEPAAS_V2_MODEL = "planktonclass"
deepaas-run --listen-ip 0.0.0.0

Step 7: Train through the API

Typical browser flow:

1. start planktonclass api my_project

2. open /ui or /api#/

3. find the TRAIN operation

4. edit the parameters you want

5. execute the request

The most important training parameters are:

• images_directory

• modelname

• use_pretrained

• pretrained_name

• pretrained_version

• image_size

• batch_size

• epochs

• use_validation

• use_test

Important limitation:

• images_directory is a path field, not a browser folder picker

• the API cannot open a server-side folder chooser through Swagger UI

• for local use, it is usually better to set the path in config.yaml before starting the API

• with the standard project layout from planktonclass init, planktonclass api my_project automatically uses my_project/config.yaml

Step 8: Run prediction through the API

The prediction endpoint accepts:

• image: a single uploaded image

• zip: a ZIP archive containing one or more images

Typical browser flow:

1. start the API

2. open /ui or /api#/

3. find the PREDICT POST method

4. click Try it out

5. provide either image or zip

6. click Execute

Prediction response

The response contains:

• filenames

• pred_lab

• pred_prob

• aphia_ids when available

What the API exposes

The main public API functions are:

• get_metadata()

• get_train_args()

• train(**args)

• get_predict_args()

• predict(**args)

Runtime behavior

• prediction writes a JSON artifact to the configured predictions directory

• ZIP prediction extracts the archive to a temporary directory and scans recursively for images

• training validates images_directory before starting

• if there are no models yet, the API can still be used for training, but not for inference