Python API 레퍼런스

한눈에 보기

NextPDF Python 소프트웨어 개발 키트(SDK)는 두 개의 클라이언트, 두 클라이언트가 공유하는 단일 ast 메서드 네임스페이스, 모든 응답에 타입을 부여하는 Pydantic 모델 모음, nextpdf 명령줄 인터페이스(CLI), 그리고 6 개 클래스로 구성된 예외 계층을 제공합니다. 이 페이지는 각 심벌의 공개 API를 정리한 레퍼런스입니다.

공개 API는 최상위 패키지에서 가져옵니다.

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	ValueError는 base_url 또는 api_key가 비어 있을 때 발생합니다.	메서드는 비동기 작업을 동기적으로 실행하며, 노트북이나 실행 중인 이벤트 루프 안에서도 안전합니다.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	키워드 전용 기본 URL, API 키, 선택적 API 버전, 선택적으로 주입되는 백엔드입니다.	백엔드가 주입되지 않은 경우 원격 백엔드 기반의 비동기 클라이언트를 생성합니다.	AsyncNextPDF	ValueError는 base_url 또는 api_key가 비어 있고 backend가 제공되지 않을 때 발생합니다.	테스트에서 사용자 지정 백엔드나 로컬 백엔드를 주입하려면 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.	식별자를 사용해 단일 노드를 가져옵니다.	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.	두 문서를 구조적으로 비교합니다.	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.	식별자를 사용해 단일 노드를 가져옵니다.	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.	두 문서를 구조적으로 비교합니다.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await로 결과를 대기합니다.

비동기 클라이언트를 컨텍스트 관리자로 사용해 두 추출 작업을 동시에 일괄 처리합니다.

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.	고정(frozen)되어 있습니다. 노드 및 검색 응답에 첨부됩니다.
AstNodeShallow	검색 결과 항목	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	고정(frozen)되어 있습니다. 깊은 자식이 없습니다.
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.	고정(frozen)되어 있습니다. 단일 표입니다.
CitedTableCell	표 셀	row, col, row_span, col_span, text, bbox, confidence.	고정(frozen)되어 있습니다. 단일 셀입니다.
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.	차이를 이루는 단일 변경 항목입니다.
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부터 시작하는 페이지 인덱스 하나를 선택합니다.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	표를 JSON으로 출력합니다.	표준 출력 또는 --output 파일에 씁니다.	모든 NextPDFError에서 종료 코드 1로 종료합니다.	--format csv는 표마다 CSV 블록 하나를 씁니다.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	전체 시맨틱 AST를 JSON으로 출력합니다.	표준 출력 또는 --output 파일에 씁니다.	모든 NextPDFError에서 종료 코드 1로 종료합니다.	응답 크기를 제한하려면 --token-budget을 사용합니다.
nextpdf info	PDF_PATH.	문서 메타데이터를 출력합니다: 페이지 수, 스키마 버전, 소스 해시, 추정 토큰 수, 루트 요약입니다.	표준 출력 또는 --output 파일에 JSON을 씁니다.	모든 NextPDFError에서 종료 코드 1로 종료합니다.	가벼운 검사 명령입니다.
nextpdf version	없음.	설치된 SDK 버전을 출력합니다.	표준 출력에 씁니다.	예상되는 예외 없음.	서버에 연결하지 않으며, 자격 증명이 필요하지 않습니다.
python -m nextpdf.mcp	없음(NEXTPDF_BASE_URL, NEXTPDF_API_KEY를 읽습니다).	표준 input/output을 통해 Model Context Protocol 서버를 실행합니다.	장기 실행 서버 프로세스입니다.	RuntimeError. 환경 변수가 설정되지 않을 때 발생합니다.	추가 항목 nextpdf[mcp]가 필요합니다.

페이지 범위의 표를 쉼표로 구분된 값(CSV)으로 추출합니다.

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

예외

예외 계층은 nextpdf.models.errors에 있으며 nextpdf에서 다시 내보내집니다. 코드가 처리할 수 있는 가장 구체적인 클래스를 먼저 catch하고, 그다음 기본 클래스로 폴백하십시오. 서버는 RFC 9110에 맞춘 HTTP 상태 의미 체계로 실패를 알립니다. 각 예외에는 원본 status_code가 담기며, 해당하는 경우 error_code도 담깁니다.

심벌	기본 클래스	status_code	발생 조건	참고
NextPDFError	Exception	선택 사항	모든 SDK 오류의 기본 클래스입니다.	선택적 status_code를 담습니다. 폴백으로 마지막에 catch하십시오.
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()를 직접 호출하십시오.
• 베어러 토큰은 로깅되거나 오류 메시지에 포함되지 않으며, 전송 계층 보안(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 색인을 참조하십시오.