Arquivos de Requisição¶

Você pode definir arquivos para serem enviados para o cliente utilizando File.

Info

Para receber arquivos compartilhados, primeiro instale python-multipart.

E.g. pip install python-multipart.

Isso se deve por que arquivos enviados são enviados como "dados de formulário".

Importe `File`¶

Importe File e UploadFile do fastapi:

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, File, UploadFile
from typing_extensions import Annotated

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


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


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

Defina os parâmetros de `File`¶

Cria os parâmetros do arquivo da mesma forma que você faria para Body ou Form:

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, File, UploadFile
from typing_extensions import Annotated

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


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


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

Informação

File é uma classe que herda diretamente de Form.

Mas lembre-se que quando você importa Query,Path, File, entre outros, do fastapi, essas são na verdade funções que retornam classes especiais.

Dica

Para declarar o corpo de arquivos, você precisa utilizar File, do contrário os parâmetros seriam interpretados como parâmetros de consulta ou corpo (JSON) da requisição.

Os arquivos serão enviados como "form data".

Se você declarar o tipo do seu parâmetro na sua função de operação de rota como bytes, o FastAPI irá ler o arquivo para você e você receberá o conteúdo como bytes.

Lembre-se que isso significa que o conteúdo inteiro será armazenado em memória. Isso funciona bem para arquivos pequenos.

Mas existem vários casos em que você pode se beneficiar ao usar UploadFile.

Parâmetros de arquivo com `UploadFile`¶

Defina um parâmetro de arquivo com o tipo UploadFile

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, File, UploadFile
from typing_extensions import Annotated

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


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

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


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


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

Utilizando UploadFile tem várias vantagens sobre bytes:

Você não precisa utilizar File() como o valor padrão do parâmetro.
A classe utiliza um arquivo em "spool":
- Um arquivo guardado em memória até um tamanho máximo, depois desse limite ele é guardado em disco.
Isso significa que a classe funciona bem com arquivos grandes como imagens, vídeos, binários extensos, etc. Sem consumir toda a memória.
Você pode obter metadados do arquivo enviado.
Ela possui uma interface semelhante a arquivos async.
Ela expõe um objeto python SpooledTemporaryFile que você pode repassar para bibliotecas que esperam um objeto com comportamento de arquivo.

`UploadFile`¶

UploadFile tem os seguintes atributos:

filename: Uma string (str) com o nome original do arquivo enviado (e.g. myimage.jpg).
content-type: Uma str com o tipo do conteúdo (tipo MIME / media) (e.g. image/jpeg).
file: Um objeto do tipo SpooledTemporaryFile (um objeto file-like). O arquivo propriamente dito que você pode passar diretamente para outras funções ou bibliotecas que esperam um objeto "file-like".

UploadFile tem os seguintes métodos async. Todos eles chamam os métodos de arquivos por baixo dos panos (usando o objeto SpooledTemporaryFile interno).

write(data): escreve dados (data) em str ou bytes no arquivo.
read(size): Lê um número de bytes/caracteres de acordo com a quantidade size (int).
seek(offset): Navega para o byte na posição offset (int) do arquivo.
- E.g., await myfile.seek(0) navegaria para o ínicio do arquivo.
- Isso é especialmente útil se você executar await myfile.read() uma vez e depois precisar ler os conteúdos do arquivo de novo.
close(): Fecha o arquivo.

Como todos esses métodos são assíncronos (async) você precisa esperar ("await") por eles.

Por exemplo, dentro de uma função de operação de rota assíncrona você pode obter os conteúdos com:

contents = await myfile.read()

Se você estiver dentro de uma função de operação de rota definida normalmente com def, você pode acessar UploadFile.file diretamente, por exemplo:

contents = myfile.file.read()

Detalhes técnicos do async

Quando você utiliza métodos assíncronos, o FastAPI executa os métodos do arquivo em uma threadpool e espera por eles.

Detalhes técnicos do Starlette

O UploadFile do FastAPI herda diretamente do UploadFile do Starlette, mas adiciona algumas funcionalidades necessárias para ser compatível com o Pydantic

O que é "Form Data"¶

A forma como formulários HTML(<form></form>) enviam dados para o servidor normalmente utilizam uma codificação "especial" para esses dados, que é diferente do JSON.

O FastAPI garante que os dados serão lidos da forma correta, em vez do JSON.

Detalhes Técnicos

Dados vindos de formulários geralmente tem a codificação com o "media type" application/x-www-form-urlencoded quando estes não incluem arquivos.

Mas quando os dados incluem arquivos, eles são codificados como multipart/form-data. Se você utilizar File, FastAPI saberá que deve receber os arquivos da parte correta do corpo da requisição.

Se você quer ler mais sobre essas codificações e campos de formulário, veja a documentação online da MDN sobre POST .

Aviso

Você pode declarar múltiplos parâmetros File e Form em uma operação de rota, mas você não pode declarar campos Bodyque seriam recebidos como JSON junto desses parâmetros, por que a codificação do corpo da requisição será multipart/form-data em vez de application/json.

Isso não é uma limitação do FastAPI, é uma parte do protocolo HTTP.

Arquivo de upload opcional¶

Você pode definir um arquivo como opcional utilizando as anotações de tipo padrão e definindo o valor padrão como None:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes | None, File()] = None):
    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):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[Union[bytes, None], File()] = None):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: Union[UploadFile, None] = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

from typing import Union

from fastapi import FastAPI, File, UploadFile
from typing_extensions import Annotated

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[Union[bytes, None], File()] = None):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: Union[UploadFile, None] = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes | None = File(default=None)):
    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):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Union[bytes, None] = File(default=None)):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: Union[UploadFile, None] = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

`UploadFile` com Metadados Adicionais¶

Você também pode utilizar File() com UploadFile, por exemplo, para definir metadados adicionais:

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


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


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

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, File, UploadFile
from typing_extensions import Annotated

app = FastAPI()


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


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

Tip

Prefer to use the Annotated version if possible.

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"),
):
    return {"filename": file.filename}

Envio de Múltiplos Arquivos¶

É possível enviar múltiplos arquivos ao mesmo tmepo.

Ele ficam associados ao mesmo "campo do formulário" enviado com "form data".

Para usar isso, declare uma lista de bytes ou UploadFile:

Python 3.9+

from typing import Annotated

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

app = FastAPI()


@app.post("/files/")
async def create_files(files: Annotated[list[bytes], File()]):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    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)

🤓 Other versions and variants

Python 3.8+Python 3.9+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import List

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

app = FastAPI()


@app.post("/files/")
async def create_files(files: Annotated[List[bytes], File()]):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile]):
    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)

Tip

Prefer to use the Annotated version if possible.

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

app = FastAPI()


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


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    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)

Tip

Prefer to use the Annotated version if possible.

from typing import List

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

app = FastAPI()


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


@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile]):
    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)

Você irá receber, como delcarado uma lista (list) de bytes ou UploadFiles,

Detalhes Técnicos

Você também poderia utilizar from starlette.responses import HTMLResponse.

O FastAPI fornece as mesmas starlette.responses como fastapi.responses apenas como um facilitador para você, desenvolvedor. Mas a maior parte das respostas vem diretamente do Starlette.

Enviando Múltiplos Arquivos com Metadados Adicionais¶

E da mesma forma que antes, você pode utilizar File() para definir parâmetros adicionais, até mesmo para UploadFile:

Python 3.9+

from typing import Annotated

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

app = FastAPI()


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


@app.post("/uploadfiles/")
async def create_upload_files(
    files: Annotated[
        list[UploadFile], File(description="Multiple files as UploadFile")
    ],
):
    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)

🤓 Other versions and variants

Python 3.8+Python 3.9+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import List

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

app = FastAPI()


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


@app.post("/uploadfiles/")
async def create_upload_files(
    files: Annotated[
        List[UploadFile], File(description="Multiple files as UploadFile")
    ],
):
    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)

Tip

Prefer to use the Annotated version if possible.

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"),
):
    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"),
):
    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)

Tip

Prefer to use the Annotated version if possible.

from typing import List

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"),
):
    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"),
):
    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)

Recapitulando¶

Use File, bytes e UploadFile para declarar arquivos que serão enviados na requisição, enviados como dados do formulário.

Arquivos de Requisição¶

Importe File¶

Defina os parâmetros de File¶

Parâmetros de arquivo com UploadFile¶

UploadFile¶

O que é "Form Data"¶

Arquivo de upload opcional¶

UploadFile com Metadados Adicionais¶

Envio de Múltiplos Arquivos¶

Enviando Múltiplos Arquivos com Metadados Adicionais¶

Recapitulando¶

Importe `File`¶

Defina os parâmetros de `File`¶

Parâmetros de arquivo com `UploadFile`¶

`UploadFile`¶

`UploadFile` com Metadados Adicionais¶