API Usage

Overview

This page is Option 2 in the full repository workflow.

It explains the local API path in the full repository context.

If you want the package-only API explanation, use the companion repository:

When to use this option

Choose Option 2 when you want:

  • a browser UI for training or prediction

  • a local DEEPaaS service for integration

  • the same project assets and outputs as the CLI path, but through HTTP

The DEEPaaS entry point is defined in pyproject.toml:

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

The simplest way to start the API is:

planktonclas api --config ./my_project/config.yaml

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.

Direct DEEPaaS startup

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

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

Main API functions

The main public API functions are:

  • get_metadata()

  • get_train_args()

  • train(**args)

  • get_predict_args()

  • predict(**args)

Training through the API

Typical browser flow:

  1. start planktonclas api --config ./my_project/config.yaml

  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

  • image_size

  • batch_size

  • epochs

  • use_validation

  • use_test

  • use_best_model

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

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

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

What comes next

After using Option 2, continue with:

  • Reference to understand outputs and project structure

  • planktonclas docs if you want package-level API detail