Notion File Uploads API 全链路工程实战:Single-Part 直传、Multi-Part 大文件分片合并、external_url 异步拉取与块封面挂载指南
一、为什么通过 API 写入图片、PDF 与大文件不能再只靠临时外链? #
在搭建自动化报销归档、CI/CD 测试报告同步、客户合同入库或企业 AI 知识库图文采集管道时,研发团队长期面临一个棘手限制:过去 Notion API 仅允许传入公开可访问的 external.url。这导致系统不得不先自建 OSS/S3 公网图床,一旦开启防盗链、鉴权过期或第三方图床下线,Notion 页面就会出现大面积裂图与下载失败(媒体基础用法参阅 上传文件指南 与 页面图标与封面指南)。
随着 Notion 官方推出 File Uploads API(/v1/file_uploads),集成终于能够把私有二进制文件真正交由 Notion 原生托管。但在实际落地中,开发团队仍常遇到四类工程误区(Files & media 属性设计可结合参阅 Files & media 属性深度实战):
- 超过 20MB 的文件直接走
single_part报错400/413:单文件直传模式的硬上限为20MB,大型设计稿、长视频或归档压缩包必须切换为multi_part分片模式并在末片传完后显式调用/complete。 - 创建上传会话后迟迟未绑定页面,导致
file_upload_id过期失效:上传成功的会话仅是“待挂载状态”,若在expiry_time(默认约 1 小时)内未将其挂载到任意page、block或Files & media属性中,对象会被服务端自动清理。 - 误以为
/v1/file_uploads返回的链接是永久公网直链:原生托管文件在读取 API 时同样返回约 1 小时有效期的临时签名 URL,不可直接硬编码到外部静态网站,应按需刷新或同步保留对象 ID。 - 忽略
external_url模式把公网临时链接原生转存进 Notion:当上游系统给出带时效签名的发票下载链时,无需先下载到本地再转发,可直接用mode: "external_url"让 Notion 服务器异步拉取托管。
上传模式(Notion-Version: 2025-09-03) | 文件体积与来源限制 | 调用链路步骤 | 状态流转与超时特征 | 最优工程适用场景 |
|---|---|---|---|---|
single_part | 本地或内存文件 ≤ 20MB | 1. POST /v1/file_uploads2. POST .../send3. 绑定至页面/块/属性 | 发送后立即变为 uploaded;需在 1 小时内完成绑定 | PDF 发票、合同扫描件、常规截图、自动化报表 |
multi_part | 大文件 > 20MB(需工作区付费版额度支撑) | 1. POST /v1/file_uploads(声明 number_of_parts)2. 分片调用 POST .../send3. POST .../complete4. 绑定至页面/块/属性 | 全部分片送达并调用 /complete 后转为 uploaded | 录屏演示视频、安装包归档、大型数据集与高精设计源文件 |
external_url | 公开 HTTPS 直链(无需本地中转二进制流) | 1. POST /v1/file_uploads(传 external_url)2. 轮询 GET /v1/file_uploads/{id}3. 绑定至页面/块/属性 | 异步队列拉取,状态从 pending 转为 uploaded 或 failed | 从企业临时签名 URL、第三方 Webhook 附件链原生转存归档 |
传统 type: "external" | 仅存储外部 URL 引用,不占用 Notion 存储 | 直接传入 POST /v1/pages 或 PATCH /v1/blocks | 无托管转存步骤;外部链接失效即裂图 | 已有企业永久 CDN/R2 域名且需跨系统共用同一 URL 的资产 |
二、File Uploads API 生命周期规范与多位置绑定实战 #
结合 创建 Notion API 集成指南、Pages API 工程指南 与 Blocks API 递归读写实战,构建可靠的文件入库管线应严格遵守以下四项核心规范:
- 按文件大小与工作区计划自动路由上传模式:
- 上传前先校验工作区权限与文件字节数。Notion 免费版单文件上限为
5MB,付费版(Plus 及以上)支持更大单文件;通过 API 处理≤ 20MB文件固定走single_part,> 20MB时按10MB(最小5MB,最后一片可小于5MB)切分并计算精确number_of_parts走multi_part。
- 上传前先校验工作区权限与文件字节数。Notion 免费版单文件上限为
- 显式绑定到正文块、页面封面或数据库属性:
- 上传状态变为
uploaded后,即可通过{"type": "file_upload", "file_upload": {"id": "<file_upload_id>"}}挂载至不同载体:- 正文媒体块(
PATCH /v1/blocks/{page_id}/children):支持image、pdf、file、video、audio等块类型,将外层external替换为file_upload即可渲染原生预览卡片; - 页面封面与图标(
PATCH /v1/pages/{page_id}):可用于cover或icon节点,让企业报告页面自动生成统一品牌封面,不再依赖易失效的外链图片; - 数据库
Files & media属性:注意PATCH会覆盖整格数组,若需保留历史附件,须先GET读取现有数组再追加新对象。
- 正文媒体块(
- 上传状态变为
- 对
external_url实施指数退避状态轮询:- 异步拉取并非瞬时完成。发起创建请求后若
status == "pending",应间隔1s -> 2s -> 4s调用GET /v1/file_uploads/{file_upload_id},确认进入uploaded后再执行页面绑定;若变为failed,需读取file_import_result.error排查目标源站是否拦截了 User-Agent 或返回403/404。
- 异步拉取并非瞬时完成。发起创建请求后若
- 周期性清理或巡检未绑定的孤儿上传会话:
- 调用
GET /v1/file_uploads?status=pending或status=uploaded可分页检索当前集成创建但尚未消费的上传会话,便于在任务中断恢复时识别是否已在expiry_time内失效,避免拿着过期id去调pages接口引发400。
- 调用
三、Python 实战:Multi-Part 大文件分片合并与 External URL 异步转存 #
以下脚本完整演示如何在 Notion-Version: 2025-09-03 下,封装兼顾 大文件 multi_part 自动切片合并 与 external_url 异步拉取轮询 的生产级客户端,并直接将结果挂载为页面 pdf / image 正文块(含 429 Retry-After 退避):
import math
import os
import time
from pathlib import Path
from typing import Any
import httpx
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
BASE_URL = "https://api.notion.com/v1"
JSON_HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2025-09-03",
"Content-Type": "application/json",
}
AUTH_HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2025-09-03",
}
CHUNK_SIZE = 10 * 1024 * 1024 # 每片 10MB(满足 5MB~20MB 分片规范)
def request_with_retry(
client: httpx.Client,
method: str,
path: str,
**kwargs: Any,
) -> dict[str, Any]:
url = f"{BASE_URL}{path}"
for attempt in range(5):
resp = client.request(method, url, timeout=60.0, **kwargs)
if resp.status_code == 429:
wait_sec = float(resp.headers.get("Retry-After", 2 ** attempt)) + 0.3
time.sleep(wait_sec)
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError(f"Notion File Uploads API 请求重试耗尽: {method} {path}")
def upload_large_file_multipart(client: httpx.Client, file_path: Path, content_type: str) -> str:
"""超过 20MB 的本地文件:创建 multi_part 会话 -> 分片发送 -> 调用 /complete 合并"""
file_size = file_path.stat().st_size
total_parts = max(1, math.ceil(file_size / CHUNK_SIZE))
# 1. 创建 multi_part 上传会话
session = request_with_retry(
client,
"POST",
"/file_uploads",
headers=JSON_HEADERS,
json={
"mode": "multi_part",
"filename": file_path.name,
"content_type": content_type,
"number_of_parts": total_parts,
},
)
upload_id = session["id"]
# 2. 按序发送二进制分片(part_number 从 1 开始)
with file_path.open("rb") as fh:
for part_idx in range(1, total_parts + 1):
chunk = fh.read(CHUNK_SIZE)
request_with_retry(
client,
"POST",
f"/file_uploads/{upload_id}/send",
headers=AUTH_HEADERS,
data={"part_number": str(part_idx)},
files={"file": (file_path.name, chunk, content_type)},
)
time.sleep(0.35)
# 3. 通知服务端合并分片并验证状态
completed = request_with_retry(
client,
"POST",
f"/file_uploads/{upload_id}/complete",
headers=JSON_HEADERS,
)
if completed.get("status") != "uploaded":
raise RuntimeError(f"分片合并异常,当前状态: {completed.get('status')}")
return upload_id
def import_external_url(client: httpx.Client, filename: str, external_url: str, max_polls: int = 12) -> str:
"""让 Notion 服务端直接从外部 HTTPS 链接异步拉取并托管"""
session = request_with_retry(
client,
"POST",
"/file_uploads",
headers=JSON_HEADERS,
json={
"mode": "external_url",
"filename": filename,
"external_url": external_url,
},
)
upload_id = session["id"]
for attempt in range(max_polls):
status_obj = request_with_retry(client, "GET", f"/file_uploads/{upload_id}", headers=AUTH_HEADERS)
state = status_obj.get("status")
if state == "uploaded":
return upload_id
if state in ("failed", "expired"):
raise RuntimeError(f"外部 URL 拉取失败 ({state}): {status_obj.get('file_import_result')}")
time.sleep(min(8.0, 1.0 * (1.5 ** attempt)))
raise TimeoutError(f"等待 external_url 转存超时: {upload_id}")
def append_uploaded_pdf_block(client: httpx.Client, page_id: str, upload_id: str) -> None:
"""将状态为 uploaded 的 file_upload_id 挂载为页面正文 PDF 预览块"""
request_with_retry(
client,
"PATCH",
f"/blocks/{page_id}/children",
headers=JSON_HEADERS,
json={
"children": [
{
"object": "block",
"type": "pdf",
"pdf": {
"type": "file_upload",
"file_upload": {"id": upload_id},
},
}
]
},
)
四、Formula 2.0 实战:文件直传批次状态与 S3 临时链接过期门禁 #
在企业级《自动化数字资产入库与文件传输台账》中(架构设计参阅 数据库架构设计速查 与 Formula 2.0 函数速查),可设立 上传模式(Select:single_part/multi_part/external_url/external)、上传状态(Select:pending/uploaded/failed/expired)、已绑定目标页(Checkbox)、会话过期时间(Date)与 文件大小MB(Number),通过以下 入库合规门禁 Formula 2.0 公式 实时拦截“未绑定即过期”与“大文件选错模式”故障:
lets(
mode, format(prop("上传模式")),
upStatus, format(prop("上传状态")),
isBound, prop("已绑定目标页"),
expTime, prop("会话过期时间"),
sizeMb, prop("文件大小MB"),
minutesLeft, if(empty(expTime), 999, dateBetween(expTime, now(), "minutes")),
ifs(
upStatus == "failed" || upStatus == "expired",
style("🚨 传输失败/会话已过期:请重新发起 /v1/file_uploads 会话", "red", "bold", "red_background"),
mode == "single_part" && sizeMb > 20,
style("⛔ 超出 20MB 上限:请将脚本路由切换为 multi_part 分片上传", "red", "bold", "red_background"),
upStatus == "uploaded" && !isBound && minutesLeft <= 15,
style("🔥 即将失效(剩 " + format(minutesLeft) + " 分钟):请立即绑定至 Page/Block", "red", "bold", "yellow_background"),
upStatus == "uploaded" && !isBound,
style("🟠 已上传未挂载:需尽快写入目标页面或 Files & media 属性", "orange", "bold"),
upStatus == "pending",
style("🟡 异步拉取/分片传输中 · 等待状态转为 uploaded", "blue"),
mode == "external",
style("🔵 外部直链引用 · 需确保源站具备永久防盗链白名单", "blue"),
style("🟢 原生托管已绑定 · 资产归档安全", "green")
)
)
五、文件上传高频报错排查与生产环境治理清单 #
上线自动化文件直传服务前,请对照核查以下高频排错要点(更多通用错误码参阅 Notion 常见报错与故障诊断手册):
- 调用
/send或/complete报400 validation_error(分片序号或大小不合规):- 检查
part_number是否严格从1开始连续递增(不可从0开始),且除最后一片外,其余每个分片大小必须处于 Notion 要求的分片区间(推荐统一设为10MB),number_of_parts必须与实际发送片数完全一致。
- 检查
- 调用
POST /v1/file_uploads返回403 restricted_resource:- 核实该集成在 Notion Developer Portal 中已勾选
Update content或Insert content能力;仅勾选Read content的只读集成无法发起文件上传会话。
- 核实该集成在 Notion Developer Portal 中已勾选
- 图片通过
external_url导入成功,但绑定后展示为下载文件而非内联图片:- 检查创建会话时传入的
filename扩展名与目标文件真实Content-Type(如image/png、application/pdf)是否一致;部分上游下载链接若缺少后缀名,需在创建会话时手动补全带后缀的规范文件名(例如report_2026.pdf)。
- 检查创建会话时传入的
- 如何避免超过免费工作区 5MB 限额引发批量入库中断?
- 脚本在批量归档前,先按文件体积分级:对大于工作区单文件限额的超大附件(或非核心归档视频),转存至企业对象存储后以
external链接配合Files & media挂载,将宝贵的原生托管额度集中留给核心合同、发票与高价值图片预览。
- 脚本在批量归档前,先按文件体积分级:对大于工作区单文件限额的超大附件(或非核心归档视频),转存至企业对象存储后以
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。