Notion File Uploads API 全链路工程实战:Single-Part 直传、Multi-Part 大文件分片合并、external_url 异步拉取与块封面挂载指南

2026 年 11 月 20 日

一、为什么通过 API 写入图片、PDF 与大文件不能再只靠临时外链? #

在搭建自动化报销归档、CI/CD 测试报告同步、客户合同入库或企业 AI 知识库图文采集管道时,研发团队长期面临一个棘手限制:过去 Notion API 仅允许传入公开可访问的 external.url。这导致系统不得不先自建 OSS/S3 公网图床,一旦开启防盗链、鉴权过期或第三方图床下线,Notion 页面就会出现大面积裂图与下载失败(媒体基础用法参阅 上传文件指南 与 页面图标与封面指南)。

随着 Notion 官方推出 File Uploads API(/v1/file_uploads),集成终于能够把私有二进制文件真正交由 Notion 原生托管。但在实际落地中,开发团队仍常遇到四类工程误区(Files & media 属性设计可结合参阅 Files & media 属性深度实战):

  1. 超过 20MB 的文件直接走 single_part 报错 400 / 413:单文件直传模式的硬上限为 20MB,大型设计稿、长视频或归档压缩包必须切换为 multi_part 分片模式并在末片传完后显式调用 /complete。
  2. 创建上传会话后迟迟未绑定页面,导致 file_upload_id 过期失效:上传成功的会话仅是“待挂载状态”,若在 expiry_time(默认约 1 小时)内未将其挂载到任意 page、block 或 Files & media 属性中,对象会被服务端自动清理。
  3. 误以为 /v1/file_uploads 返回的链接是永久公网直链:原生托管文件在读取 API 时同样返回约 1 小时有效期的临时签名 URL,不可直接硬编码到外部静态网站,应按需刷新或同步保留对象 ID。
  4. 忽略 external_url 模式把公网临时链接原生转存进 Notion:当上游系统给出带时效签名的发票下载链时,无需先下载到本地再转发,可直接用 mode: "external_url" 让 Notion 服务器异步拉取托管。
上传模式(Notion-Version: 2025-09-03) 文件体积与来源限制 调用链路步骤 状态流转与超时特征 最优工程适用场景
single_part 本地或内存文件 ≤ 20MB 1. POST /v1/file_uploads
2. POST .../send
3. 绑定至页面/块/属性
发送后立即变为 uploaded;需在 1 小时内完成绑定 PDF 发票、合同扫描件、常规截图、自动化报表
multi_part 大文件 > 20MB(需工作区付费版额度支撑) 1. POST /v1/file_uploads(声明 number_of_parts)
2. 分片调用 POST .../send
3. POST .../complete
4. 绑定至页面/块/属性
全部分片送达并调用 /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 递归读写实战,构建可靠的文件入库管线应严格遵守以下四项核心规范:

  1. 按文件大小与工作区计划自动路由上传模式:
    • 上传前先校验工作区权限与文件字节数。Notion 免费版单文件上限为 5MB,付费版(Plus 及以上)支持更大单文件;通过 API 处理 ≤ 20MB 文件固定走 single_part,> 20MB 时按 10MB(最小 5MB,最后一片可小于 5MB)切分并计算精确 number_of_parts 走 multi_part。
  2. 显式绑定到正文块、页面封面或数据库属性:
    • 上传状态变为 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 读取现有数组再追加新对象。
  3. 对 external_url 实施指数退避状态轮询:
    • 异步拉取并非瞬时完成。发起创建请求后若 status == "pending",应间隔 1s -> 2s -> 4s 调用 GET /v1/file_uploads/{file_upload_id},确认进入 uploaded 后再执行页面绑定;若变为 failed,需读取 file_import_result.error 排查目标源站是否拦截了 User-Agent 或返回 403/404。
  4. 周期性清理或巡检未绑定的孤儿上传会话:
    • 调用 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 常见报错与故障诊断手册):

  1. 调用 /send 或 /complete 报 400 validation_error(分片序号或大小不合规):
    • 检查 part_number 是否严格从 1 开始连续递增(不可从 0 开始),且除最后一片外,其余每个分片大小必须处于 Notion 要求的分片区间(推荐统一设为 10MB),number_of_parts 必须与实际发送片数完全一致。
  2. 调用 POST /v1/file_uploads 返回 403 restricted_resource:
    • 核实该集成在 Notion Developer Portal 中已勾选 Update content 或 Insert content 能力;仅勾选 Read content 的只读集成无法发起文件上传会话。
  3. 图片通过 external_url 导入成功,但绑定后展示为下载文件而非内联图片:
    • 检查创建会话时传入的 filename 扩展名与目标文件真实 Content-Type(如 image/png、application/pdf)是否一致;部分上游下载链接若缺少后缀名,需在创建会话时手动补全带后缀的规范文件名(例如 report_2026.pdf)。
  4. 如何避免超过免费工作区 5MB 限额引发批量入库中断?
    • 脚本在批量归档前,先按文件体积分级:对大于工作区单文件限额的超大附件(或非核心归档视频),转存至企业对象存储后以 external 链接配合 Files & media 挂载,将宝贵的原生托管额度集中留给核心合同、发票与高价值图片预览。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。