Referencia de la API de Python

De un vistazo

El SDK de Python de NextPDF expone dos clientes, un único espacio de nombres de métodos ast compartido por ambos, modelos de Pydantic que tipan cada respuesta, la CLI nextpdf y una jerarquía de excepciones de seis clases. Esta página documenta la superficie de referencia de esos símbolos.

Importar la superficie pública desde el paquete de nivel superior:

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

Cada método de extracción recibe los bytes sin procesar del PDF (bytes) como primer argumento posicional y devuelve un modelo de Pydantic tipado. A continuación se indican las opciones exclusivas por palabra clave. Los métodos síncronos NextPDF.ast.* y los métodos asíncronos AsyncNextPDF.ast.* comparten firmas idénticas. Los métodos asíncronos son corrutinas y se invocan con await.

Cliente

El cliente síncrono NextPDF encapsula al cliente asíncrono y ejecuta cada corrutina hasta su finalización. El cliente asíncrono AsyncNextPDF también es un gestor de contexto asíncrono. Se recomienda usar la forma de gestor de contexto para que el transporte subyacente se cierre de forma determinista.

Constructores

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
NextPDF(*, base_url, api_key, api_version='v1')	URL base, clave de API y versión opcional de la API, todas exclusivas por palabra clave.	Construye un cliente síncrono respaldado de forma remota.	NextPDF	ValueError cuando base_url o api_key está vacío.	Los métodos ejecutan trabajo asíncrono de forma síncrona y son seguros en notebooks o con un bucle de eventos en ejecución.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	URL base, clave de API, versión opcional de la API y backend inyectado opcional, todos exclusivos por palabra clave.	Construye un cliente asíncrono respaldado de forma remota cuando no se inyecta ningún backend.	AsyncNextPDF	ValueError cuando base_url o api_key está vacío y no se proporciona ningún backend.	Pasa backend= para inyectar un backend personalizado o local en las pruebas.
AsyncNextPDF.__aenter__()	ninguno.	Entra en el contexto asíncrono y devuelve el cliente.	AsyncNextPDF	ninguna esperada.	Usa async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Argumentos de excepción ignorados.	Llama a close() al salir del contexto.	None	ninguna esperada.	Libera el transporte incluso cuando el cuerpo lanza una excepción.
AsyncNextPDF.close()	ninguno.	Cierra el backend remoto que posee el cliente y libera el grupo de conexiones.	None	ninguna esperada.	Idempotente; los backends inyectados no se cierran.

Mantener la clave de API fuera del código fuente. Leer base_url y api_key desde el entorno (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) o desde un gestor de secretos.

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

Métodos síncronos del AST — NextPDF.ast.*

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
NextPDF.ast.get_document_ast()	pdf_data: bytes; palabras clave page_range_start, page_range_end, token_budget.	Construye el AST semántico completo para cada página.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Reducir el rango de páginas cuando una construcción exceda el tiempo de espera.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; palabras clave page_index, headings_only.	Extrae cada bloque de texto con un ancla de cita.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Establecer headings_only=True para recuperar solo los nodos de encabezado.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; palabra clave page_range (dict con start y end).	Extrae cada tabla con anclas de cita a nivel de celda.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Omitir page_range para analizar el documento completo.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera un nodo por su identificador.	GetAstNodeResponse	NextPDFError cuando no se encuentra el nodo.	node_id tiene el formato ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; palabras clave node_type, page_index, text_query, max_results=100.	Devuelve representaciones superficiales de nodos que coinciden con los filtros.	SearchAstNodesResponse	NextPDFAPIError.	text_query es una coincidencia de subcadena que no distingue mayúsculas de minúsculas.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compara estructuralmente dos documentos.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Informa de los nodos agregados, eliminados y modificados.

Métodos asíncronos del AST — AsyncNextPDF.ast.*

Cada método asíncrono es una corrutina con los mismos parámetros, valores predeterminados, tipo de retorno y modos de fallo que su equivalente síncrono anterior. Invocarlo con await dentro de un entorno de ejecución de asyncio.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; palabras clave page_range_start, page_range_end, token_budget.	Construye el AST semántico completo para cada página.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Aplicar await al resultado.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; palabras clave page_index, headings_only.	Extrae cada bloque de texto con un ancla de cita.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Aplicar await al resultado.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; palabra clave page_range.	Extrae cada tabla con anclas de cita a nivel de celda.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Aplicar await al resultado.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera un nodo por su identificador.	GetAstNodeResponse	NextPDFError cuando no se encuentra el nodo.	Aplicar await al resultado.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; palabras clave node_type, page_index, text_query, max_results=100.	Devuelve representaciones superficiales de nodos que coinciden con los filtros.	SearchAstNodesResponse	NextPDFAPIError.	Aplicar await al resultado.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compara estructuralmente dos documentos.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Aplicar await al resultado.

Usar el cliente asíncrono como gestor de contexto y agrupar dos extracciones de forma concurrente:

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

Modelos

Cada respuesta es un modelo de Pydantic. Importar las clases de modelo desde nextpdf o desde nextpdf.models.ast.

Símbolo	Tipo	Campos clave	Notas
AstDocument	Raíz del documento	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (propiedad).	Devuelto por get_document_ast(). Acepta los alias schemaVersion, sourceHash, pageCount.
AstNode	Nodo del árbol	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Nodo recursivo que contiene el árbol del documento.
AstNodeMeta	Metadatos de la respuesta	etag, pages_processed.	Inmutable; se adjunta a las respuestas de nodo y de búsqueda.
AstNodeShallow	Resultado de búsqueda	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Inmutable; sin hijos profundos.
BoundingBox	Objeto de valor	x, y, width, height (cada uno 0.0–1.0).	Coordenadas de página normalizadas.
CitationAnchor	Objeto de valor	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Registro de procedencia en cada bloque.
CitedTextBlock	Bloque de texto	text, citation: CitationAnchor, node_type, chunk_index, depth.	Cada elemento de la lista de extract_cited_text().
CitedTableBlock	Bloque de tabla	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Inmutable; una sola tabla.
CitedTableCell	Celda de tabla	row, col, row_span, col_span, text, bbox, confidence.	Inmutable; una sola celda.
NodeType	Enumeración	document, section, heading, paragraph, list, table, figure, entre otros.	Enumeración de cadenas con los valores de tipo de nodo.
GetAstNodeResponse	Respuesta	node: AstNode, meta: AstNodeMeta.	Devuelto por get_ast_node().
SearchAstNodesResponse	Respuesta	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Devuelto por search_ast_nodes().
ExtractCitedTablesResponse	Respuesta	tables: list[CitedTableBlock], table_count, pages_processed.	Devuelto por extract_cited_tables().
AstDiffEntry	Elemento de diferencia	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Cambio individual dentro de una diferencia.
AstDiffSummary	Totales de la diferencia	added_node_count, removed_node_count, changed_node_count.	Recuentos agregados.
GetAstDiffResponse	Respuesta	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Devuelto por get_ast_diff().

Leer un ancla de cita de un bloque de texto extraído:

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

Comandos de la CLI

El comando nextpdf ejecuta la extracción desde la terminal. Pasar --base-url y --api-key, o definir NEXTPDF_BASE_URL y NEXTPDF_API_KEY en el entorno. Todos los comandos excepto version requieren configuración de conexión. Un PDF_PATH con valor - lee los bytes del PDF desde la entrada estándar.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Emite los bloques de texto citados como JSON.	Escribe en la salida estándar o en el archivo de --output.	Código de salida 1 ante cualquier NextPDFError.	--page selecciona un índice de página basado en cero.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Emite las tablas como JSON.	Escribe en la salida estándar o en el archivo de --output.	Código de salida 1 ante cualquier NextPDFError.	--format csv escribe un bloque CSV por cada tabla.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Emite el AST semántico completo como JSON.	Escribe en la salida estándar o en el archivo de --output.	Código de salida 1 ante cualquier NextPDFError.	Usa --token-budget para acotar el tamaño de la respuesta.
nextpdf info	PDF_PATH.	Emite los metadatos del documento: recuento de páginas, versión del esquema, hash de origen, tokens estimados y resumen de la raíz.	Escribe JSON en la salida estándar o en el archivo de --output.	Código de salida 1 ante cualquier NextPDFError.	Un comando de inspección ligero.
nextpdf version	ninguno.	Imprime la versión instalada del SDK.	Escribe en la salida estándar.	ninguna esperada.	No contacta con ningún servidor; no necesita credenciales.
python -m nextpdf.mcp	ninguna (lee NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Ejecuta el servidor Model Context Protocol sobre la entrada/salida estándar (input/output).	Proceso de servidor de larga duración.	RuntimeError cuando las variables de entorno no están definidas.	Requiere el extra nextpdf[mcp].

Extraer tablas como valores separados por comas (CSV) de un rango de páginas:

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

Excepciones

La jerarquía de excepciones reside en nextpdf.models.errors y se reexporta desde nextpdf. Capturar la clase más específica sobre la que el código pueda actuar y, después, recurrir a la clase base. El servidor señala el fallo con una semántica de estado HTTP alineada con RFC 9110. Cada excepción transporta el status_code de origen y, cuando corresponde, un error_code.

Símbolo	Clase base	status_code	Cuándo se lanza	Notas
NextPDFError	Exception	opcional	Base de todos los errores del SDK.	Transporta un status_code opcional. Capturarla al final como mecanismo de reserva.
NextPDFAPIError	NextPDFError	obligatorio	El endpoint de Connect devolvió un error HTTP.	Agrega error_code.
NextPDFLicenseError	NextPDFAPIError	402	La función requiere una licencia de nivel superior en el servidor.	error_code es license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Se superó un límite de frecuencia o una cuota.	Transporta retry_after; respetarlo antes de reintentar.
AstNoStructTreeError	NextPDFAPIError	422	El PDF no está etiquetado y la alternativa heurística no está habilitada.	Habilitar el modo heurístico o proporcionar un PDF etiquetado.
AstBuildTimeoutError	NextPDFAPIError	504	La construcción del AST excedió el tiempo de espera en el servidor.	Reducir el rango de páginas y volver a intentarlo.

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)

Notas de desarrollo

• El cliente síncrono NextPDF delega cada llamada a AsyncNextPDF. Puede llamarse de forma segura desde un notebook o desde un hilo que ya ejecuta un bucle de eventos, porque la corrutina se despacha a un hilo de trabajo cuando se detecta un bucle en ejecución.
• Preferir la forma de gestor de contexto asíncrono async with AsyncNextPDF(...) as client: para que el grupo de conexiones se cierre de forma determinista. Cuando se construya AsyncNextPDF directamente, llamar a close() de forma explícita.
• El token de portador nunca se registra ni se incluye en los mensajes de error, y la verificación de la seguridad de la capa de transporte (TLS) está habilitada de forma predeterminada. No incrustar credenciales en el código fuente; leerlas desde el entorno o desde un gestor de secretos.
• Todos los modelos son clases de Pydantic v2; varios modelos de respuesta son inmutables (frozen). Tratar los bloques extraídos como valores de solo lectura.
• La CLI termina con el código de estado 1 ante cualquier NextPDFError e imprime el mensaje en la salida de error estándar. Integrar ese código de salida en tus pipelines.

Consulta también

• Guía para desarrolladores del SDK de Python — arquitectura, agrupación asíncrona y gestión de fallos.
• CLI de Python — extracción en la terminal y streaming para archivos grandes.
• Servidor MCP de Python — expone las herramientas de extracción a los agentes de IA.
• RFC 9110 (HTTP Semantics) y RFC 9457 (Problem Details for HTTP APIs) describen la semántica de estado y los cuerpos de error legibles por máquina que devuelve el endpoint de Connect. Consulta el índice de RFC de la IETF para conocer el texto autoritativo.