Custom Response Classes

Overview

FastAPI provides several response classes for different content types. By default, FastAPI returns responses as JSON, but you can customize this behavior using different response classes.

Available Response Classes

FastAPI (via Starlette) provides these response classes:

JSONResponse - JSON responses (default)
HTMLResponse - HTML content
PlainTextResponse - Plain text
RedirectResponse - HTTP redirects
StreamingResponse - Streaming responses
FileResponse - File downloads
Response - Generic response class

JSONResponse

The default response class for most FastAPI endpoints:

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/items/")
def read_items():
    return JSONResponse(content={"message": "Hello World"})

You typically don’t need to use JSONResponse explicitly - FastAPI uses it by default when you return a dict, list, or Pydantic model.

HTMLResponse

Return HTML content from your endpoints:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/items/", response_class=HTMLResponse)
async def read_items():
    return """
    <html>
        <head>
            <title>Some HTML in here</title>
        </head>
        <body>
            <h1>Look ma! HTML!</h1>
        </body>
    </html>
    """

Direct HTMLResponse

You can also return an HTMLResponse object directly:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/items/")
async def read_items():
    html_content = """
    <html>
        <head>
            <title>Some HTML in here</title>
        </head>
        <body>
            <h1>Look ma! HTML!</h1>
        </body>
    </html>
    """
    return HTMLResponse(content=html_content, status_code=200)

When using response_class=HTMLResponse, you can return the HTML as a string directly. When returning HTMLResponse objects, you have more control over status codes and headers.

PlainTextResponse

Return plain text content:

from fastapi import FastAPI
from fastapi.responses import PlainTextResponse

app = FastAPI()

@app.get("/text/", response_class=PlainTextResponse)
async def read_text():
    return "Hello, World!"

Or directly:

@app.get("/text/")
async def read_text():
    return PlainTextResponse(content="Hello, World!")

RedirectResponse

Redirect to another URL:

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()

@app.get("/old-path")
async def redirect_old_path():
    return RedirectResponse(url="/new-path")

@app.get("/new-path")
async def new_path():
    return {"message": "This is the new path"}

Redirect Status Codes

Control the redirect type with status codes:

from fastapi import status
from fastapi.responses import RedirectResponse

# Temporary redirect (default is 307)
@app.get("/temp-redirect")
async def temp_redirect():
    return RedirectResponse(
        url="/new-path",
        status_code=status.HTTP_307_TEMPORARY_REDIRECT
    )

# Permanent redirect
@app.get("/permanent-redirect")
async def permanent_redirect():
    return RedirectResponse(
        url="/new-path",
        status_code=status.HTTP_308_PERMANENT_REDIRECT
    )

Use 307 (Temporary Redirect) to preserve the request method
Use 308 (Permanent Redirect) for permanent redirects that preserve the method
Use 302 (Found) for temporary redirects that may change the method to GET
Use 301 (Moved Permanently) for permanent redirects that may change the method

StreamingResponse

Stream large files or generated content:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import io

app = FastAPI()

@app.get("/stream/")
async def stream_data():
    def generate():
        for i in range(10):
            yield f"data chunk {i}\n"
    
    return StreamingResponse(
        generate(),
        media_type="text/plain"
    )

Streaming Files

Stream file content:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()

@app.get("/video/")
def stream_video():
    file_path = "large_video.mp4"
    
    def iterfile():
        with open(file_path, "rb") as file:
            yield from file
    
    return StreamingResponse(
        iterfile(),
        media_type="video/mp4"
    )

For static files, consider using FileResponse instead, as it’s optimized for serving files efficiently.

FileResponse

Serve files efficiently with proper headers:

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/download/")
async def download_file():
    file_path = "example.pdf"
    return FileResponse(
        path=file_path,
        filename="downloaded_file.pdf",
        media_type="application/pdf"
    )

File Download with Custom Headers

@app.get("/download-with-headers/")
async def download_with_headers():
    return FileResponse(
        path="example.csv",
        filename="data.csv",
        media_type="text/csv",
        headers={
            "Content-Disposition": "attachment; filename=data.csv"
        }
    )

Setting Default Response Class

Set a default response class for your entire app or router:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI(default_response_class=HTMLResponse)

@app.get("/items/")
async def read_items():
    return "<h1>Items</h1>"

Or for a router:

from fastapi import APIRouter
from fastapi.responses import JSONResponse

router = APIRouter(default_response_class=JSONResponse)