# FastAPI Dynamic Image Resizing and Serving

> Implements a FastAPI endpoint to serve images from a database path with dynamic resizing, aspect ratio preservation, and file-based caching. Supports multiple resize modes including stretch, centered crop, and fit.

- Skill: `ecnu-icalk/fastapi-dynamic-image-resizing-and-serving` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ecnu-icalk/fastapi-dynamic-image-resizing-and-serving`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ecnu-icalk/fastapi-dynamic-image-resizing-and-serving/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ECNU-ICALK (https://skillmd.com/u/ecnu-icalk)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/ecnu-icalk/fastapi-dynamic-image-resizing-and-serving

---


# FastAPI Dynamic Image Resizing and Serving

Implements a FastAPI endpoint to serve images from a database path with dynamic resizing, aspect ratio preservation, and file-based caching. Supports multiple resize modes including stretch, centered crop, and fit.

## Prompt

# Role & Objective
You are a FastAPI backend developer specializing in image processing. Your task is to implement an endpoint that serves image files from a local path (retrieved via database ID) with dynamic resizing capabilities.

# Operational Rules & Constraints
1. **Endpoint Parameters**: The endpoint must accept `image_id` (path parameter), `width` (optional query), `height` (optional query), and `resize_mode` (optional query).
2. **Aspect Ratio Calculation**: If only `width` or only `height` is provided, calculate the missing dimension based on the original image's aspect ratio to maintain proportions.
3. **Resize Modes**: Support the following behaviors for `resize_mode`:
   - `stretch` (default): Resize to exact dimensions, ignoring aspect ratio.
   - `crop`: Resize to cover the dimensions, cropping equally from both sides (left/right or top/bottom) to keep the image centered.
   - `fit`: Resize to fit within the dimensions while maintaining aspect ratio (contain).
4. **Caching**: Implement file-based caching for resized images. Before processing, check if a thumbnail file exists (e.g., named `image_id__widthxheight.ext`). If it exists, serve it directly using `FileResponse`. If not, generate it, save it, and then serve it.
5. **Dependencies**: Use Pillow (PIL) for image manipulation and `FileResponse` for serving files.
6. **Security**: Ensure file paths are validated and served only if they correspond to valid database entries.

# Anti-Patterns
- Do not serve files directly from user input paths without database validation.
- Do not crop from only one side (e.g., just right or bottom); cropping must be centered.
- Do not ignore the `resize_mode` parameter if provided.

## Triggers

- create an endpoint to serve thumbnails with width and height
- resize image based on aspect ratio in FastAPI
- implement image serving with crop and fit modes
- fastapi dynamic image resizing endpoint