Thought leadership from the most innovative tech companies, all in one place.

Python FastAPI — Serving Images, MP3 Files, etc. from Your Backend for Beginners

A beginners’ guide on how to serve images, MP3 files, PDF files, DOC files, etc. to frontend from backend using Python FastAPI.


If you clicked on this article, you probably intend to build a Python FastAPI backend application that can provide and serve stuff like images, music, MP3 files, PDF files, word docs, etc. to your frontend application. In this article’s context, all these files will be referred to as static files.

Starting With A Very Basic FastAPI App

Here’s some basic Python FastAPI code in case you need it:

#app.pyimport uvicorn
from fastapi import FastAPIapp = FastAPI()[@app]("/")
def home():
    return {"message": "hello world"}if __name__ == "__main__":"app:app", host="", port=5000)

In case you are very new, we first need to install the librariesuvicorn and fastapi. We type the following command into our terminal or CMD.

pip install fastapi uvicorn

To run this, we simply type this into terminal/CMD

python # python3 for MacOS

And our FastAPI backend app will run. If we visit the / endpoint in our web browser at [http://localhost:5000](http://localhost:5000,/), we get back a JSON response:

{"message": "hello world"}

Adding Our Static Files

Once again, static files here refer to the images, MP3 files, PDF files, DOCX files, etc. that we want our backend app to serve. We first need to create a static folder (next to, like this:

  • static

The static folder is the one containing all our static files — our images, mp3 files, pdf files etc files will all go inside the static folder. Note that we can use subfolders to organise things, because who wants to manage 1 folder full of random static files?

- static
  - images
    - image1.jpg
    - image2.jpg
  - mp3
    - song1.mp3
    - song2.mp3-

Note: it’s fine to use even more subfolders if you want, as long as these folders all go inside the static folder.

Adding 2 Lines Of Code To Serve Our Static Files

Here, we want to tell Python FastAPI that we want to allow users to access these static files. We only need to add 2 lines of code to make this work.

from fastapi.staticfiles
import StaticFilesapp = FastAPI() # this was here before
app.mount("/static", StaticFiles(directory="static"), name="static")

The line app.mount("/static", ...) essentially exposes our static folder to our users. Now, let’s run our FastAPI app to test if we can access our static files.

Let’s say we want to access static/images/image1.jpg. We simply need to visit the endpoint /static/images/image1.jpg. If we want to access static/mp3/song1.mp3, we just need to visit the endpoint /static/mp3/song1.mp3


And we’ll be able to see our static files whether it is an image, mp3 file etc.

Letting Your Frontend Know What Static Files You Have

Let’s say we want our frontend app to display all images in our static/images folder on one of its pages. As of now, we have exposed our static folder (images, MP3, etc.) which means that:

  • Our frontend can call our static endpoints /static/images/image1.jpg and /static/images/image2.jpg (and more if we have more images)
  • Our frontend can access these images after calling these endpoints, and in turn display it

However, our frontend currently will not know that we have image1.jpg and image2.jpg in our static folder (unless we hard code but let’s not do that). As such, our frontend needs to call another endpoint to get this information.

What we envision

Our frontend calls the /images endpoint with this JSON response:

  {"name":"image1", "filepath": "/static/images/image1.jpg"}
  {"name":"image2", "filepath": "/static/images/image2.jpg"}

Using this response, our frontend now knows 1) how many images there are and 2) where to find them. Our frontend then makes 2 more requests to the endpoint of the static images — /static/images/image1.jpg and /static/images/image2.jpg, and displays them.

Writing the /images endpoint (or whatever endpoint you set it to be)

import os@app.get("/images")
def images():
    out = []
    for filename in os.listdir("static/images"):
            "name": filename.split(".")[0],
            "path": "/static/images/" + filename
    return out

The os.listdir function essentially returns a list of filenames inside a given folder. Here, os.listdir("static/images") will return a list ["image1.jpg", "image2.jpg"], and we do some string processing before adding them into our output.

A Github repository containing an example

Continue Learning