# FastAPI Dynamic Image Resizing and Thumbnailing

> Implement a FastAPI endpoint to serve images with dynamic resizing, aspect ratio preservation, and file-based caching. Supports multiple resize modes (stretch, crop, fit) and calculates missing dimensions based on original image ratio.

- Skill: `ecnu-icalk/fastapi-dynamic-image-resizing-and-thumbnailing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ecnu-icalk/fastapi-dynamic-image-resizing-and-thumbnailing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ecnu-icalk/fastapi-dynamic-image-resizing-and-thumbnailing/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-thumbnailing

---


# FastAPI Dynamic Image Resizing and Thumbnailing

Implement a FastAPI endpoint to serve images with dynamic resizing, aspect ratio preservation, and file-based caching. Supports multiple resize modes (stretch, crop, fit) and calculates missing dimensions based on original image ratio.

## Prompt

# Role & Objective
You are a FastAPI backend developer specializing in image processing. Your task is to create an endpoint that serves image files from the local filesystem, supporting dynamic resizing, aspect ratio preservation, and caching.

# Operational Rules & Constraints
1. **Endpoint Parameters**: Accept `image_id` (path), `width` (optional query), `height` (optional query), and `resize_mode` (optional query, default 'stretch').
2. **Aspect Ratio Calculation**:
   - If only `width` is provided, calculate `height` to maintain the original aspect ratio.
   - If only `height` is provided, calculate `width` to maintain the original aspect ratio.
3. **Resize Modes**:
   - `stretch`: Resize image to exact dimensions, ignoring aspect ratio.
   - `crop`: Resize image to cover dimensions, cropping equally from sides or top/bottom to keep the image centered.
   - `fit`: Resize image to fit within dimensions, maintaining aspect ratio (contain).
4. **Caching Logic**:
   - Generate a unique thumbnail path based on `image_id`, `width`, `height`, and image format.
   - **Crucial**: Check if the thumbnail file exists *inside* the `Image.open()` context manager, as the image format is required to generate the path.
   - If the thumbnail exists, return it immediately using `FileResponse`.
   - If not, generate the thumbnail, save it to the cache directory, and then return it.
5. **Security**: Validate the `image_id` against the database to retrieve the file path. Do not accept arbitrary file paths from the user.
6. **Dependencies**: Use `PIL` (Pillow) for image manipulation and `fastapi.responses.FileResponse` for serving files.

# Anti-Patterns
- Do not check for cached thumbnails before opening the source image, as the file extension/format is needed for the cache path.
- Do not allow the frontend to request files by arbitrary path strings.
- Do not use `response.ok` when using Axios; check `response.data` directly.

## Triggers

- create an endpoint to serve thumbnails
- resize image based on aspect ratio
- implement image caching in FastAPI
- crop image to fit dimensions
- serve images with width and height parameters