該用哪種方式從程式碼使用 PDF123?
四種介面呼叫的是同一組操作,因此合併的結果在每一種介面中都相同。請依程式碼的執行環境來選擇。
| 介面 | 適用情境 | 安裝方式或位址 | 指南 |
|---|---|---|---|
| REST API | 任何程式語言、伺服器、Shell 指令碼 | https://pdf123.xyz/api/v1 | API 參考文件 |
| TypeScript SDK | 需要型別的 Node、Bun 與瀏覽器程式碼 | npm install @pdf123/sdk | SDK 指南 |
| 命令列 | 終端機、CI 工作、成批的本機檔案 | npm install -g @pdf123/cli | CLI 指南 |
| MCP | Claude Code、Claude Desktop、Cursor 等 AI 代理 | npx -y @pdf123/mcp 或 https://pdf123.xyz/mcp | MCP 指南 |
如果你的程式碼不是用 TypeScript 寫的,請使用 REST API。如果是,建議使用 SDK,因為工具選項有型別,並會在上傳前先檢查。一次性的工作與 Shell 指令碼適合用命令列。若要讓 AI 代理自行決定執行哪個工具,請使用 MCP。
目錄中共有 97 個工具,其中 58 個在本網站有專屬頁面,例如合併 PDF、分割 PDF 與壓縮 PDF。其餘是沒有網頁的後端操作,全部都能在 SDK、命令列與 MCP 中使用。
如何執行第一個請求?
用 curl 合併兩個檔案。請求是 multipart 表單,每個檔案對應一個 fileInput 部分。
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdf用 TypeScript SDK 做同樣的合併:
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" });用命令列做同樣的合併:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf驗證如何運作?
匿名呼叫公開 API 不需要帳號,也不需要金鑰。若想標示自己的流量,或要呼叫一律需要金鑰的託管 MCP 端點,請在 X-API-KEY 標頭中帶上 API 金鑰。
請登入後在下方面板建立金鑰,並妥善保存。
正在檢查登入狀態…
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.pdfSDK 以 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。每個步驟都會接收上一個步驟的輸出。
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 的文字是寫給人看的,不會包含工具的原始輸出。所有代碼都列在錯誤代碼。
| 代碼或 reason | HTTP 狀態 | 意義 |
|---|---|---|
bad_request | 400 | 參數或 multipart 內容無效 |
password_required | 400 | PDF 已加密,但沒有傳入密碼 |
invalid_pdf | 400 | 檔案不是 PDF 或已損壞;可試試修復 PDF |
page_out_of_range | 400 | 要求的頁面不存在 |
not_found | 404 | 未知的操作路徑 |
rate_limited | 429 | 配額已用完;請等待 Retry-After |
可以先呼叫哪些工具?
這十二個工具涵蓋大部分的請求。想先在瀏覽器中試用,可以開啟對應的工具頁。
| 工具頁 | API 端點 | CLI 指令 | 功能 |
|---|---|---|---|
| 合併 | /general/merge-pdfs | pdfx merge | 把多份 PDF 合成一份 |
| 分割 | /general/split-pages | pdfx split | 把一份 PDF 切成多個檔案 |
| 壓縮 | /misc/compress-pdf | pdfx compress | 重新壓縮 PDF 資料流以縮小體積 |
| 旋轉 | /general/rotate-pdf | pdfx rotate | 變更頁面方向 |
| 加入密碼 | /security/add-password | pdfx protect | 用密碼加密 PDF |
| 移除密碼 | /security/remove-password | pdfx unlock | 解除密碼保護 |
| 加入浮水印 | /security/add-watermark | pdfx watermark | 加入文字或圖片浮水印 |
| OCR | /misc/ocr-pdf | pdfx ocr | 讀取掃描的 PDF 並回傳 Markdown |
| PDF 轉 Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | 把 PDF 轉成 Markdown |
| PDF 轉 Word | /convert/pdf/word | pdfx convert-to-word | 把 PDF 轉成可編輯的 Word 檔 |
| 文件資訊 | /security/get-info-on-pdf | pdfx get-info | 回報中繼資料、權限、字型與結構 |
| 修復 | /misc/repair | pdfx 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。三者共用同一份目錄與同一個伺服器,所以也可以搭配使用。