18_ Request file

This section describes how to use File Declare the uploaded file as （ Form data ） Input parameters .

File Used to define the file uploaded by the client .

Because uploading files is based on “ The form data ”　 Send as . So receive uploaded files , To pre install python-multipart.

---

1. Import File：

When using , Need from fastapi Import File and UploadFile：

from fastapi import FastAPI, File, UploadFile

---

2. Definition File Parameters ：

create a file （File） The method of parameters is the same as before Body and Form Same parameter ：

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):  #  Definition File Parameters 
    return {
    "file_size": len(file)}

File It is directly inherited from Form Class , Import File when , It is actually a factory function that returns a specific class .

Tips ：

The declaration file body must use File, otherwise ,FastAPI This parameter will be treated as a query parameter or request body （JSON） Parameters .

File as “ The form data ” Upload . If the type of path operation function parameter is declared as bytes, FastAPI Will be with bytes Read and receive the contents of the file in the form of . In this way, all the contents of the file are stored in memory , Suitable for small files .

however , In many cases ,UploadFile Better to use .

---

3. contain UploadFile Of File Parameters ：

Definition File Parameter is used UploadFile:

from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):  #  Definition UploadFile Parameters 
    return {
    "filename": file.filename}

UploadFile And bytes Have more advantages than ：

• Use spooled file ：
  When the file stored in memory exceeds the maximum limit ,FastAPI Will save the file to disk ;
• This method is more suitable for processing images 、 video 、 Binary files and other large files , The advantage is that it won't take up all memory ;
• You can get the metadata of the uploaded file ;
• Bring their own file-likeasync Interface ;
• exposed python SpooledTemporaryFile Objects can be passed directly to other expectations file-like The library of objects .

UploadFile：

UploadFile The properties of are as follows ：

• filename： Upload file name string （str）, for example ,myimage.jpg;
• content_type： Content type （MIME type / Media type ） character string （str）, for example image/jpeg;
• file: SpooledTemporaryFile(file-like object ). In fact, that is python file , It can be passed directly to other intended uses file-like Object's function or support library .

UploadFile Support the following async Method ,（ Use the inside SpooledTemporaryFile） The corresponding file method can be called .

• write(data)： hold data（str or bytes） write file ;

• read(size)： A specified number of bytes or characters （size(int)) Read file contents ;

• seek(offset)： Move to file offset （int) Position at byte ;

  • Such as ,await myfile.seek(0) Move to the beginning of steadiness ;
  • perform await myfile.read() after , When you need to read the read content again , This method is particularly useful ;

• close(): Close file .

Because the above methods are async Method , So match await Use .

for example , stay async Path operation function in , To read the contents of the file in the following way ：

contents = await myfile.read()

If it's in ordinary def In path operation function , You can directly access UploadFile.file, Such as ：

contents = myfile.file.read()

async Technical details ：

Use async When the method is used ,FastAPI Method of executing files in the thread pool , and await Wait for the operation to complete .

Starlette Technical details ：

FastAPI Of UploadFile Inherit directly from Starlette Of UploadFile, But some necessary functions have been added , To that of the Pydantic And FastAPI Compatible with other components of .

---

4. What is? “ The form data ”？

And JSOn Different ,HTML Forms （<form></form>） Data sent to the server usually uses a 「 special 」 The coding , This is different from JSON Of .

FastAPI Make sure you read the data from the correct location , Instead of reading JSON.

Technical details ：

When files are not included , Form data is generally used application/x-www-form-urlencoded「 Media type 」 code .

But when the form contains files , Encoded as multipart/form-data. Used File,FastAPI You know to get the file from the correct location of the request body .

For details of codes and form fields, see MDN Web Document POST Section .

Warning ：

Multiple... Can be declared in one path operation File and Form Parameters , But you can't declare to receive at the same time JSON Of Body Field . Because the code of the request body is multipart/form-data, No application/json.

This is not FastAPI The problem of , It is HTTP Provisions of the agreement .

---

5. Optional file upload ：

We can use the standard type annotation and set the parameter default value to None Make a file optional ：

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes | None = File(default=None)):  #  Optional parameters 
    if not file:
        return {
    "message": "No file sent"}
    else:
        return {
    "file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):  #  Optional parameters 
    if not file:
        return {
    "message": "No upload file sent"}
    else:
        return {
    "filename": file.filename}

---

6. With additional metadata UploadFile：

We can also go through UploadFile To use File() To set additional metadata for the file ：

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File(description="A file read as bytes")):
    return {
    "file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(
    file: UploadFile = File(description="A file read as UploadFile"),  #  Add metadata 
):
    return {
    "filename": file.filename}

---

7. Multiple file upload ：

FastAPi Support to upload multiple files at the same time . These multiple files will be associated with the sent “ The form data ” The same in “ form field ”.

In order to use it , You need to declare a bytes or UploadFile A list of ：

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(files: list[bytes] = File()):  #  Multiple bytes A list of 
    return {
    "file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):  #  Multiple UploadFile A list of 
    return {
    "filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """ <body> <form action="/files/" enctype="multipart/form-data" method="post"> <input name="files" type="file" multiple> <input type="submit"> </form> <form action="/uploadfiles/" enctype="multipart/form-data" method="post"> <input name="files" type="file" multiple> <input type="submit"> </form> </body> """
    return HTMLResponse(content=content)

It also contains bytes or UploadFile A list of （list）.

Technical details ：

You can also use from starlette.responses import HTMLResponse.

fastapi.responses In fact, with starlette.responses identical , Just for the convenience of developers . actually , majority FastAPI All responses are directly from Starlette call .

Multi file upload with additional metadata ：

The same as before , We can use File() To set additional parameters , Even right UploadFile You can also set ：

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(
    files: list[bytes] = File(description="Multiple files as bytes"),  #  Set metadata for multiple files 
):
    return {
    "file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(
    files: list[UploadFile] = File(description="Multiple files as UploadFile"),  #  Set metadata for multiple files 
):
    return {
    "filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """ <body> <form action="/files/" enctype="multipart/form-data" method="post"> <input name="files" type="file" multiple> <input type="submit"> </form> <form action="/uploadfiles/" enctype="multipart/form-data" method="post"> <input name="files" type="file" multiple> <input type="submit"> </form> </body> """
    return HTMLResponse(content=content)