跳到內容
NextPDF

Connect REST API 參考

概覽

標題為「概覽」的區段

NextPDF Connect 會透過 HTTP，以 REST 傳輸形式公開它的工具註冊表，並以一份 OpenAPI 3.1 合約描述。本頁是該介面的參考：base URL、驗證方式、操作群組與錯誤模型。完整的機器可讀規格已公開發布，你可以把它載入互動式 API 瀏覽器、用戶端產生器或請求用戶端，完全不必手動複製任何內容。

若要查看不受傳輸方式影響的工具目錄（同一組操作同時透過 Model Context Protocol、gRPC 與 REST 提供），請參閱 Connect API 參考。若要了解 RoadRunner 管線、部署與驗證設定，請參閱 REST 傳輸指南。

Base URL 與驗證

標題為「Base URL 與驗證」的區段

REST 傳輸會在你部署所設定的主機與連接埠上監聽。本機執行時是 http://localhost:8080；在正式環境中則是你的 worker 池前方的位址。

驗證採用 bearer token。對每個受 tier 控管的路由發出請求時，都必須在 Authorization 標頭中送出 API key：

Terminal window
curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

唯讀的 liveness 與 readiness 探測不需要 token。

操作

標題為「操作」的區段

可用性受 tier 控管。開源核心提供 document、render、session 與 job 操作。簽署、表單填寫、塗黑（redaction）、比對、無障礙檢查與最佳化，則需在伺服器端安裝對應的商業版。特定部署的權威操作集合由 capabilities endpoint 回傳。請查詢它，不要假設是一份固定清單。

健康狀態與生命週期

標題為「健康狀態與生命週期」的區段
方法路徑用途
GET/healthzLiveness 探測。不需驗證。
GET/readyzReadiness 探測（相依項目與 worker 池就緒）。不需驗證。
GET/api/v1/capabilities此部署實際公開的工具與 tier。請先查詢這個。

渲染與文件

標題為「渲染與文件」的區段
方法路徑用途
POST/api/v1/render依照一份有序操作清單渲染文件，並回傳該 PDF。
POST/api/v1/extract-text從 PDF 擷取文字內容。
POST/api/v1/merge將多份 PDF 輸入合併為一份文件。
POST/api/v1/split將一份 PDF 拆分為多份文件。

非同步 job

標題為「非同步 job」的區段
方法路徑用途
POST/api/v1/jobs以 job 形式提交需長時間執行的操作。
GET/api/v1/jobs/{id}輪詢 job 狀態。
GET/api/v1/jobs/{id}/result取得已完成的 job 結果。

工作階段（Session）

標題為「工作階段（Session）」的區段

Session 會讓文件在多次呼叫之間保持開啟，因此你可以逐步建構，最後再一次渲染。

方法路徑用途
POST/api/v1/sessions開啟一個 session。
GET / DELETE/api/v1/sessions/{sessionId}檢視或關閉 session。
POST/api/v1/sessions/{sessionId}/pages新增一頁。
POST/api/v1/sessions/{sessionId}/text新增文字。
POST/api/v1/sessions/{sessionId}/images新增一張影像。
POST/api/v1/sessions/{sessionId}/tables新增一個表格。
POST/api/v1/sessions/{sessionId}/html新增渲染後的 HTML。
POST/api/v1/sessions/{sessionId}/font設定使用中的字型。
POST/api/v1/sessions/{sessionId}/render渲染 session 文件。

商業版操作

標題為「商業版操作」的區段

這些路由只有在安裝對應的商業版時才會註冊。其中數個會由 human-in-the-loop 確認流程控管核准；請參閱 風險分級。

方法路徑用途
POST/api/v1/sign套用數位簽章。
POST/api/v1/fill-form填寫互動式表單。
POST/api/v1/redact塗黑內容。
POST/api/v1/compare比對兩份 PDF 文件。
POST/api/v1/check-accessibility執行結構性無障礙檢查。
POST/api/v1/optimize最佳化並縮減文件。

錯誤模型

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

REST 傳輸使用 HTTP 狀態碼，其語意依 RFC 9110 定義：2xx 代表成功，4xx 代表呼叫端必須修正的請求（400 主體格式錯誤、401 缺少或無效的 token、403 tier 或核准遭拒、404 未知的路由或 job、409 冪等性衝突、422 引擎無法處理的合法請求），而 5xx 代表伺服器端失敗。401 回應會帶有一個 WWW-Authenticate 挑戰。

錯誤主體是依 RFC 9457（Problem Details for HTTP APIs）格式產生的 application/problem+json 文件：一個穩定的 type、一段簡短的 title、數值化的 status，以及人類可讀的 detail。請比對 type，而不是比對 detail 字串。規範性定義另請參閱 RFC 9110（HTTP Semantics）與 RFC 9457。

提交會改變狀態的請求時，請帶上 Idempotency-Key 標頭，讓重試的請求只會被處理一次。

機器可讀規格

標題為「機器可讀規格」的區段

完整合約會以一份靜態的 OpenAPI 3.1 文件發布：

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

請將它視為 REST 介面的單一事實來源：

  1. 開啟 互動式 API explorer，這是一份由此合約產生、可在瀏覽器內執行的自架 Scalar 參考；你可以在其中閱讀並試用每個操作的請求與回應結構描述。
  2. 將它匯入 Postman 或 Insomnia 這類請求用戶端。
  3. 使用 OpenAPI 產生器，為你的語言產生型別化用戶端。

這份文件是一份靜態合約，版本與套件綁定。它不是由即時 endpoint 提供，因此跨部署都保持穩定。

另請參閱

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