Deploying a Machine-Learning Model as a FastAPI API on Heroku

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

“Delply” is a typo for deploy. The intended workflow is to train a machine-learning model separately, serialize it, load it in a FastAPI application, validate JSON input, and return predictions through an HTTP endpoint. The 2021 example uses a music-genre classifier with eight audio features and Heroku as the host. FastAPI remains a useful framework for this pattern, but the Heroku-specific instructions below are historical and must be checked against Heroku’s current runtime, pricing, and deployment documentation.

What the FastAPI–Heroku pattern does

The service has four parts:

1. A trained estimator, preferably saved together with its preprocessing pipeline.
2. A FastAPI application that loads the artifact when the process starts.
3. A typed request model that checks incoming JSON.
4. A prediction route that calls model.predict() and returns JSON.

The request path is:

Client → JSON request → FastAPI validation → serialized model → JSON prediction

This is model serving, not model training. Retraining inside a web request would make latency, reliability, and resource use much harder to control.

#	Preview	Product	Price
1		Python Machine Learning By Example: Unlock machine learning best practices with real-world use cases	$29.55	Buy on Amazon
2		Introduction to Machine Learning with Python: A Guide for Data Scientists	$33.05	Buy on Amazon
3		Machine Learning with PyTorch and Scikit-Learn: Develop machine learning and deep learning models...	$34.23	Buy on Amazon
4		Python Machine Learning: Machine Learning and Deep Learning with Python, scikit-learn, and...	$42.74	Buy on Amazon
5		Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow: Concepts, Tools, and Techniques...	$49.50	Buy on Amazon

The source tutorial, published July 6, 2021, demonstrates this approach with a music classifier. It describes genres such as Rock and Hip-Hop, but the exact label is determined by the model artifact, not by FastAPI. See the original walkthrough at Analytics Vidhya.

Project layout and model preparation

A maintainable small project can look like this:

ml-fastapi-app/
├── app/
│   ├── __init__.py
│   └── main.py
├── model/
│   └── model.pkl
├── requirements.txt
├── Procfile
└── README.md

A flat layout with main.py and model.pkl in the project root also works for a demonstration. The model file must be included in the deployment artifact or downloaded from controlled object storage at startup. Large artifacts may be unsuitable for a Git repository or a small application instance.

#1 Best Overall

Sale

Python Machine Learning By Example: Unlock machine learning best practices with real-world use cases

$29.55

Buy on Amazon

Serialize the complete inference pipeline

Save the same transformations used during training—scaling, encoding, missing-value handling, feature selection, and the estimator—in one tested pipeline where possible. Otherwise, a serving process can return plausible but incorrect predictions because feature order or preprocessing changed.

Record the serving environment

Test loading the artifact in a clean environment and record the Python, NumPy, SciPy, scikit-learn, and other relevant versions. Pickle files are not a portable interchange format across arbitrary library versions.

Treat pickle as trusted code

pickle.load() can execute arbitrary code. Load only artifacts produced by a trusted build process, protect their storage, verify integrity, and never accept an uploaded pickle from an untrusted user.

Build the FastAPI application

The original example defines eight floating-point inputs: acousticness, danceability, energy, instrumentalness, liveness, speechiness, tempo, and valence. This version uses a path derived from __file__ so it does not depend on the process’s working directory.

Rank #2

Sale

Introduction to Machine Learning with Python: A Guide for Data Scientists

$33.05

Buy on Amazon

from pathlib import Path
import pickle

from fastapi import FastAPI
from pydantic import BaseModel

BASE_DIR = Path(__file__).resolve().parent
MODEL_PATH = BASE_DIR.parent / "model" / "model.pkl"

with MODEL_PATH.open("rb") as file:
    model = pickle.load(file)

app = FastAPI(title="Music Genre Prediction API")


class Music(BaseModel):
    acousticness: float
    danceability: float
    energy: float
    instrumentalness: float
    liveness: float
    speechiness: float
    tempo: float
    valence: float


@app.get("/")
def health_check():
    return {"status": "ok"}


@app.post("/prediction")
def predict(data: Music):
    values = [[
        data.acousticness,
        data.danceability,
        data.energy,
        data.instrumentalness,
        data.liveness,
        data.speechiness,
        data.tempo,
        data.valence,
    ]]
    prediction = model.predict(values)[0]
    return {"prediction": prediction}

Pydantic supplies the request schema used by FastAPI and its generated OpenAPI documentation. The source uses data.dict(); with modern Pydantic installations, model_dump() may be required instead, so keep the code and dependency versions compatible.

Validation versus model correctness

A float annotation checks type, not meaning. Add domain constraints when they are known—for example, finite values, nonnegative tempo, or bounded ratios—and reject impossible requests. Validation still cannot prove that units, feature order, or values match the training data.

Run and test locally

Install the dependencies in an isolated environment, then start the application from the project root:

uvicorn app.main:app --reload

For a root-level main.py, use:

uvicorn main:app --reload

Check these URLs:

• http://127.0.0.1:8000/ for the health response.
• http://127.0.0.1:8000/docs for Swagger UI backed by the OpenAPI schema.
• http://127.0.0.1:8000/openapi.json for the raw schema.

Send a request with curl:

curl -X POST "http://127.0.0.1:8000/prediction" 
  -H "Content-Type: application/json" 
  -d '{
    "acousticness": 0.344719513,
    "danceability": 0.758067547,
    "energy": 0.323318405,
    "instrumentalness": 0.0166768347,
    "liveness": 0.0856723112,
    "speechiness": 0.0306624283,
    "tempo": 101.993,
    "valence": 0.443876228
  }'

The response shape is:

{"prediction": "<model-generated-label>"}

Do not promise “Rock” or any other class without checking the deployed artifact. A Python client can test the same contract:

Rank #3

Sale

Machine Learning with PyTorch and Scikit-Learn: Develop machine learning and deep learning models with Python

$34.23

Buy on Amazon

import requests

payload = {
    "acousticness": 0.344719513,
    "danceability": 0.758067547,
    "energy": 0.323318405,
    "instrumentalness": 0.0166768347,
    "liveness": 0.0856723112,
    "speechiness": 0.0306624283,
    "tempo": 101.993,
    "valence": 0.443876228,
}

response = requests.post(
    "http://127.0.0.1:8000/prediction",
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())

Historical Heroku deployment files

requirements.txt

The tutorial lists these unpinned dependencies:

fastapi
uvicorn
gunicorn
scikit-learn
pydantic

For a reproducible deployment, pin versions after testing them together. Do not copy arbitrary version numbers: serialized scikit-learn models can break when Python or scientific-library versions differ from training.

Procfile

For app/main.py with an application object named app, the historical Gunicorn command is:

web: gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app

The module path must match your files. Four workers is not a universal recommendation: each worker may load its own model copy, multiplying memory use. Choose the count from model size, available memory, CPU, concurrency, and measured latency.

runtime.txt

The 2021 article uses runtime.txt to declare Python. Treat that as a historical Heroku convention. Supported Python versions, runtime declaration, build behavior, pricing, sleeping behavior, and dashboard labels can change, so verify them in Heroku’s current documentation before deployment.

Rank #4

Sale

Python Machine Learning: Machine Learning and Deep Learning with Python, scikit-learn, and TensorFlow 2, 3rd Edition

$42.74

Buy on Amazon

Deploying the historical workflow

The source describes putting the code and model in a Git repository, creating a Heroku application, connecting the repository, and deploying a branch. Current interface labels and supported deployment methods are not guaranteed to match that 2021 description.

1. Place the application, model artifact, dependency file, and process definition in the deployment artifact.
2. Configure secrets and settings as environment variables rather than committing them.
3. Create or select the Heroku application using the currently supported workflow.
4. Trigger a build and inspect its output.
5. Review runtime logs, for example with heroku logs --tail where the Heroku CLI and application support it.
6. Check the health endpoint, open /docs, and send a real POST request to /prediction.

Heroku’s official pages are heroku.com and heroku.com/pricing. The original tutorial’s references to free hosting should not be treated as a current pricing claim.

Troubleshoot common failures

Boot failure

Read the application logs first. Typical causes are a wrong Procfile module path, missing Gunicorn, an import error, an unsupported runtime, a missing model file, or a dependency build failure.

Model file not found

Use a path based on Path(__file__), confirm the file is included with the deployed artifact or downloaded at startup, and check case-sensitive names.

Best Value

Sale

Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow: Concepts, Tools, and Techniques to Build Intelligent Systems

• Use scikit-learn to track an example ML project end to end
• Explore several models, including support vector machines, decision trees, random forests, and ensemble methods
• Exploit unsupervised learning techniques such as dimensionality reduction, clustering, and anomaly detection
• Dive into neural net architectures, including convolutional nets, recurrent nets, generative adversarial networks, autoencoders, diffusion models, and transformers
• Use TensorFlow and Keras to build and train neural nets for computer vision, natural language processing, generative models, and deep reinforcement learning

$49.50

Buy on Amazon

Unpickling error

Recreate the serving environment with the training versions, or retrain/export the model in a controlled environment. A successful web build does not prove artifact compatibility.

HTTP 422

FastAPI returns 422 when required fields are missing or types do not match. Compare the JSON with the schema shown in /docs.

Correct HTTP response, wrong prediction

Inspect feature ordering, units, scaling, encoding, missing-value rules, label mapping, and whether the serialized object contains the complete preprocessing pipeline.

Memory exhaustion or timeouts

Reduce worker count, avoid duplicate model loads, use a smaller or optimized model, profile inference, and move to larger or specialized infrastructure when the workload requires it. Async route syntax does not make CPU-bound prediction asynchronous.

Production safeguards

• Use authentication, HTTPS, rate limiting, request-size limits, and restrictive CORS settings.
• Keep secrets in environment configuration and avoid logging sensitive feature payloads.
• Expose health and, where useful, model-version metadata.
• Track latency, errors, resource use, and prediction distributions.
• Version artifacts and dependencies, test rollback, and evaluate a model before promotion.
• Monitor data and concept drift; a healthy HTTP process can still serve a degraded model.

When Heroku is not the right fit

Docker is documented at docker.com and docker.com/pricing. Managed services include SageMaker, Vertex AI, and Azure Machine Learning. Their costs and limits depend on configuration and should be checked directly.

Bottom line

Keep the FastAPI design: load a trusted, versioned model once, validate a clearly defined request, and test the contract locally through /docs and a real client. Treat the Heroku deployment recipe as a dated example rather than a timeless production standard. For current production use, choose hosting based on model size, reproducibility, security, observability, and scaling needs.

Quick Recap

SaleBestseller No. 1

Python Machine Learning By Example: Unlock machine learning best practices with real-world use cases

$29.55

SaleBestseller No. 2

Introduction to Machine Learning with Python: A Guide for Data Scientists

$33.05

SaleBestseller No. 3

Machine Learning with PyTorch and Scikit-Learn: Develop machine learning and deep learning models with Python

$34.23

SaleBestseller No. 4

Python Machine Learning: Machine Learning and Deep Learning with Python, scikit-learn, and TensorFlow 2, 3rd Edition

$42.74

SaleBestseller No. 5

Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow: Concepts, Tools, and Techniques to Build Intelligent Systems

Use scikit-learn to track an example ML project end to end

$49.50

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.