跳至主要內容
PPDF123

開發者適用的 PDF123:REST API、SDK、命令列與 MCP

PDF123 開發者平台以四種介面提供同一套 97 個 PDF 工具:以 OpenAPI 描述的 REST API、TypeScript SDK、pdfx 命令列,以及給 AI 代理使用的 MCP 伺服器。匿名呼叫不需要帳號或 API 金鑰。

本頁內容

該用哪種方式從程式碼使用 PDF123?

四種介面呼叫的是同一組操作,因此合併的結果在每一種介面中都相同。請依程式碼的執行環境來選擇。

介面適用情境安裝方式或位址指南
REST API任何程式語言、伺服器、Shell 指令碼https://pdf123.xyz/api/v1API 參考文件
TypeScript SDK需要型別的 Node、Bun 與瀏覽器程式碼npm install @pdf123/sdkSDK 指南
命令列終端機、CI 工作、成批的本機檔案npm install -g @pdf123/cliCLI 指南
MCPClaude Code、Claude Desktop、Cursor 等 AI 代理npx -y @pdf123/mcp 或 https://pdf123.xyz/mcpMCP 指南

如果你的程式碼不是用 TypeScript 寫的,請使用 REST API。如果是,建議使用 SDK,因為工具選項有型別,並會在上傳前先檢查。一次性的工作與 Shell 指令碼適合用命令列。若要讓 AI 代理自行決定執行哪個工具,請使用 MCP。

目錄中共有 97 個工具,其中 58 個在本網站有專屬頁面,例如合併 PDF、分割 PDF 與壓縮 PDF。其餘是沒有網頁的後端操作,全部都能在 SDK、命令列與 MCP 中使用。

如何執行第一個請求?

用 curl 合併兩個檔案。請求是 multipart 表單,每個檔案對應一個 fileInput 部分。

REST:合併兩份 PDFbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

用 TypeScript SDK 做同樣的合併:

SDK:合併兩份 PDFts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

用命令列做同樣的合併:

CLI:合併兩份 PDFbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

驗證如何運作?

匿名呼叫公開 API 不需要帳號,也不需要金鑰。若想標示自己的流量,或要呼叫一律需要金鑰的託管 MCP 端點,請在 X-API-KEY 標頭中帶上 API 金鑰。

請登入後在下方面板建立金鑰,並妥善保存。

正在檢查登入狀態…

帶金鑰呼叫 APIbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

SDK 以 apiKey 接收金鑰。命令列與本機 MCP 伺服器則從環境變數 PDFX_API_KEY 讀取。

注意

在自架的伺服器上,設定環境變數 SECURITY_CUSTOMGLOBALAPIKEY 即可指定一組伺服器接受的金鑰。請參閱自架。

API 參考文件在哪裡?

REST API 有兩種文件形式。Swagger UI 讓你在瀏覽器中試用每個端點。OpenAPI 文件則是供用戶端產生器使用、可由機器讀取的來源。

每個操作都是基礎網址 https://pdf123.xyz/api/v1 下的 POST 請求,並依類別分組。例如合併是 /general/merge-pdfs,壓縮是 /misc/compress-pdf。

如何在一次請求中串接多個工具?

POST /api/v1/pipeline 接收 fileInput 部分與 steps 欄位。steps 欄位是 JSON 陣列,其中每個物件包含 op 和選用的 params。每個步驟都會接收上一個步驟的輸出。

一次請求完成合併再壓縮bash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

如何安全地重試請求?

在任何操作上都可以帶 Idempotency-Key 標頭。24 小時內重複送出相同的請求時,不會再次執行,而是回傳第一次的結果,並附上標頭 Idempotency-Replayed: true。若把同一個金鑰用在不同的請求上,該請求會被拒絕。大於 32 MiB 的結果不會被儲存,因此重複這類請求會得到 409,需要改用新的金鑰。

大小與頻率限制是多少?

限制數值
網站上的檔案大小每個檔案 500 MB
單一直接 API 請求的內容100 MiB,含 multipart 封裝
分段上傳總大小超過 95 MB 時,SDK 會自動改用上傳 API

回應帶有標頭 X-RateLimit-Limit、X-RateLimit-Remaining 與 X-RateLimit-Reset。狀態碼為 429 的回應還會加上 Retry-After。請讀取這些標頭,而不要假設固定的配額,因為自架的伺服器有自己的限制。部落格文章請求大小限制說明了內容過大時會遇到的錯誤。

錯誤長什麼樣子?

失敗時會回傳 application/problem+json,包含欄位 type、title、status、detail、code、reason 與 hint。請優先依 reason 判斷,找不到時再退回使用 code。detail 的文字是寫給人看的,不會包含工具的原始輸出。所有代碼都列在錯誤代碼。

代碼或 reasonHTTP 狀態意義
bad_request400參數或 multipart 內容無效
password_required400PDF 已加密,但沒有傳入密碼
invalid_pdf400檔案不是 PDF 或已損壞;可試試修復 PDF
page_out_of_range400要求的頁面不存在
not_found404未知的操作路徑
rate_limited429配額已用完;請等待 Retry-After

可以先呼叫哪些工具?

這十二個工具涵蓋大部分的請求。想先在瀏覽器中試用,可以開啟對應的工具頁。

工具頁API 端點CLI 指令功能
合併/general/merge-pdfspdfx merge把多份 PDF 合成一份
分割/general/split-pagespdfx split把一份 PDF 切成多個檔案
壓縮/misc/compress-pdfpdfx compress重新壓縮 PDF 資料流以縮小體積
旋轉/general/rotate-pdfpdfx rotate變更頁面方向
加入密碼/security/add-passwordpdfx protect用密碼加密 PDF
移除密碼/security/remove-passwordpdfx unlock解除密碼保護
加入浮水印/security/add-watermarkpdfx watermark加入文字或圖片浮水印
OCR/misc/ocr-pdfpdfx ocr讀取掃描的 PDF 並回傳 Markdown
PDF 轉 Markdown/convert/pdf/markdownpdfx pdf-to-markdown把 PDF 轉成 Markdown
PDF 轉 Word/convert/pdf/wordpdfx convert-to-word把 PDF 轉成可編輯的 Word 檔
文件資訊/security/get-info-on-pdfpdfx get-info回報中繼資料、權限、字型與結構
修復/misc/repairpdfx repair重建損壞 PDF 的結構

端點是相對於 https://pdf123.xyz/api/v1 的路徑。執行 pdfx list 或開啟 OpenAPI 文件,即可看到全部 97 個工具。

如何從 AI 代理使用 PDF123?

代理可以用三種方式使用這些工具:

  • 連接 MCP 伺服器。MCP 指南涵蓋處理本機檔案的 @pdf123/mcp 本機伺服器,以及位於 https://pdf123.xyz/mcp 的託管端點。
  • 載入代理 Skill。Agent Skill 是給 Claude Code、Codex、Cursor 等工具使用的 SKILL.md 檔案,有一個對應整個目錄,另外每個工具各有一個。
  • 讀取網站索引。/llms.txt 以純文字列出工具、API 與 MCP 端點,/site.jsonld 則以結構化資料描述本站。

PDF123 部落格的文章〈為 AI 代理而生,而不只是為瀏覽器〉說明了 REST API 與 MCP 如何搭配運作。

可以在自己的伺服器上執行 PDF123 嗎?

可以。後端是 pdfx-server 程式,在 Docker 中執行。用 PDFX_API_BASE 把 SDK、命令列或 MCP 伺服器指向它,檔案就會留在你的網路內。設定方式請參閱自架,支援方案請參閱企業版。

常見問題

PDF123 API 免費嗎?

匿名使用免費。呼叫公開 API 不需要帳號或金鑰。託管服務的回應包含頻率限制標頭,用戶端可以在收到 429 回應之前先放慢速度。

需要 API 金鑰嗎?

使用公開網站時,REST API、SDK 與命令列都不需要。位於 /mcp 的託管 MCP 端點則需要,沒有 X-API-KEY 標頭會回應 401。登入後即可在本頁建立金鑰。

檔案大小上限是多少?

網站接受每個最大 500 MB 的檔案。單一直接 API 請求的內容最大可達 100 MiB,含 multipart 封裝。總大小超過 95 MB 後,SDK 會自動以分段方式上傳較大的輸入。

可以自架 API 嗎?

可以。自行執行伺服器,並把 API 基礎位址設為它的位址即可。SDK、命令列與本機 MCP 伺服器都接受自訂的基礎網址。

如何回報錯誤?

請複製問題回應中的 code、reason 與 detail 欄位,連同請求的時間,透過聯絡頁面寄給我們。除非客服要求,否則請不要附上 PDF 檔案本身。

該用 SDK、命令列還是 MCP?

在 TypeScript 程式碼中使用 SDK,指令碼與成批的本機檔案使用命令列,由 AI 代理選擇工具時使用 MCP。三者共用同一份目錄與同一個伺服器,所以也可以搭配使用。