How does FastAPI return a file byte stream? And comes with some json parameters

GET method StreamingResponse

server:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from starlette.responses import FileResponse
from pydantic import BaseModel

app = FastAPI()


# 创建一个 Base 模型，用于表示其他的 JSON 信息
class AdditionalInfo(BaseModel):
    message: str
    status: str


@app.get("/get_demo_image_with_json")
async def get_demo_image_with_json():
    # 从文件中读取字节流
    file_path = "face.png"
    file_like = open(file_path, mode="rb")

    # 模拟其他的 JSON 信息
    json_info = AdditionalInfo(message="Image loaded successfully", status="OK")

    # 使用 StreamingResponse 返回字节流和其他的 JSON 信息
    return StreamingResponse(file_like, media_type="image/jpeg",
                             headers={
    
    "Additional-Info": json_info.model_dump_json()})


if __name__ == '__main__':
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

Client:

import requests

url = "http://127.0.0.1:8000/get_demo_image_with_json"

response = requests.get(url)

# 检查请求是否成功
if response.status_code == 200:
    # 获取文件的字节流
    image_data = response.content

    # 处理其他的 JSON 信息
    additional_info = response.headers.get("Additional-Info")

    # 在此处添加您的处理逻辑，例如保存字节流到文件，解析 JSON 信息等
    # ...

    print("Image loaded successfully.")
    print(f"Additional Info: {additional_info}")

else:
    print(f"Failed to fetch image. Status code: {response.status_code}")

POST method StreamingResponse

Server code:

import io

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import StreamingResponse
from pydantic import BaseModel

app = FastAPI()


# 创建一个 Base 模型，用于表示其他的 JSON 信息
class AdditionalInfo(BaseModel):
    message: str
    status: str


@app.post("/get_demo_image_with_json")
async def get_demo_image_with_json():
    #  读取face.png
    image_data = open("face.png", "rb").read()

    # 模拟其他的 JSON 信息
    json_info = AdditionalInfo(message="Image loaded successfully", status="OK")

    # 使用 StreamingResponse 返回字节流和其他的 JSON 信息
    return StreamingResponse(io.BytesIO(image_data), media_type="image/png",
                             headers={
    
    "Additional-Info": json_info.model_dump_json()})


if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Client parameters:

import requests

url = "http://127.0.0.1:8000/get_demo_image_with_json"

response = requests.post(url)

# 检查请求是否成功
if response.status_code == 200:
    # 获取文件的字节流
    image_data = response.content
    # 写入文件
    with open("demo_image_with_json.png", "wb") as fp:
        fp.write(image_data)
    # 打印其他参数
    print(response.headers["Additional-Info"])

else:
    print(f"Failed to fetch image. Status code: {response.status_code}")

other

There are also FileResponse and base64.
FileResponse is too superficial and base64 is too large for large files.

In FastAPI, the main ways of returning a file byte stream include using StreamingResponse and FileResponse. Both of these can be used to return binary data, such as image files.

1. StreamingResponse: is suitable for sending data in a streaming manner. It is especially useful for large files because it allows sending the data as it is generated rather than waiting for the entire data set to be available. .

   from fastapi.responses import StreamingResponse
   
   @app.get("/get_demo_image")
   async def get_demo_image():
       image_data = open("face.png", "rb").read()
       return StreamingResponse(io.BytesIO(image_data), media_type="image/png")
   

2. FileResponse: is suitable for returning files. The file content can be read from the file system path, or the file content can be passed directly through the content parameter.

   from fastapi.responses import FileResponse
   
   @app.get("/get_demo_image")
   async def get_demo_image():
       image_data = open("face.png", "rb").read()
       return FileResponse(content=image_data, media_type="image/png")
   

Both approaches are valid, and the specific choice may depend on your application's needs and performance considerations. If you wish to send files asynchronously, you may prefer StreamingResponse. If you are just returning files from the file system, FileResponse is a simpler option.

About compression

FastAPI本身没有直接支持响应内容压缩的中间件，但你可以通过使用 Starlette 的中间件来实现这一功能。具体来说，Starlette 提供了 `Middleware` 类，你可以使用它来定义自定义中间件。以下是一个简单的例子，演示如何使用 Gzip 中间件来压缩响应内容：

```python
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from starlette.responses import FileResponse
from starlette.middleware.gzip import GZipMiddleware
from pydantic import BaseModel

app = FastAPI()

# 使用 Gzip 中间件
app.add_middleware(GZipMiddleware, minimum_size=1000, compress_level=6)

# 创建一个 Base 模型，用于表示其他的 JSON 信息
class AdditionalInfo(BaseModel):
    message: str
    status: str

@app.get("/get_demo_image_with_json")
async def get_demo_image_with_json():
    # 从文件中读取字节流
    file_path = "face.png"
    file_like = open(file_path, mode="rb")

    # 模拟其他的 JSON 信息
    json_info = AdditionalInfo(message="Image loaded successfully", status="OK")

    # 使用 StreamingResponse 返回字节流和其他的 JSON 信息
    return StreamingResponse(file_like, media_type="image/jpeg",
                             headers={
    
    "Additional-Info": json_info.json()})

In the above code, you enable Gzip compression by adding GZipMiddleware to the FastAPI application. The byte stream returned in StreamingResponse is compressed during transmission. Note that Gzip compression may increase CPU usage, but usually significantly reduces the amount of data transferred and improves performance. You can adjust the minimum_size and compress_level parameters according to your needs.