PDF4me Python SDK 入门

这 pdf4me 包裹 PyPI 是官方的异步 Python SDK 为了 PDF4me REST API它包含 106 个类型化的异步函数，分布在 18 个模块中，涵盖转换、优化、合并、拆分、加盖戳记、电子签名等功能。 OCR表格填写、数据提取、条形码 ZUGFeRD 电子发票，以及 AI基于 - 从发票、收据、合同、银行对账单、税务文件和工资单中提取文档。

包装信息

场地	价值
软件包名称	`pdf4me`
当前版本	`1.0.2` （发布于 2026 年 9 月 14 日）
执照	MIT
Python 支持	`>=3.11` （已在 3.11、3.12、3.13、3.14 版本上测试）
发展状况	生产/稳定
框架	异步IO
来源	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

客户端底层是由微软生成的。 Kiota 在……之上 httpx[http2]因此，每个操作都是完全类型化的，返回类型化的结果，并且每个客户端都重用一个连接池。

先决条件

Python 3.11 或更高版本。
A PDF4me 账户和 API 钥匙。
pip （或者 uv， poetry或任何 PyPI（兼容的安装程序）。

获得你的 API 钥匙

查看 PyPI

查看 GitHub

安装

pip
uv
Poetry

python -m pip install pdf4me

uv add pdf4me

poetry add pdf4me

安装 pdf4me 拉进来 httpx[http2] 以及微软 Kiota 运行时包（microsoft-kiota-abstractions， microsoft-kiota-http以及 JSON、表单、文本和多部分序列化后端）。

认证

设置你的 API 环境中的关键因素：

Bash / Zsh
PowerShell
Windows CMD

export PDF4ME_API_KEY="your-api-key"

$env:PDF4ME_API_KEY = "your-api-key"

set PDF4ME_API_KEY=your-api-key

以下示例在运行时从该变量读取键。您也可以直接将其传递给 Pdf4meClient(api_key) 如果您更喜欢从密钥管理器加载它， .env 文件或其他来源。

快速入门

最小的实用程序：打开一个客户端，运行一个操作，将结果写入磁盘。

import asyncio
import os
from pathlib import Path

from pdf4me import Pdf4meClient
from pdf4me.optimize import optimize


async def main() -> None:
    api_key = os.environ.get("PDF4ME_API_KEY")
    if not api_key:
        raise SystemExit("Set PDF4ME_API_KEY before running this example.")

    source = Path("input.pdf")
    async with Pdf4meClient(api_key) as client:
        result = await optimize(
            client, source.read_bytes(), doc_name=source.name
        )
    Path("optimized.pdf").write_bytes(result)
    print("Saved optimized.pdf")


if __name__ == "__main__":
    asyncio.run(main())

三点需要注意：

一个客户，多个电话。 这 async with Pdf4meClient(...) 上下文管理底层 httpx 连接池。在连接池内，每次调用都重用同一个客户端。 main 而不是每次操作都打开一个。
Actions 是自由函数，而不是客户端方法。 从其模块导入每个操作（from pdf4me.optimize import optimize， from pdf4me.pdf import get_pdf_metadata并将客户端作为第一个参数传递。这样可以保持界面平坦，并允许你在编辑器中对未使用的模块进行 tree-shaking 操作。
输入字节，输出字节。 产生文件返回的操作 bytes生成元数据的操作会返回类型化的数据类。由于没有磁盘暂存，因此可以在操作之间传递结果而无需访问文件系统。

还有两种常见的呼叫

盖章 PDF：

from pdf4me.edit import StampAlignX, stamp

stamped = await stamp(client, data, text="DRAFT", align_x=StampAlignX.Center)
Path("stamped.pdf").write_bytes(stamped)

读 PDF 元数据：

from pdf4me.pdf import get_pdf_metadata

metadata = await get_pdf_metadata(client, data, doc_name="input.pdf")
print(metadata.page_count)

每个值都以枚举形式传递（例如 StampAlignX.Center) 是一个类型化的常量，所以你的 IDE 它能自动补全合法值，并且 mypy 或 pyright 能在编辑时捕获拼写错误。

盒子里包含哪些内容（18 个模块，共 106 个操作）

模块	行动	导入示例
`pdf4me.ai_document_extraction`	14	`from pdf4me.ai_document_extraction import extract_invoice_data`
`pdf4me.barcode`	7	`from pdf4me.barcode import create_barcode, read_barcodes`
`pdf4me.convert`	13	`from pdf4me.convert import html_to_pdf, url_to_pdf, word_to_pdf`
`pdf4me.edit`	7	`from pdf4me.edit import stamp, add_page_number, add_html_header_footer`
`pdf4me.excel`	1	`from pdf4me.excel import excel_to_pdf`
`pdf4me.extract`	8	`from pdf4me.extract import extract_text, extract_attachments`
`pdf4me.find_search`	2	`from pdf4me.find_search import find_and_replace_text`
`pdf4me.forms`	2	`from pdf4me.forms import fill_pdf_form, get_form_fields`
`pdf4me.generate`	6	`from pdf4me.generate import generate_document_single`
`pdf4me.image`	13	`from pdf4me.image import resize_image, add_watermark_to_image`
`pdf4me.merge_split`	5	`from pdf4me.merge_split import merge_pdfs, split_pdf_by_barcode`
`pdf4me.optimize`	1	`from pdf4me.optimize import optimize`
`pdf4me.organize`	5	`from pdf4me.organize import rotate_pdf, extract_pages`
`pdf4me.pdf`	16	`from pdf4me.pdf import get_pdf_metadata, sign_pdf`
`pdf4me.pdf4me`	1	`from pdf4me.pdf4me import ping`
`pdf4me.security`	2	`from pdf4me.security import protect_document, unlock_pdf`
`pdf4me.word`	2	`from pdf4me.word import add_tracked_changes`
`pdf4me.zugferd`	1	`from pdf4me.zugferd import create_zugferd_invoice`

以上导入路径仅用于说明模块接口。请参阅…… PDF4me REST API 参考有关每个操作的完整参数列表以及源代码库的 pdf4me/ 包含您版本导出的确切符号名称的包树。

接下来该去哪里？

PDF4me REST API 参考

来源 GitHub

报告问题

故障排除

ModuleNotFoundError: No module named 'pdf4me'。 该软件包安装在与运行脚本的解释器不同的解释器中。请确认。 python -m pip show pdf4me 在同一个虚拟环境中。如果您使用 pyenv 或者 conda首先激活环境。

SystemExit: Set PDF4ME_API_KEY before running this example. 您的进程无法访问该环境变量。请重启您的 shell。 export或者直接传递密钥 Pdf4meClient("your-api-key")在Windows系统上，请记住…… set 在 CMD 内部执行的操作不会跨会话持久化；请使用 setx 具有永久价值。

httpx.HTTPStatusError: 401 Unauthorized。 这 API 密钥存在但被拒绝。请在以下位置重新生成密钥： PDF4me 仪表板再试一次。

一段时间不活动后，首次通话速度较慢。 HTTP/2 空闲时保持连接重置。保持 Pdf4meClient 在批处理作业的整个生命周期内保持打开状态，而不是为每个文件打开一个新窗口。

asyncio.run() cannot be called from a running event loop。 你已进入 Jupyter 或者使用一个已经运行事件循环的框架。 await main() 在笔记本单元格的顶层，或者将你的代码包装在框架自身的异步入口点中。

包装信息​

先决条件​

安装​

认证​

快速入门​

还有两种常见的呼叫​

盒子里包含哪些内容（18 个模块，共 106 个操作）​

接下来该去哪里？​

故障排除​