如何使用 Python Requests 库向 REST API 上传文件-Python教程-PHP中文网

如何使用 Python Requests 库向 REST API 上传文件

本文详解如何用 Python requests 库以 multipart/form-data 方式上传文件（如图片、文档）至 REST API，并对比 JSON 文本提交与文件上传的底层差异，附可运行代码示例与关键注意事项。

本文详解如何用 python `requests` 库以 `multipart/form-data` 方式上传文件（如图片、文档）至 rest api，并对比 json 文本提交与文件上传的底层差异，附可运行代码示例与关键注意事项。

在 Web 开发中，向 REST API 提交数据有两种常见场景：一是发送结构化文本（如 JSON），二是上传二进制文件（如图片、PDF）。二者底层 HTTP 协议机制截然不同——json=data 会将数据序列化为 UTF-8 字符串，设置 Content-Type: application/json；而文件上传必须使用 multipart/form-data 编码，它能安全混合文本字段与二进制流，并自动构造边界（boundary）分隔各部分。

requests 库通过 files 参数原生支持该协议。基本用法如下：

import requests

url = "https://abc.example.com/v1/upload"
files = {"image": open("/path/to/your/image.jpg", "rb")}
response = requests.post(url, files=files)

print(response.status_code)
print(response.text)

⚠️ 注意：files 字典的键（如 "image"）需与 API 文档要求的表单字段名严格一致（常对应后端接收的参数名，如 file、document 或 image）；值必须是以二进制模式打开的文件对象（"rb"），不可用字符串路径直接传入。

更规范的写法是使用上下文管理器确保文件正确关闭，并显式指定文件名与 MIME 类型（尤其当 API 依赖 Content-Type 时）：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

import requests

url = "https://abc.example.com/v1/upload"

# 推荐：显式控制文件元信息
with open("/path/to/photo.png", "rb") as f:
    files = {
        "image": ("photo.png", f, "image/png")  # (filename, fileobj, content_type)
    }
    response = requests.post(url, files=files)

print(f"Status: {response.status_code}")

你也可以同时上传多个文件或混合文本字段：

files = {
    "avatar": ("me.jpg", open("me.jpg", "rb"), "image/jpeg"),
    "cover": ("cover.pdf", open("cover.pdf", "rb"), "application/pdf")
}
data = {"user_id": "123", "description": "Profile assets"}  # 普通表单字段
response = requests.post(url, files=files, data=data)  # data 用于非文件字段

? 关键原理说明：
当传入 files 参数时，requests 会自动：

生成唯一的 boundary 字符串；
将每个文件按 RFC 7578 格式封装为独立 part，包含 Content-Disposition（含 name 和可选 filename）及 Content-Type 头；
设置请求头 Content-Type: multipart/form-data; boundary=...；
将整个 payload 组织为二进制字节流发送。

这与 curl -F 的行为完全等价，也是服务端框架（如 Flask 的 request.files、Django 的 request.FILES）识别上传文件的基础。

✅ 最佳实践总结：