Python SDK API リファレンス

概要

NextPDF Python Software Development Kit（SDK）は、2 つのクライアント、両者が共有する単一の ast メソッド名前空間、すべてのレスポンスを型付けする Pydantic モデル群、nextpdf コマンドラインインターフェイス（CLI）、および 6 クラスから成る例外階層を公開します。このページは、それらの各シンボルのリファレンスです。

パブリックな機能はトップレベルのパッケージからインポートします。

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

すべての抽出メソッドは、最初の位置引数として生の PDF バイト列（bytes）を受け取り、型付きの Pydantic モデルを返します。後続のオプションはキーワード専用です。同期版の NextPDF.ast.* メソッドと非同期版の AsyncNextPDF.ast.* メソッドは、同一のシグネチャを共有します。非同期メソッドはコルーチンであり、呼び出しには await が必要です。

クライアント

同期版の NextPDF クライアントは非同期クライアントをラップし、各コルーチンを完了まで実行します。非同期版の AsyncNextPDF クライアントは、非同期コンテキストマネージャーとしても使用できます。コンテキストマネージャー形式を推奨します。内部トランスポートを確実にクローズできるためです。

コンストラクター

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗の条件	備考
NextPDF(*, base_url, api_key, api_version='v1')	キーワード専用のベース URL、API キー、および任意の API バージョン。	リモートバックエンドを使う同期クライアントを構築。	NextPDF	base_url または api_key が空の場合に ValueError。	メソッドは非同期処理を同期的に実行するため、ノートブック内や実行中のイベントループ内でも安全です。
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	キーワード専用のベース URL、API キー、任意の API バージョン、および任意で注入するバックエンド。	バックエンドが注入されていない場合、リモートバックエンドを使う非同期クライアントを構築。	AsyncNextPDF	base_url または api_key が空で、かつ backend が指定されていない場合に ValueError。	引数 backend= を渡すと、テストでカスタムバックエンドまたはローカルバックエンドを注入できます。
AsyncNextPDF.__aenter__()	なし。	非同期コンテキストに入り、クライアントを返却。	AsyncNextPDF	想定されません。	形式 async with AsyncNextPDF(...) as client: を使用。
AsyncNextPDF.__aexit__(*_)	抑制対象の例外引数。	コンテキスト終了時にメソッド close() を呼び出し。	None	想定されません。	本体で例外が発生した場合でも、トランスポートを解放。
AsyncNextPDF.close()	なし。	所有しているリモートバックエンドをクローズし、コネクションプールを解放。	None	想定されません。	べき等です。注入されたバックエンドはクローズされません。

API キーはソースコードに記述しないでください。base_url と api_key は、環境変数（NEXTPDF_BASE_URL、NEXTPDF_API_KEY）またはシークレットマネージャーから読み込みます。

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

同期 AST メソッド — NextPDF.ast.*

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗の条件	備考
NextPDF.ast.get_document_ast()	pdf_data: bytes。キーワード page_range_start、page_range_end、token_budget。	全ページを対象に完全なセマンティック AST を構築。	AstDocument	AstNoStructTreeError、AstBuildTimeoutError、NextPDFLicenseError、QuotaExceededError。	ビルドがタイムアウトする場合は、ページ範囲を狭めてください。
NextPDF.ast.extract_cited_text()	pdf_data: bytes。キーワード page_index、headings_only。	引用アンカーを持つすべてのテキストブロックを抽出。	list[CitedTextBlock]	NextPDFAPIError、QuotaExceededError。	引数 headings_only=True を指定すると、見出しノードのみを取得します。
NextPDF.ast.extract_cited_tables()	pdf_data: bytes。キーワード page_range（dict のフィールド start と end）。	セル単位の引用アンカーを持つすべてのテーブルを抽出。	ExtractCitedTablesResponse	NextPDFAPIError、QuotaExceededError。	引数 page_range を省略すると、ドキュメント全体をスキャンします。
NextPDF.ast.get_ast_node()	pdf_data: bytes、node_id: str。	識別子で 1 つのノードを取得。	GetAstNodeResponse	NextPDFError（ノードが見つからない場合）。	node_id の形式は ast:{hash6}:{pageIdx}:{seq}。
NextPDF.ast.search_ast_nodes()	pdf_data: bytes。キーワード node_type、page_index、text_query、max_results=100。	フィルターに一致するシャローノードを返却。	SearchAstNodesResponse	NextPDFAPIError。	text_query は、大文字と小文字を区別しない部分一致です。
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes、modified_pdf_data: bytes。	2 つのドキュメントを構造的に比較。	GetAstDiffResponse	NextPDFAPIError、QuotaExceededError。	追加、削除、および変更されたノードを報告します。

非同期 AST メソッド — AsyncNextPDF.ast.*

各非同期メソッドはコルーチンであり、上記の同期版と同じパラメーター、既定値、戻り値の型、および失敗モードを持ちます。asyncio ランタイム内で await を付けて呼び出します。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗の条件	備考
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes。キーワード page_range_start、page_range_end、token_budget。	全ページを対象に完全なセマンティック AST を構築。	AstDocument	AstNoStructTreeError、AstBuildTimeoutError、NextPDFLicenseError、QuotaExceededError。	await で結果を待機します。
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes。キーワード page_index、headings_only。	引用アンカーを持つすべてのテキストブロックを抽出。	list[CitedTextBlock]	NextPDFAPIError、QuotaExceededError。	await で結果を待機します。
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes。キーワード page_range。	セル単位の引用アンカーを持つすべてのテーブルを抽出。	ExtractCitedTablesResponse	NextPDFAPIError、QuotaExceededError。	await で結果を待機します。
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes、node_id: str。	識別子で 1 つのノードを取得。	GetAstNodeResponse	NextPDFError（ノードが見つからない場合）。	await で結果を待機します。
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes。キーワード node_type、page_index、text_query、max_results=100。	フィルターに一致するシャローノードを返却。	SearchAstNodesResponse	NextPDFAPIError。	await で結果を待機します。
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes、modified_pdf_data: bytes。	2 つのドキュメントを構造的に比較。	GetAstDiffResponse	NextPDFAPIError、QuotaExceededError。	await で結果を待機します。

非同期クライアントをコンテキストマネージャーとして使い、2 つの抽出を同時にバッチ処理します。

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}")

モデル

すべてのレスポンスは Pydantic モデルです。モデルクラスは nextpdf または nextpdf.models.ast からインポートします。

シンボル	種別	主なフィールド	備考
AstDocument	ドキュメントルート	schema_version、source_hash、page_count、root: AstNode、estimated_tokens（プロパティ）。	メソッド get_document_ast() の戻り値。schemaVersion、sourceHash、pageCount のエイリアスを受け付けます。
AstNode	ツリーノード	id、type: NodeType、page_index、bbox、text_content、attributes、children: list[AstNode]、pdf_object_number、mcid。	ドキュメントツリーを保持する再帰的なノード。
AstNodeMeta	レスポンスメタデータ	etag、pages_processed。	イミュータブル。ノードレスポンスと検索レスポンスに付与。
AstNodeShallow	検索ヒット	id、type: NodeType、page_index、bbox、text_content、attributes、children_count。	イミュータブル。深い子要素なし。
BoundingBox	値オブジェクト	x、y、width、height（各 0.0–1.0）。	正規化されたページ座標。
CitationAnchor	値オブジェクト	node_id、page_index、bbox: BoundingBox、confidence、content_hash。	各ブロックの来歴情報。
CitedTextBlock	テキストブロック	text、citation: CitationAnchor、node_type、chunk_index、depth。	メソッド extract_cited_text() が返すリストの各項目。
CitedTableBlock	テーブルブロック	table_node_id、page_index、citation_anchor、row_count、col_count、rows。	イミュータブル。1 つのテーブル。
CitedTableCell	テーブルセル	row、col、row_span、col_span、text、bbox、confidence。	イミュータブル。1 つのセル。
NodeType	列挙型	document、section、heading、paragraph、list、table、figure、その他。	ノード型の値を表す文字列列挙型。
GetAstNodeResponse	レスポンス	node: AstNode、meta: AstNodeMeta。	メソッド get_ast_node() の戻り値。
SearchAstNodesResponse	レスポンス	nodes: list[AstNodeShallow]、total_matches、truncated、meta。	メソッド search_ast_nodes() の戻り値。
ExtractCitedTablesResponse	レスポンス	tables: list[CitedTableBlock]、table_count、pages_processed。	メソッド extract_cited_tables() の戻り値。
AstDiffEntry	差分項目	type（added/removed/changed）、node_id、node_type、page_index、text_preview。	差分における 1 つの変更。
AstDiffSummary	差分の合計	added_node_count、removed_node_count、changed_node_count。	集計カウント。
GetAstDiffResponse	レスポンス	original_page_count、modified_page_count、summary: AstDiffSummary、diff: list[AstDiffEntry]、pages_processed。	メソッド get_ast_diff() の戻り値。

抽出したテキストブロックから引用アンカーを参照します。

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]}"

CLI コマンド

nextpdf コマンドは、ターミナルから抽出を実行します。接続設定には --base-url と --api-key を指定するか、NEXTPDF_BASE_URL と NEXTPDF_API_KEY を環境変数に設定します。version を除くすべてのコマンドは、接続設定を必要とします。PDF_PATH が - の場合、PDF バイト列を標準入力から読み込みます。

シンボル	パラメーター	既定の動作	戻り値	スローまたは失敗の条件	備考
nextpdf extract text	PDF_PATH、--format {json,markdown,plain}、--page、--headings-only。	引用付きテキストブロックを JSON として出力。	標準出力または --output ファイルに書き出し。	いずれかの NextPDFError が発生すると終了コード 1 で終了。	--page は、0 始まりのページインデックスを 1 つ選択します。
nextpdf extract tables	PDF_PATH、--format {json,csv}、--page-start、--page-end。	テーブルを JSON として出力。	標準出力または --output ファイルに書き出し。	いずれかの NextPDFError が発生すると終了コード 1 で終了。	--format csv は、テーブルごとに 1 つの CSV ブロックを書き出します。
nextpdf ast	PDF_PATH、--page-start、--page-end、--token-budget。	完全なセマンティック AST を JSON として出力。	標準出力または --output ファイルに書き出し。	いずれかの NextPDFError が発生すると終了コード 1 で終了。	引数 --token-budget を使ってレスポンスのサイズを制限します。
nextpdf info	PDF_PATH。	ドキュメントのメタデータ（ページ数、スキーマバージョン、ソースハッシュ、推定トークン数、ルートの概要）を出力。	JSON を標準出力または --output ファイルに書き出し。	いずれかの NextPDFError が発生すると終了コード 1 で終了。	軽量な検査用コマンド。
nextpdf version	なし。	インストールされている SDK のバージョンを出力。	標準出力に書き出し。	想定されません。	サーバーに接続しません。認証情報は不要です。
python -m nextpdf.mcp	なし（NEXTPDF_BASE_URL、NEXTPDF_API_KEY）。	Model Context Protocol サーバーを標準入出力（input/output）上で実行。	長時間稼働するサーバープロセス。	RuntimeError（環境変数が設定されていない場合）。	拡張機能 nextpdf[mcp] が必要です。

ページ範囲からテーブルをカンマ区切り値（CSV）として抽出します。

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

例外

例外階層は nextpdf.models.errors にあり、nextpdf から再エクスポートされます。コードが処理できる最も具体的なクラスを先にキャッチし、その後に基底クラスへフォールバックしてください。サーバーは、RFC 9110 に準拠した HTTP ステータスのセマンティクスで失敗を通知します。各例外は、発生元の status_code と、該当する場合は error_code を保持します。

シンボル	基底クラス	status_code	スローされる条件	備考
NextPDFError	Exception	任意	すべての SDK エラーの基底クラス。	任意の status_code を保持。フォールバックとして最後にキャッチ。
NextPDFAPIError	NextPDFError	必須	Connect エンドポイントから HTTP エラーが返された場合。	属性 error_code を追加。
NextPDFLicenseError	NextPDFAPIError	402	この機能には、サーバー上でより上位のライセンスが必要です。	error_code は license/tier-required。
QuotaExceededError	NextPDFAPIError	429	レート制限またはクォータを超過しました。	属性 retry_after を保持。再試行前にこの値を尊重してください。
AstNoStructTreeError	NextPDFAPIError	422	PDF がタグ付けされておらず、ヒューリスティックフォールバックが有効になっていません。	ヒューリスティックモードを有効にするか、タグ付き PDF を指定してください。
AstBuildTimeoutError	NextPDFAPIError	504	サーバー上で AST のビルドがタイムアウトしました。	ページ範囲を狭めて再試行してください。

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)

開発上の注意

• 同期版の NextPDF クライアントは、すべての呼び出しを AsyncNextPDF に委譲します。ノートブックや、すでにイベントループを実行しているスレッドから呼び出しても安全です。実行中のループが検出されると、コルーチンはワーカースレッドにディスパッチされます。
• 非同期コンテキストマネージャー形式 async with AsyncNextPDF(...) as client: を推奨します。これにより、コネクションプールが確実にクローズされます。 AsyncNextPDF を直接構築する場合は、close() を自分で呼び出してください。
• ベアラートークンがログに記録されたりエラーメッセージに含まれたりすることはなく、Transport Layer Security（TLS）の検証は既定で有効です。認証情報をソースに埋め込まないでください。環境変数またはシークレットマネージャーから読み込みます。
• すべてのモデルは Pydantic v2 クラスです。いくつかのレスポンスモデルはイミュータブル（変更不可）です。抽出されたブロックは読み取り専用の値として扱ってください。
• CLI は、いずれかの NextPDFError が発生するとステータスコード 1 で終了し、メッセージを標準エラーに出力します。パイプラインではその終了コードを利用してください。

関連項目

• Python SDK 開発者ガイド — アーキテクチャ、非同期バッチ処理、および失敗時の処理。
• Python CLI — ターミナルでの抽出と、大きなファイル向けのストリーミング。
• Python MCP サーバー — 抽出ツールを AI エージェントに公開します。
• RFC 9110（HTTP Semantics）と RFC 9457（Problem Details for HTTP APIs）は、Connect エンドポイントが返すステータスのセマンティクスと、機械可読なエラー本文を規定しています。正式な本文については、IETF RFC インデックスを参照してください。