跳到內容
NextPDF

NextPDF Connect API 參考

概觀

標題為「概觀」的區段

本頁是 NextPDF Connect 伺服器（nextpdf/server）的符號層級參考文件。它逐一列出每個工具註冊的工具名稱與實作類別，並記載 gRPC 服務 NextPDFConnect、其遠端程序呼叫（Remote Procedure Call，RPC）方法，以及請求與回應訊息。它也說明各傳輸（transport）共用的驗證、錯誤與速率限制約定。

伺服器透過三種傳輸對外提供同一份工具登錄表（tool registry）：以標準輸入與輸出承載的 Model Context Protocol（MCP）、Representational State Transfer（REST）應用程式介面（API），以及 gRPC。每個傳輸的線路細節各自獨立成頁；請參閱 MCP 傳輸、REST 傳輸，以及 gRPC 傳輸。本頁則是這些傳輸所承載符號的型錄。

下表中的工具名稱、類別與風險層級，皆讀取自 src/Tools/ 中的工具實作。某次部署實際對外提供的工具數量屬於執行期屬性；請參閱 工具型錄。層級的解析（resolve）方式說明於 啟動與探索。

各傳輸的可用性

標題為「各傳輸的可用性」的區段

只要部署啟用了某個傳輸，工具就能透過該傳輸存取。這些傳輸是彼此獨立的行程（process）；啟動其中一個不會連帶啟動其他傳輸。

傳輸進入點線路格式驗證
MCPbin/nextpdf-mcp以 stdio 承載的 JavaScript Object Notation Remote Procedure Call（JSON-RPC）2.0作業系統行程邊界（不需 API key）
RESTbin/nextpdf-serverHTTP、OpenAPI 3.1在 Authorization 標頭中的 bearer API key
gRPCbin/nextpdf-grpcProtocol Buffers，套件 nextpdf.connect.v1位於 authorization 呼叫中繼資料中的 bearer token

在 MCP 上，呼叫工具時會將註冊的工具名稱搭配 tools/call。在 REST 與 gRPC 上，同一套引擎能力則透過繪製、操作與能力介面取得；請參閱 REST 傳輸 的路由表，以及 gRPC 傳輸 的 RPC 表。

驗證與風險層級

標題為「驗證與風險層級」的區段

API key 驗證

標題為「API key 驗證」的區段

REST 與 gRPC 傳輸要求每個請求都附帶 bearer API key，唯一例外是不需驗證的健康檢查探測（health probe）。key 的形式為 npk_live_{kid}_{secret}：其中 kid 是用於記錄查找的八字元識別碼，秘密值（secret）則承載熵（entropy）。伺服器只保存 key 的 SHA-256 摘要，並以常數時間比對（constant-time comparison）核對提交的 token；因此即使 key 錯誤，也不會透過時序洩漏任何資訊。REST 從 Authorization: Bearer … 標頭讀取 token；gRPC 則從 authorization 呼叫中繼資料讀取同一個 token。MCP stdio 傳輸沒有 API key，因為它是由啟動它的用戶端所信任的本機子行程（subprocess）。完整的驗證模型記載於 安全與維運。

四個風險層級

標題為「四個風險層級」的區段

每個工具都會宣告四個有序風險等級之一；這些等級由 src/Config/RiskLevel.php 中的 RiskLevel enum 定義。

層級列舉成員（enum case）值效果
Safe（安全）RiskLevel::Safe0唯讀，無副作用。自動執行。
Caution（謹慎）RiskLevel::Caution1建立或修改記憶體內狀態。自動執行，並寫入稽核紀錄。
Review（審查）RiskLevel::Review2產生可能遭濫用的輸出。自動執行，並寫入稽核紀錄。
ApprovalRequired（需核准）RiskLevel::ApprovalRequired3具破壞性、涉及法律或攸關隱私。需經人工確認。

工具的實際風險層級只會來自兩個來源：工具本身的 riskLevel() 宣告，以及一項可選的維運者組態覆寫——此覆寫只能調高風險，絕不能調降 ApprovalRequired 工具的風險。請參閱 HITL 風險層級 與 組態。

核准 token 如何流轉

標題為「核准 token 如何流轉」的區段

當一個 ApprovalRequired 工具在未提供有效 token 的情況下被呼叫時，ConfirmationGate（src/Mcp/ConfirmationGate.php）會回傳單次使用的挑戰 token，而不會執行該工具。AI Agent（代理）會把挑戰碼轉達給人類，再以核發的 token 透過 _confirmation_token 引數重新呼叫同一個工具。token 會綁定工具名稱、一組隨機 nonce，以及 300 秒的存活時間（time-to-live，TTL）。它並不綁定引數，也不是身分驗證憑證。在 REST 上，bearer API key 仍負責驗證請求，而同一道閘門（gate）會在受管控操作之前，於共用的工具執行器（tool executor）中執行。在 gRPC 上，同一道閘門會在派發操作之前執行。挑戰碼與 token 機制在各傳輸間完全一致。

工具與端點（endpoint）

標題為「工具與端點（endpoint）」的區段

下表依每個工具註冊的工具名稱（Symbol 欄）逐一列出工具，並標明其實作類別。工具依層級與類別分組。所有 AST 與 mutation 類別都位於 src/Tools/Ast 與 src/Tools/Ast/Mutation 下；擷取類別位於 src/Tools/Extraction 下；其餘類別則位於 src/Tools/Core 下。

核心文件工具

標題為「核心文件工具」的區段
符號（Symbol）參數預設行為回傳擲出或失敗條件備註
create_pdfpage_size（預設 A4）、orientation（portrait/landscape）、title、author；皆非必填。在記憶體中建立一份文件與一個頁面；若有提供中繼資料（metadata）則一併設定。帶有 document_id、page_count、page_size、orientation 的 JSON。失敗時回傳含引擎訊息的錯誤結果。類別 CreatePdfTool。風險 RiskLevel::Caution。層級 core。回傳的 document_id 會供應給後續每項操作。
add_pagedocument_id（必填），頁面尺寸與方向為選填。在文件末尾附加一個頁面。帶有新頁數的 JSON。當 document_id 不明時回傳錯誤結果。類別 AddPageTool。風險 RiskLevel::Caution。層級 core。
add_textdocument_id（必填）、text（必填），位置與樣式為選填。在文件中加入文字。JSON 文件狀態摘要。當 document_id 不明時回傳錯誤結果。類別 AddTextTool。風險 RiskLevel::Caution。層級 core。
add_imagedocument_id（必填）、source（必填：檔案路徑或 base64），擺放位置為選填。從路徑或 base64 資料加入一張影像。JSON 文件狀態摘要。來源無法讀取或 document_id 不明時回傳錯誤結果。類別 AddImageTool。風險 RiskLevel::Caution。層級 core。
add_tabledocument_id（必填）、html（必填）。把一段 HTML 表格 markup（標記語言）繪製進文件。JSON 文件狀態摘要。標記語言無效或 document_id 不明時回傳錯誤結果。類別 AddTableTool。風險 RiskLevel::Caution。層級 core。
set_fontdocument_id（必填）、family（必填），大小與樣式為選填。為後續文字操作設定字型。回傳目前作用中字型的 JSON 確認資訊。字型不明或 document_id 不明時回傳錯誤結果。類別 SetFontTool。風險 RiskLevel::Caution。層級 core。
output_pdfdocument_id（必填）、file_path（選填）、destroy（預設 true）。完成文件；若有提供 file_path 則寫入該路徑，若省略則回傳 base64；預設會銷毀文件。帶有 file_path 與 file_size 的 JSON，或帶有 base64 與 file_size 的 JSON。當 document_id 不明時回傳錯誤結果；若嘗試寫入基準目錄之外，則發生路徑封閉性（path containment）失敗。類別 OutputPdfTool。風險 RiskLevel::ApprovalRequired。層級 core。寫入檔案會經過確認閘門；base64 模式則不會。
preview_layoutdocument_id（必填）。回傳版面配置摘要，但不繪製最終的 PDF。JSON 版面配置摘要。當 document_id 不明時回傳錯誤結果。類別 PreviewLayoutTool。風險 RiskLevel::Safe。層級 core。
parse_pdfdocument_id（必填）。檢視結構性中繼資料：頁數、字型、影像、加密狀態，以及 Info Dictionary。JSON 結構性中繼資料。文件格式異常時回傳錯誤結果。類別 ParsePdfTool。風險 RiskLevel::Safe。層級 core。只有當 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED 為 true 或 1 時才會註冊。

核心診斷工具

標題為「核心診斷工具」的區段
符號（Symbol）參數預設行為回傳擲出或失敗條件備註
diagnostic.doctor無。執行健康檢查，並回傳結構化的環境診斷資訊。JSON 環境報告。內部檢查失敗時回傳錯誤結果。類別 DiagnosticDoctorTool。風險 RiskLevel::Safe。層級 core。不需文件，也不需確認。
diagnostic.capabilities無。列出各項能力（capability）及其層級與狀態資訊。JSON 能力清單。內部失敗時回傳錯誤結果。類別 DiagnosticCapabilitiesTool。風險 RiskLevel::Safe。層級 core。
diagnostic.inspectdocument_id（必填）。檢視一份 PDF，並回傳結構性中繼資料。JSON 結構性中繼資料。當 document_id 不明時回傳錯誤結果。類別 DiagnosticInspectTool。風險 RiskLevel::Safe。層級 core。
diagnostic.verifydocument_id（必填），PDF/A 或 PDF/UA 描述檔為選填。驗證結構完整性；可選擇透過衍生一個 VeraPDF 子行程來驗證 PDF/A 或 PDF/UA。JSON 驗證報告。子行程失敗、逾時或輸入過大時回傳錯誤結果。類別 DiagnosticVerifyTool。風險 RiskLevel::Caution。層級 core。輸入上限為 50 mebibyte（MiB）。

核心條碼工具

標題為「核心條碼工具」的區段
符號（Symbol）參數預設行為回傳擲出或失敗條件備註
generate_barcodepayload（必填）、format（例如 QR Code、DataMatrix）。為 payload 產生二維條碼的模組矩陣（module matrix）。JSON 模組矩陣。當 format 不受支援或 payload 無效時回傳錯誤結果。類別 BarcodeTool。風險 RiskLevel::Caution。層級 core。工具 BarcodeTool 只有當核心 barcode 編碼器登錄表存在於已安裝的 nextpdf/core 中時才會註冊；其註冊的工具名稱為 generate_barcode。

Enterprise 隱私工具

標題為「Enterprise 隱私工具」的區段

這些工具包裝 Enterprise 隱私類別；只有當這些類別可被自動載入（autoloadable）時，才會在 Enterprise 層級註冊。它們作用於純文字內容。

符號（Symbol）參數預設行為回傳擲出或失敗條件備註
redact_pdfcontent（必填），偵測選項為選填。使用 Enterprise 遮蔽引擎，對純文字內容中的個人可識別資訊（personally identifiable information，PII）進行破壞性遮蔽。帶有遮蔽後內容及一個 SHA-256 雜湊的 JSON。當 Enterprise 類別缺席或偵測失敗時回傳錯誤結果。類別 RedactPdfTool。風險 RiskLevel::Review。層級 enterprise。
deidentify_pdfcontent（必填）、strategy（redact 或 suppress）。使用 Enterprise 去識別化元件，對純文字內容套用系統化的去識別化策略。帶有去識別化後內容的 JSON。當 Enterprise 類別缺席時回傳錯誤結果。類別 DeIdentifyPdfTool。風險 RiskLevel::Review。層級 enterprise。
zone_redact_pdfcontent（必填）、zones（頁面，外加正規化矩形清單）。使用 Enterprise 遮蔽引擎，套用以座標為基準的區域遮蔽。帶有遮蔽後內容的 JSON。當區域無效或 Enterprise 類別缺席時回傳錯誤結果。類別 ZoneRedactionTool。風險 RiskLevel::Review。層級 enterprise。

抽象語法樹（abstract syntax tree，AST）讀取工具

標題為「抽象語法樹（abstract syntax tree，AST）讀取工具」的區段

這些工具隨伺服器一同提供，在 Pro 層級註冊，並由 NEXTPDF_AST_TOOLS_ENABLED 管控（預設啟用）。它們是唯讀的。

符號（Symbol）參數預設行為回傳擲出或失敗條件備註
get_document_astpdf_data（必填）。建構語意 AST：一棵完整的節點樹，且每個結構元素都帶有引用錨點（citation anchor）。JSON 節點樹，外加用於並行控制（concurrency control）的 ETag。文件格式異常時回傳錯誤結果。類別 GetDocumentAstTool。風險 RiskLevel::Safe。層級 pro。
get_ast_nodepdf_data（必填）、node_id（必填）。取得單一 AST 節點及其所有子節點。帶有其子節點的 JSON 節點。當 node_id 不明時回傳錯誤結果。類別 GetAstNodeTool。風險 RiskLevel::Safe。層級 pro。
get_ast_difforiginal_pdf_data（必填）、modified_pdf_data（必填）。透過比對兩份文件的語意 AST，產生結構化差異。列出新增、移除與變更節點的 JSON。輸入文件格式異常時回傳錯誤結果。類別 GetAstDiffTool。風險 RiskLevel::Safe。層級 pro。
search_ast_nodespdf_data（必填），型別、頁面索引（Index）與文字篩選為選填。依型別、頁面索引或文字內容搜尋 AST 節點。JSON 扁平清單，列出符合的節點及其淺層子節點。文件格式異常時回傳錯誤結果。類別 SearchAstNodesTool。風險 RiskLevel::Safe。層級 pro。
extract_cited_textpdf_data（必填），headings_only 為選填。擷取帶有引用錨點（頁面、定界框、信心值）的文字區塊。帶有引用資訊的 JSON 文字區塊。文件格式異常時回傳錯誤結果。類別 ExtractCitedTextTool。風險 RiskLevel::Safe。層級 pro。類別（category） ast。
extract_cited_tablespdf_data（必填）。擷取帶有引用錨點的表格區塊；每個 Table 節點回傳一個以列為主（row-major）的儲存格矩陣。帶有錨點的 JSON 表格矩陣。文件格式異常時回傳錯誤結果。類別 ExtractCitedTablesTool。風險 RiskLevel::Safe。層級 pro。類別（category） extraction。

AST 變更（mutation）工具

標題為「AST 變更（mutation）工具」的區段

這些工具隨伺服器一同提供，在 Pro 層級註冊，並由 NEXTPDF_MUTATION_TOOLS_ENABLED 管控（預設啟用）。這四個工具都是 ApprovalRequired，並透過 ETag 採用樂觀並行控制（optimistic concurrency control，OCC）。

符號（Symbol）參數預設行為回傳擲出或失敗條件備註
apply_ast_mutationspdf_data、etag、idempotency_key、mutations（皆為必填）。以原子方式套用一批 mutation；對重複的 idempotency_key 會重播快取結果。帶有變更後 PDF 與一個新 ETag 的 JSON。當 ETag 過期時發生 OCC 衝突；mutation 格式異常時則發生驗證錯誤。類別 ApplyAstMutationsTool。風險 RiskLevel::ApprovalRequired。層級 pro。
delete_ast_nodepdf_data、node_id、etag（皆為必填）。以疊加（overlay）模式移除一個節點（原始內容會被覆蓋，而非實際刪除）。帶有修改後 PDF 與一個新 ETag 的 JSON。當 ETag 過期時發生 OCC 衝突；node_id 不明時則發生錯誤。類別 DeleteAstNodeTool。風險 RiskLevel::ApprovalRequired。層級 pro。
insert_ast_nodepdf_data、parent_node_id、position、etag、node（皆為必填）。在指定位置插入一個新節點，作為父節點的子節點。帶有修改後 PDF 與一個新 ETag 的 JSON。當 ETag 過期時發生 OCC 衝突；節點格式異常時則發生驗證錯誤。類別 InsertAstNodeTool。風險 RiskLevel::ApprovalRequired。層級 pro。
update_ast_nodepdf_data、node_id、etag、updates（皆為必填）。更新節點的文字內容。帶有修改後 PDF 與一個新 ETag 的 JSON。當 ETag 過期時發生 OCC 衝突；node_id 不明時則發生錯誤。類別 UpdateAstNodeTool。風險 RiskLevel::ApprovalRequired。層級 pro。

請求與回應結構描述（schema）

標題為「請求與回應結構描述（schema）」的區段

gRPC 傳輸在 Protocol Buffers 套件 nextpdf.connect.v1 中定義伺服器的型別化結構描述，檔案位於 proto/nextpdf/connect/v1/*.proto。此服務及其訊息就是正式的結構描述符號。

服務 NextPDFConnect

標題為「服務 NextPDFConnect」的區段

服務 NextPDFConnect 對外提供 unary 與 server-streaming 兩種 RPC。結構描述符號就是這些 RPC 方法名稱，以及它們所承載的請求與回應訊息。

RPC請求訊息回應訊息形態
RenderRenderRequestRenderResponseUnary。同步、無狀態的繪製。
RenderStreamRenderRequestRenderChunk（串流）Server-streaming。繪製結果以有序區塊（chunk）形式傳遞。
SubmitJobSubmitJobRequestJobResponseUnary。提交一個非同步的繪製工作（job）。
GetJobStatusGetJobStatusRequestJobResponseUnary。輪詢工作狀態。
GetJobResultGetJobResultRequestRenderResponseUnary。下載已完成的結果。
GetJobResultStreamGetJobResultRequestRenderChunk（串流）Server-streaming。以區塊形式下載已完成的結果。
CancelJobCancelJobRequestJobResponseUnary。取消或刪除一個工作。
CreateSessionCreateSessionRequestSessionResponseUnary。建立一個文件建構工作階段（session）。
GetSessionGetSessionRequestSessionResponseUnary。取得工作階段中繼資料。
DestroySessionDestroySessionRequestDestroySessionResponseUnary。銷毀一個工作階段及其文件。
SessionOperationSessionOperationRequestSessionResponseUnary。對工作階段文件執行一項操作。
SessionRenderSessionRenderRequestRenderResponseUnary。把工作階段文件繪製成 PDF。
SessionRenderStreamSessionRenderRequestRenderChunk（串流）Server-streaming。把工作階段文件以區塊形式繪製。
ExecuteCapabilityCapabilityRequestCapabilityResponseUnary。執行一項受層級管控的能力操作。
GetCapabilitiesGetCapabilitiesRequestGetCapabilitiesResponseUnary。列出已驗證用戶端可用的各項能力。
HealthCheckHealthCheckRequestHealthCheckResponseUnary。存活性探測（liveness probe）。
ReadinessCheckReadinessCheckRequestReadinessCheckResponseUnary。就緒性探測（readiness probe）。

訊息符號

標題為「訊息符號」的區段

請求與回應訊息是結構描述的結構性符號。繪製訊息——RenderRequest、RenderResponse，以及串流式的 RenderChunk——承載頁面尺寸、方向、有序操作，以及產生的 PDF 位元組。工作訊息——SubmitJobRequest、GetJobStatusRequest、GetJobResultRequest、CancelJobRequest，以及 JobResponse——建模非同步工作的生命週期，工作中繼資料則保存在 JobData 訊息中。工作階段訊息——CreateSessionRequest、SessionResponse、GetSessionRequest、DestroySessionRequest、DestroySessionResponse、SessionOperationRequest，以及 SessionRenderRequest——建模有狀態工作階段的生命週期，工作階段中繼資料則保存在 SessionData 訊息中。能力訊息——CapabilityRequest、CapabilityResponse、GetCapabilitiesRequest，以及 GetCapabilitiesResponse——承載受層級管控的操作派發與內省（introspection）。系統訊息——HealthCheckRequest、HealthCheckResponse、ReadinessCheckRequest，以及 ReadinessCheckResponse——承載存活性與就緒性狀態。

隨附的 .proto 檔案是正式的線路約定；gRPC 傳輸參考請見 gRPC 傳輸。

錯誤模型

標題為「錯誤模型」的區段

伺服器以各傳輸原生的錯誤機制回報失敗。各傳輸維持相同的邏輯條件；只有編碼方式不同。

MCP

標題為「MCP」的區段

MCP 錯誤是 JSON-RPC 2.0 錯誤物件。未知的方法會回傳 method-not-found（-32601）；不是有效 JSON-RPC 的訊息會回傳 invalid-request（-32600）；無法剖析的輸入會回傳 parse-error（-32700）。當某個工具失敗時，會回傳一個成功的 JSON-RPC 回應，並在其內容中標示錯誤，而非回傳傳輸層級的錯誤，讓代理（agent）仍能讀取該訊息。針對 ApprovalRequired 工具的確認挑戰同樣是成功的回應，而非錯誤。

REST

標題為「REST」的區段

REST 使用超文字傳輸協定（Hypertext Transfer Protocol，HTTP）狀態碼，其語意由 RFC 9110 定義。200 表示成功，並夾帶處理結果；當請求欄位未通過格式驗證時，會回傳 400；當未提供有效的 API key 時，會回傳 401，並夾帶 WWW-Authenticate: Bearer 驗證質詢標頭；當金鑰有效但其方案層級無權執行該操作時，會回傳 403；當依方案層級啟用的路由因其套件不存在而未註冊時，會回傳 404。機器可讀的錯誤回應主體是符合 RFC 9457 的問題詳情（Problem Details）文件，以 application/problem+json 媒體類型提供，並針對每一種錯誤狀況各有一個穩定的 type 統一資源識別碼（Uniform Resource Identifier，URI）。欄位層級的驗證失敗會列在回應主體中。為了強化路徑穿越（path-traversal）防護，凡是 document_id 不符合 doc_[a-f0-9]{24} 樣式時，都會在工具執行前以 400 拒絕。REST 的中介軟體管線與路由表記載於 REST 傳輸一節。

gRPC

標題為「gRPC」的區段

gRPC 使用標準的 gRPC 狀態碼。當 token 缺漏、格式異常、未知、已停用或已過期時，呼叫會以 UNAUTHENTICATED 失敗，而非回傳 HTTP 狀態。豐富的錯誤細節沿用 REST Problem Details 的形態，並承載於 gRPC 狀態細節中，使錯誤 type URI 在各傳輸間保持一致。

另請參閱：RFC 9110（HTTP 語意）了解狀態碼語意，以及 RFC 9457（HTTP API 的 Problem Details）了解錯誤主體格式。

速率限制與配額

標題為「速率限制與配額」的區段

REST 傳輸在其 middleware 管線中套用以網際網路協定位址為單位（per-IP）與以用戶端為單位的速率限制，外加主體大小限制、層級 payload 限制，以及每個請求的逾時。相關上限是組態值，並非寫死的常數：

  • 各層級的 payload 上限（corePayloadLimit、proPayloadLimit、enterprisePayloadLimit）以及對應的逾時，會依已驗證 key 的層級在 REST 上套用。請參閱 組態。
  • 記憶體內的文件儲存區受 max_documents（預設 50）與 document_ttl（預設 1800 秒）所限制。
  • 速率限制與冪等性（idempotency）狀態是以 worker 為單位，除非設定了 NEXTPDF_REDIS_HOST 以使用共用儲存區。請參閱 部署。

當速率限制與冪等性儲存區為共用時，重複提交的相同非同步工作會依 idempotency_key 去重複。MCP 傳輸透過管線一次處理一個請求，並透過 64 筆緩衝區去重複出現的請求 id，而不套用網路速率限制。

開發注意事項

標題為「開發注意事項」的區段
  • 從 src/Tools/ 下的原始碼讀取工具名稱、類別與風險層級；不要假設總數固定。請向執行中的伺服器查詢權威數量，做法如 工具型錄 所示。
  • 從隨附的 proto/nextpdf/connect/v1/*.proto 檔案重新產生 gRPC 用戶端 stub；其套件與命名空間（namespace）為 nextpdf.connect.v1。不要手動編輯產生的訊息類別。
  • 一個 ApprovalRequired 工具在第一次呼叫時會以確認挑戰回應。在你交付任何驅動 _confirmation_token 或任何 mutation 工具的整合之前，先把重試路徑建好——轉達挑戰碼，再以 output_pdf 重新呼叫。
  • 未安裝的受層級管控路由或能力並非驗證失敗：REST 對缺席的路由回傳 404，而 gRPC ExecuteCapability 會把該操作回報為不可用。請把缺席的 Pro 或 Enterprise 層級視為預期內的運作，而非故障。
  • API key 不要納入版本控制；請從 secret 檔案掛載，並優先採用可熱重載的檔案式 key 儲存區，使輪替（rotation）無需重新啟動。請參閱 安全與維運。

另請參閱

標題為「另請參閱」的區段