PDF4me Python SDK Erste Schritte

Der pdf4me Paket auf PyPI ist die offizielle asynchrone Python SDK für die PDF4me REST APIEs enthält 106 typisierte asynchrone Funktionen in 18 Modulen, die Konvertierung, Optimierung, Zusammenführung, Aufteilung, Stempelung und elektronische Signatur abdecken. OCRFormularausfüllung, Datenextraktion, Barcodes, ZUGFeRD elektronische Rechnungsstellung und AI-basierte Dokumentenextraktion aus Rechnungen, Quittungen, Verträgen, Kontoauszügen, Steuerunterlagen und Gehaltsabrechnungen.

Verpackungsinformationen

Feld	Wert
Paketname	pdf4me
Aktuelle Version	1.0.2 (veröffentlicht am 14.09.2026)
Lizenz	MIT
Python Unterstützung	>=3.11 (getestet mit Version 3.11, 3.12, 3.13, 3.14)
Entwicklungsstand	Produktion/Stabil
Rahmen	AsyncIO
Quelle	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

Im Hintergrund wird der Client mit Microsoft generiert. Kiota obendrauf httpx[http2]Daher ist jede Aktion vollständig typisiert, liefert typisierte Ergebnisse und verwendet pro Client einen Verbindungspool wieder.

Voraussetzungen

• Python 3.11 oder neuer.
• A PDF4me Konto und API Schlüssel.
• pip (oder uv, poetryoder irgendeine PyPI(kompatibles Installationsprogramm).

Hol dir deins API Schlüssel

Ansehen auf PyPI

Ansehen auf GitHub

Installieren

pip

python -m pip install pdf4me

uv

uv add pdf4me

Poetry

poetry add pdf4me

Installation pdf4me zieht an httpx[http2] und Microsoft Kiota Laufzeitpakete (microsoft-kiota-abstractions, microsoft-kiota-http, und die JSON-, Formular-, Text- und Multipart-Serialisierungs-Backends).

Authentifizieren

Stellen Sie Ihre API Schlüsselelement in der Umwelt:

Bash / Zsh

export PDF4ME_API_KEY="your-api-key"

PowerShell

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

Windows CMD

set PDF4ME_API_KEY=your-api-key

Die folgenden Beispiele lesen den Schlüssel zur Laufzeit aus dieser Variable. Sie können ihn auch direkt übergeben. Pdf4meClient(api_key) Wenn Sie es lieber über einen Geheimnismanager laden möchten, .env Datei oder eine andere Quelle.

Schnellstart

Das kleinste nützliche Programm: einen Client öffnen, eine Aktion ausführen, das Ergebnis auf die Festplatte schreiben.

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())

Drei Dinge, die man beachten sollte:

1. Ein Kunde, viele Anrufe. Der async with Pdf4meClient(...) Der Kontext steuert die zugrunde liegende httpx Verbindungspool. Derselbe Client wird für jeden Aufruf innerhalb des Verbindungspools wiederverwendet. main anstatt für jede Aktion ein separates Fenster zu öffnen.
2. Aktionen sind freie Funktionen, keine Clientmethoden. Importiere jede Aktion aus ihrem Modul (from pdf4me.optimize import optimize, from pdf4me.pdf import get_pdf_metadata) und übergeben Sie den Client als erstes Argument. Dadurch bleibt die Schnittstelle flach und Sie können ungenutzte Module in Ihrem Editor per Tree-Shaking entfernen.
3. Bytes rein, Bytes raus. Aktionen, die eine Datei zurückgeben bytesAktionen, die Metadaten erzeugen, geben typisierte Datenklassen zurück. Es findet keine Zwischenspeicherung auf der Festplatte statt, sodass Ergebnisse zwischen Aktionen weitergeleitet werden können, ohne das Dateisystem zu verändern.

Zwei weitere häufige Anrufe

Stempel a PDF:

from pdf4me.edit import StampAlignX, stamp

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

Lesen PDF Metadaten:

from pdf4me.pdf import get_pdf_metadata

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

Jeder als Enum übergebene Wert (wie StampAlignX.Center) ist eine typisierte Konstante, also Ihre IDE Die zulässigen Werte werden automatisch vervollständigt und mypy bzw. pyright erkennen Tippfehler bereits bei der Bearbeitung.

Was ist in der Box enthalten (106 Aktionen in 18 Modulen)

Modul	Aktionen	Importbeispiel
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

Die oben aufgeführten Importpfade veranschaulichen die Modulstruktur. Siehe die PDF4me REST API Referenz die vollständige Parameterliste für jede Aktion und das Quell-Repository pdf4me/ Paketstruktur für die exakten Symbolnamen, die Ihre Version exportiert.

Wohin als Nächstes?

PDF4me REST API Referenz

Quelle auf GitHub

Ein Problem melden

Fehlerbehebung

ModuleNotFoundError: No module named 'pdf4me'Die Das Paket ist in einem anderen Interpreter installiert als dem, der Ihr Skript ausführt. Bestätigen Sie mit python -m pip show pdf4me innerhalb derselben virtuellen Umgebung. Wenn Sie verwenden pyenv oder condaAktivieren Sie zuerst die Umgebung.

SystemExit: Set PDF4ME_API_KEY before running this example. Die Umgebungsvariable ist für Ihren Prozess nicht sichtbar. Starten Sie Ihre Shell anschließend neu. exportoder übergeben Sie den Schlüssel direkt mit Pdf4meClient("your-api-key")Unter Windows sollten Sie Folgendes beachten: set Einstellungen innerhalb der CMD-Konsole bleiben nicht sitzungsübergreifend erhalten; verwenden Sie setx für einen dauerhaften Wert.

httpx.HTTPStatusError: 401 UnauthorizedDie Der API Der Schlüssel ist vorhanden, wurde aber abgelehnt. Generieren Sie ihn neu. PDF4me Armaturenbrett und versuchen Sie es erneut.

Langsamer erster Anruf nach einer Phase der Inaktivität. HTTP/2 Keep-Alive-Resets im Leerlauf. Behalten Sie die Pdf4meClient Die Datei sollte für die gesamte Laufzeit eines Batch-Jobs geöffnet bleiben, anstatt für jede Datei eine neue Datei zu öffnen.

asyncio.run() cannot be called from a running event loopDie Du bist im Inneren Jupyter oder ein Framework, das bereits eine Ereignisschleife ausführt. await main() entweder auf der obersten Ebene einer Notebook-Zelle oder indem Sie Ihren Code in den eigenen asynchronen Einstiegspunkt des Frameworks einbetten.