Dokumentacja API w języku Python

W skrócie

NextPDF Python Software Development Kit (SDK) udostępnia dwóch klientów, jedną wspólną przestrzeń nazw metod abstrakcyjnego drzewa składni (AST) o nazwie ast, modele Pydantic dla każdej odpowiedzi, interfejs wiersza poleceń (CLI) nextpdf oraz hierarchię wyjątków obejmującą sześć klas. Korzystaj z tej strony jako dokumentacji publicznych symboli interfejsu programowania aplikacji (API) do pracy z dokumentami Portable Document Format (PDF).

Zaimportuj publiczne symbole z pakietu najwyższego poziomu:

from nextpdf import (
    AsyncNextPDF,
    NextPDF,
    AstBuildTimeoutError,
    AstNoStructTreeError,
    NextPDFAPIError,
    NextPDFError,
    NextPDFLicenseError,
    QuotaExceededError,
)

Każda metoda ekstrakcji przyjmuje surowe bajty PDF (bytes) jako pierwszy argument pozycyjny i zwraca model Pydantic z typami. Opcje przekazuj wyłącznie jako argumenty nazwane. Synchroniczne metody NextPDF.ast.* oraz asynchroniczne metody AsyncNextPDF.ast.* mają identyczne sygnatury. Metody asynchroniczne są korutynami; wywołuj je za pomocą await.

Klient

Synchroniczny klient NextPDF stanowi opakowanie klienta asynchronicznego i wykonuje każdą korutynę do końca. AsyncNextPDF jest jednocześnie klientem asynchronicznym i asynchronicznym menedżerem kontekstu. Preferuj formę menedżera kontekstu, aby bazowy transport był zamykany w sposób deterministyczny.

Konstruktory

Symbol	Parametry	Domyślne zachowanie	Zwraca	Wyjątki / tryby niepowodzenia	Uwagi
NextPDF(*, base_url, api_key, api_version='v1')	Tylko nazwane: bazowy adres URL, klucz API oraz opcjonalna wersja API.	Tworzy synchronicznego klienta opartego na zdalnym backendzie.	NextPDF	ValueError, gdy base_url lub api_key jest pusty.	Wykonuje pracę asynchroniczną synchronicznie; bezpieczny w notebookach i w działającej pętli zdarzeń.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	Tylko nazwane: bazowy adres URL, klucz API, opcjonalna wersja API oraz opcjonalny wstrzyknięty backend.	Tworzy asynchronicznego klienta opartego na zdalnym backendzie, gdy nie wstrzyknięto backendu.	AsyncNextPDF	ValueError, gdy base_url lub api_key jest pusty i nie podano backend.	Przekaż backend=, aby w testach wstrzyknąć niestandardowy lub lokalny backend.
AsyncNextPDF.__aenter__()	Brak.	Wchodzi w kontekst asynchroniczny i zwraca klienta.	AsyncNextPDF	Nie oczekuje się żadnych.	Użyj async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Ignorowane argumenty wyjątku.	Wywołuje close() przy wyjściu z kontekstu.	None	Nie oczekuje się żadnych.	Zwalnia transport nawet wtedy, gdy ciało zgłosi wyjątek.
AsyncNextPDF.close()	Brak.	Zamyka własny zdalny backend i zwalnia pulę połączeń.	None	Nie oczekuje się żadnych.	Operacja idempotentna; wstrzyknięte backendy nie są zamykane.

Nie przechowuj klucza API w kodzie źródłowym. Odczytuj base_url i api_key ze środowiska (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) lub z menedżera sekretów.

import os

from nextpdf import AsyncNextPDF


async def extract(pdf_bytes: bytes) -> int:
    """Return the page count of a PDF using the async client as a context manager."""
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]

    async with AsyncNextPDF(base_url=base_url, api_key=api_key) as client:
        document = await client.ast.get_document_ast(pdf_bytes)
        return document.page_count

Synchroniczne metody AST — NextPDF.ast.*

Symbol	Parametry	Domyślne zachowanie	Zwraca	Wyjątki / tryby niepowodzenia	Uwagi
NextPDF.ast.get_document_ast()	pdf_data: bytes; argumenty nazwane page_range_start, page_range_end, token_budget.	Buduje pełne semantyczne drzewo AST dla każdej strony.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Zmniejsz zakres stron, jeśli budowanie przekroczy limit czasu.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; argumenty nazwane page_index, headings_only.	Wyodrębnia wszystkie bloki tekstu z kotwicami cytowań.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Ustaw headings_only=True, aby pobrać tylko węzły nagłówków.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; argumenty nazwane page_range (dict z start i end).	Wyodrębnia wszystkie tabele z kotwicami cytowań na poziomie komórek.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Pomiń page_range, aby przeskanować cały dokument.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Pobiera jeden węzeł na podstawie jego identyfikatora.	GetAstNodeResponse	NextPDFError, gdy węzeł nie zostanie znaleziony.	node_id ma format ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; argumenty nazwane node_type, page_index, text_query, max_results=100.	Zwraca płytkie węzły pasujące do filtrów.	SearchAstNodesResponse	NextPDFAPIError.	text_query dopasowuje podciąg bez uwzględniania wielkości liter.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Porównuje dwa dokumenty pod względem struktury.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Raportuje dodane, usunięte i zmienione węzły.

Asynchroniczne metody AST — AsyncNextPDF.ast.*

Każda metoda asynchroniczna jest korutyną o tych samych parametrach, wartościach domyślnych, typie zwracanym i trybach niepowodzenia co jej synchroniczny odpowiednik. Wywołuj ją za pomocą await wewnątrz środowiska wykonawczego asyncio.

Symbol	Parametry	Domyślne zachowanie	Zwraca	Wyjątki / tryby niepowodzenia	Uwagi
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; argumenty nazwane page_range_start, page_range_end, token_budget.	Buduje pełne semantyczne drzewo AST dla każdej strony.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Użyj await dla wyniku.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; argumenty nazwane page_index, headings_only.	Wyodrębnia wszystkie bloki tekstu z kotwicami cytowań.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Użyj await dla wyniku.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; argumenty nazwane page_range.	Wyodrębnia wszystkie tabele z kotwicami cytowań na poziomie komórek.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Użyj await dla wyniku.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Pobiera jeden węzeł na podstawie jego identyfikatora.	GetAstNodeResponse	NextPDFError, gdy węzeł nie zostanie znaleziony.	Użyj await dla wyniku.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; argumenty nazwane node_type, page_index, text_query, max_results=100.	Zwraca płytkie węzły pasujące do filtrów.	SearchAstNodesResponse	NextPDFAPIError.	Użyj await dla wyniku.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Porównuje dwa dokumenty pod względem struktury.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Użyj await dla wyniku.

Użyj klienta asynchronicznego jako menedżera kontekstu, aby wykonać dwie ekstrakcje współbieżnie w jednej grupie:

import asyncio

from nextpdf import AsyncNextPDF


async def extract_pair(first: bytes, second: bytes) -> None:
    """Extract two PDFs concurrently with one shared async client."""
    async with AsyncNextPDF(base_url="https://connect.example.com", api_key="set-from-secret") as client:
        text_blocks, tables = await asyncio.gather(
            client.ast.extract_cited_text(first),
            client.ast.extract_cited_tables(second),
        )
        print(f"text blocks: {len(text_blocks)}; tables: {tables.table_count}")

Modele

Każda odpowiedź jest modelem Pydantic. Importuj klasy modeli z nextpdf lub nextpdf.models.ast.

Symbol	Rodzaj	Kluczowe pola	Uwagi
AstDocument	Korzeń dokumentu	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (właściwość).	Zwracany przez get_document_ast(). Akceptuje aliasy schemaVersion, sourceHash oraz pageCount.
AstNode	Węzeł drzewa	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Rekurencyjny węzeł reprezentujący drzewo dokumentu.
AstNodeMeta	Metadane odpowiedzi	etag, pages_processed.	Zamrożony; dołączany do odpowiedzi węzła i wyszukiwania.
AstNodeShallow	Trafienie wyszukiwania	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Zamrożony; bez zagnieżdżonych potomków.
BoundingBox	Obiekt wartości	x, y, width, height (każda od 0.0–1.0).	Znormalizowane współrzędne w obrębie strony.
CitationAnchor	Obiekt wartości	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Rekord pochodzenia dla każdego bloku.
CitedTextBlock	Blok tekstu	text, citation: CitationAnchor, node_type, chunk_index, depth.	Każdy element listy extract_cited_text().
CitedTableBlock	Blok tabeli	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Zamrożony; jedna tabela.
CitedTableCell	Komórka tabeli	row, col, row_span, col_span, text, bbox, confidence.	Zamrożony; jedna komórka.
NodeType	Wyliczenie	document, section, heading, paragraph, list, table, figure i inne.	Wyliczenie tekstowe dla wartości typów węzłów.
GetAstNodeResponse	Odpowiedź	node: AstNode, meta: AstNodeMeta.	Zwracany przez get_ast_node().
SearchAstNodesResponse	Odpowiedź	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Zwracany przez search_ast_nodes().
ExtractCitedTablesResponse	Odpowiedź	tables: list[CitedTableBlock], table_count, pages_processed.	Zwracany przez extract_cited_tables().
AstDiffEntry	Element różnicy	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Jedna zmiana w różnicy.
AstDiffSummary	Podsumowanie różnic	added_node_count, removed_node_count, changed_node_count.	Łączne liczniki.
GetAstDiffResponse	Odpowiedź	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Zwracany przez get_ast_diff().

Odczytaj kotwicę cytowania z wyodrębnionego bloku tekstu:

from nextpdf import CitedTextBlock


def describe(block: CitedTextBlock) -> str:
    """Render a text block with its page index and confidence."""
    anchor = block.citation
    return f"[page {anchor.page_index}, confidence {anchor.confidence:.2f}] {block.text[:80]}"

Polecenia CLI

Polecenie nextpdf uruchamia ekstrakcję z terminala. Przekaż --base-url i --api-key albo ustaw NEXTPDF_BASE_URL i NEXTPDF_API_KEY w środowisku. Każde polecenie z wyjątkiem version wymaga ustawień połączenia. Argument PDF_PATH o wartości - powoduje odczyt bajtów PDF ze standardowego wejścia.

Symbol	Parametry	Domyślne zachowanie	Zwraca	Wyjątki / tryby niepowodzenia	Uwagi
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Emituje cytowane bloki tekstu w formacie JavaScript Object Notation (JSON).	Zapisuje na standardowe wyjście lub do pliku --output.	Kod wyjścia 1 dla każdego NextPDFError.	--page wybiera jeden indeks strony liczony od zera.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Emituje tabele w formacie JSON.	Zapisuje na standardowe wyjście lub do pliku --output.	Kod wyjścia 1 dla każdego NextPDFError.	--format csv zapisuje jeden blok wartości rozdzielanych przecinkami (CSV) na tabelę.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Emituje pełne semantyczne drzewo AST w formacie JSON.	Zapisuje na standardowe wyjście lub do pliku --output.	Kod wyjścia 1 dla każdego NextPDFError.	Użyj --token-budget, aby ograniczyć rozmiar odpowiedzi.
nextpdf info	PDF_PATH.	Emituje metadane dokumentu: liczbę stron, wersję schematu, skrót źródła, szacowaną liczbę tokenów oraz podsumowanie korzenia.	Zapisuje JSON na standardowe wyjście lub do pliku --output.	Kod wyjścia 1 dla każdego NextPDFError.	Lekkie polecenie inspekcji.
nextpdf version	Brak.	Wypisuje zainstalowaną wersję SDK.	Zapisuje na standardowe wyjście.	Nie oczekuje się żadnych.	Nie łączy się z serwerem; nie wymaga poświadczeń.
python -m nextpdf.mcp	Brak (odczytuje NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Uruchamia serwer Model Context Protocol przez standardowe wejście i wyjście.	Proces serwera działający długotrwale.	RuntimeError, gdy zmienne środowiskowe nie są ustawione.	Wymaga dodatku nextpdf[mcp].

Wyodrębnij tabele jako wartości rozdzielane przecinkami (CSV) z zakresu stron:

nextpdf extract tables invoice.pdf --format csv --page-start 0 --page-end 2 --output tables.csv

Wyjątki

Hierarchia wyjątków znajduje się w nextpdf.models.errors i jest ponownie eksportowana z nextpdf. Przechwytuj najbardziej szczegółową klasę, którą kod potrafi obsłużyć, a dopiero potem przechodź do klasy bazowej. Serwer sygnalizuje niepowodzenie semantyką statusów Hypertext Transfer Protocol (HTTP) zgodną z Request for Comments (RFC) 9110. Każdy wyjątek zawiera źródłowy status_code oraz, jeśli jest dostępny, error_code.

Symbol	Klasa bazowa	status_code	Kiedy jest zgłaszany	Uwagi
NextPDFError	Exception	opcjonalny	Klasa bazowa dla każdego błędu SDK.	Zawiera opcjonalny status_code. Przechwytuj ją na końcu jako rozwiązanie awaryjne.
NextPDFAPIError	NextPDFError	wymagany	Punkt końcowy Connect zwrócił błąd HTTP.	Dodaje error_code.
NextPDFLicenseError	NextPDFAPIError	402	Serwer wymaga licencji wyższego poziomu dla tej funkcji.	error_code to license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Przekroczono limit szybkości lub przydziału.	Zawiera retry_after; uwzględnij tę wartość przed ponowną próbą.
AstNoStructTreeError	NextPDFAPIError	422	Plik PDF jest nieotagowany, a heurystyczne rozwiązanie awaryjne nie jest włączone.	Włącz tryb heurystyczny lub dostarcz otagowany plik PDF.
AstBuildTimeoutError	NextPDFAPIError	504	Budowanie drzewa AST przekroczyło limit czasu na serwerze.	Zmniejsz zakres stron i ponów próbę.

from nextpdf import (
    NextPDF,
    AstBuildTimeoutError,
    NextPDFAPIError,
    NextPDFError,
    QuotaExceededError,
)


def extract_text(client: NextPDF, pdf_bytes: bytes) -> int:
    """Extract cited text, handling the most specific failures first."""
    try:
        blocks = client.ast.extract_cited_text(pdf_bytes)
    except QuotaExceededError as error:
        raise RuntimeError(f"Quota exceeded (retry after {error.retry_after}s)") from error
    except AstBuildTimeoutError as error:
        raise RuntimeError("AST build timed out; reduce the page range") from error
    except NextPDFAPIError as error:
        raise RuntimeError(f"API error {error.status_code}: {error}") from error
    except NextPDFError as error:
        raise RuntimeError(f"SDK error: {error}") from error
    return len(blocks)

Uwagi dla deweloperów

• Synchroniczny klient NextPDF deleguje każde wywołanie do AsyncNextPDF. Możesz go wywołać z notebooka lub z wątku, który już wykonuje pętlę zdarzeń, ponieważ po wykryciu działającej pętli kieruje korutynę do wątku roboczego.
• Preferuj formę asynchronicznego menedżera kontekstu async with AsyncNextPDF(...) as client:, aby pula połączeń była zamykana w sposób deterministyczny. Gdy konstruujesz AsyncNextPDF bezpośrednio, samodzielnie wywołaj close().
• Token uwierzytelniający nigdy nie jest zapisywany w dziennikach ani dołączany do komunikatów o błędach, a weryfikacja Transport Layer Security (TLS) jest domyślnie włączona. Nie umieszczaj poświadczeń w kodzie źródłowym; odczytuj je ze środowiska lub z menedżera sekretów.
• Wszystkie modele to klasy Pydantic v2; kilka modeli odpowiedzi jest zamrożonych (niezmiennych). Traktuj wyodrębnione bloki jako wartości tylko do odczytu.
• Interfejs CLI kończy działanie z kodem statusu 1 dla każdego NextPDFError i wypisuje komunikat na standardowe wyjście błędów. Wykorzystaj ten kod wyjścia w potokach.

Zobacz także

• Przewodnik dla deweloperów SDK dla języka Python — architektura, grupowanie asynchroniczne i obsługa błędów.
• Interfejs CLI dla języka Python — ekstrakcja z terminala i strumieniowanie dużych plików.
• Serwer MCP dla języka Python — udostępnianie narzędzi ekstrakcji agentom sztucznej inteligencji (AI).
• RFC 9110 (HTTP Semantics) oraz RFC 9457 (Problem Details for HTTP APIs) opisują semantykę statusów oraz maszynowo odczytywalne treści błędów zwracane przez punkt końcowy Connect. Tekst autorytatywny znajdziesz w indeksie RFC organizacji IETF.