What’s the best way to handle chat messages with optional file uploads?

Switching between JSON and multipart usually creates unnecessary complexity. Once a FastAPI route includes Form or File parameters, its body is expected to be form data, so supporting JSON as an alternate format may require another route or custom request handling. Also, depending on your CORS and authentication headers, JSON requests may trigger a preflight request, so using multipart consistently may not even be slower.

The simplest FastAPI shape would be something like `message: str = Form("")` and `file: UploadFile | None = File(None)`. Install `python-multipart`, since FastAPI needs it to parse form uploads. Also, don’t manually set the Content-Type header when using fetch with FormData—the browser adds the required multipart boundary automatically. If you hardcode `multipart/form-data` without that boundary, parsing can fail.

I’d use one multipart/form-data request for every chat submission. FastAPI can accept the text as a Form field and the file as an optional UploadFile, so a text-only message is still handled by the same endpoint. The extra multipart headers add almost no meaningful overhead, while separate requests can get out of sync or partially fail. You don’t need an actual form element either—just create a FormData object in JavaScript and append the message and file when present.