Muốn tạo bài viết kèm ảnh đại diện trong một request, bạn cần gửi cả text lẫn file qua multipart/form-data. FastAPI giải quyết bằng cách khai báo trường text bằng Form() và file bằng File() trong cùng chữ ký hàm — framework tự tách hai phần và trả 422 khi thiếu dữ liệu. Cách này dùng cho mọi endpoint nhận form kèm file: đăng bài kèm ảnh, cập nhật hồ sơ kèm avatar, hay import CSV kèm ghi chú.

Vấn đề

Endpoint tạo bài viết kèm ảnh thường được viết thế này — một model Pydantic cho phần text, một UploadFile cho ảnh:

from fastapi import FastAPI, File, UploadFile
from pydantic import BaseModel
app = FastAPI()
class PostCreate(BaseModel):
title: str
caption: str | None = None
@app.post("/posts/")
async def create_post(post: PostCreate, image: UploadFile = File(...)):
return {"title": post.title}

Nhìn thì hợp lý, nhưng endpoint này không bao giờ nhận được request hợp lệ. FastAPI gom cả model thành một trường form lồng nhau tên post, trong khi client thường gửi title, caption rời rạc và file image — kết quả mọi request đều trả 422 Field required cho body post. App vẫn chạy bình thường nên lỗi chỉ lộ khi test thật. Gửi JSON kèm file cũng vô ích — endpoint có File() bắt buộc nhận multipart/form-data.

Giải pháp

Bỏ model khỏi chữ ký hàm, khai báo từng trường text bằng Form() và giữ UploadFile cho file:

from fastapi import FastAPI, File, Form, HTTPException, UploadFile
app = FastAPI()
ALLOWED_TYPES = {"image/jpeg", "image/png", "image/webp"}
MAX_SIZE = 5 * 1024 * 1024 # 5MB
@app.post("/posts/")
async def create_post(
title: str = Form(min_length=3, max_length=100),
caption: str | None = Form(default=None, max_length=500),
image: UploadFile = File(...),
):
if image.content_type not in ALLOWED_TYPES:
raise HTTPException(status_code=400, detail="chi nhan anh jpeg/png/webp")
data = await image.read()
if len(data) > MAX_SIZE:
raise HTTPException(status_code=413, detail="file qua 5MB")
return {
"title": title,
"caption": caption,
"filename": image.filename,
"size": len(data),
}

Giờ title và caption là các trường form riêng, mỗi trường vẫn validate như thường — title ngắn hơn 3 ký tự hay thiếu file image đều bị chặn bằng 422 trước khi hàm chạy. Đổi kiểu thành bytes = File(...) cũng được, nhưng UploadFile tốt hơn với file lớn vì FastAPI spool file ra đĩa tạm thay vì giữ hết trong RAM. Nhớ cài python-multipart, nếu không FastAPI báo lỗi ngay khi khởi động vì không đọc được form data. Phía client: curl dùng -F cho từng trường, requests dùng data= và files=, form HTML cần enctype="multipart/form-data".

Áp dụng vào dự án của bạn

Áp dụng ngay cho form tạo bài viết kèm ảnh đại diện, form cập nhật hồ sơ kèm avatar, hay form import dữ liệu kèm file CSV và ghi chú. Quy tắc nhớ một dòng: cứ có File() trong chữ ký thì toàn bộ phần còn lại phải là Form(), không trộn model JSON vào. Form nhiều trường text thì gom vào một dependency class: __init__ nhận các Form(), endpoint chỉ Depends class đó.

Bài viết liên quan

Câu hỏi thường gặp

Có dùng Pydantic model cho phần form text được không?

Không — mỗi trường form phải khai báo riêng bằng Form(). Nếu form có nhiều trường, gom chúng vào một dependency class: __init__ của class nhận các Form(), endpoint chỉ cần Depends class đó. Cách này đã kiểm chứng chạy được trên FastAPI 0.143.

File lớn thì dùng bytes hay UploadFile?

Dùng UploadFile. Với bytes, FastAPI đọc toàn bộ file vào RAM; với UploadFile, file được spool ra đĩa tạm và bạn đọc theo chunk bằng await file.read(size). File vài chục MB trở lên mà dùng bytes rất dễ làm server hết RAM.

Client gửi JSON kèm file thì sao?

Sẽ nhận 422. Endpoint có File() thì bắt buộc dùng multipart/form-data: curl dùng cờ -F cho từng trường, requests dùng data= cho text và files= cho file, form HTML phải có enctype="multipart/form-data". JSON body chỉ dùng được khi endpoint không có File() hay Form().

Thiếu python-multipart thì lỗi gì?

FastAPI báo lỗi ngay khi khởi động vì không đọc được form data. Cài bằng pip install python-multipart và khai báo trong requirements của dự án — thiếu gói này khi deploy là lỗi hay gặp nhất.

💬 Bạn đã thử cách này trong dự án của mình chưa? Nếu gặp lỗi hoặc có cách làm gọn hơn, để lại bình luận bên dưới — mình đọc hết và sẽ bổ sung những ý hay vào bài.

Nguồn tham khảo