How-to2026-11-01約 2 分鐘閱讀

不用 API Key 的免費 PDF API：匿名呼叫能做到什麼

PDF123 的 REST API 不需要 API Key 與帳號。用 curl 合併、壓縮 PDF，附上大小限制、錯誤回應的格式，以及收到 HTTP 429 時用戶端該怎麼做。

By the PDF123 team · Updated 2026-11-01

有。PDF123 的 REST API 不需要 API Key，也不需要帳號：測試時，用最普通的 curl 先後呼叫合併 PDF與壓縮 PDF的端點，沒有帶 X-API-KEY 標頭，兩次都回傳 HTTP 200 和一個 PDF。限制一次呼叫的是它的大小，以及分段上傳同時開了多少個，與呼叫者是誰無關：一次請求的請求本體最多 100 MiB，每個回應都帶有 X-RateLimit-* 標頭。

有沒有不需要 API Key 的免費 PDF API？

匿名使用沒有問題：開發者頁面寫明，呼叫公開 API 不需要帳號，也不需要 Key。OpenAPI 文件把 X-API-KEY 列為驗證方式，但下面的呼叫都沒有帶它。

指令於 2026-10-23 在本機執行的一份伺服器上跑過，這裡把位址換成 https://pdf123.xyz。輸入是兩個單頁 PDF，由兩個很短的 Markdown 檔產生。合併時每個檔案傳一個 fileInput 部分，順序就是頁面在結果中的順序：

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

回應是 HTTP 200，content-type: application/pdf。qpdf --show-npages merged.pdf 輸出 2，pdftotext 讀到的文字先是 a.pdf 的，再是 b.pdf 的。下載下來的檔案以第一個輸入命名，也就是 a.pdf，存到原檔旁邊之前先改個名稱。

壓縮只傳一個檔案：

curl -X POST https://pdf123.xyz/api/v1/misc/compress-pdf \
  -F [email protected] \
  -o small.pdf

這次同樣是 HTTP 200。回應標頭 X-Original-Bytes: 28564 與 X-Compressed-Bytes: 25113 和磁碟上兩個檔案的大小一致，指令碼不必開啟檔案就能知道這次呼叫做了什麼。這兩個數字只屬於一個很小的測試檔，不代表你的檔案會被壓到多小。

不帶 Key，有哪些限制？

伺服器在 GET /api/v1/info/status 回報它的大小限制，這個介面同樣不需要 Key。它回傳的值，換算成 MiB（1 MiB 是 1,048,576 位元組）如下：

欄位	值	限制的是什麼
`maxUploadBytes`	104,857,600（100 MiB）	一次直接請求的請求本體，含 multipart 封裝
`maxChunkedUploadBytes`	524,288,000（500 MiB）	透過分段上傳介面傳送的單一檔案
`uploadChunkBytes`	33,554,432（32 MiB）	每一段的大小
`maxOcrPages`	50	一次 OCR 請求中需要辨識的頁數

限制頁讀的是同一個介面，並補上網站自己的上限，例如批次處理。請求本體超限時回傳什麼錯誤，見大型 PDF 上傳被拒：100 MiB 請求本體上限，與那個指向錯誤方向的訊息。

包括上面這些在內，每個回應都帶了三個標頭：x-ratelimit-limit: 100000、x-ratelimit-remaining: 100000 與 x-ratelimit-reset: 0。在我做的這幾次呼叫裡，數字沒有變動。沒有設定週期上限時，伺服器寫 100000，reset 則一律寫 0，所以在那台伺服器上，這些標頭宣告的不是一個會遞減的配額。它們也無法說明日後某一天 pdf123.xyz 的配額是多少：請在你自己的回應上讀取，不要把某個數字寫死在程式裡。標頭的用途見不必登入：匿名速率限制如何讓免費工具保持免費。

介面文件在哪裡？

OpenAPI 3 文件在 https://pdf123.xyz/v1/openapi.json，https://pdf123.xyz/swagger-ui 則把同一套 API 放在一個頁面裡，可以逐個端點試用。每個操作都是 /api/v1 底下的 POST，依類別分組：合併是 /general/merge-pdfs，壓縮是 /misc/compress-pdf。網站上的工具頁呼叫的是同一批端點。

想要能直接複製執行的範例，範例裡常見的工作都有 curl、pdfx 與 Node 三種寫法。開發者頁面還介紹了 SDK、命令列與 MCP。

出錯時回傳什麼？收到 429 該怎麼辦？

失敗的呼叫回傳 application/problem+json，格式由 RFC 9457《Problem Details for HTTP APIs》定義。把一個名為 fake.pdf 的文字檔傳兩次給合併，回傳 HTTP 400 與下面這個回應本體（這裡重新排版，鍵的順序與回傳一致）：

{
  "code": "invalid_document",
  "detail": "The file is not a valid PDF or it is damaged.",
  "error": "The file is not a valid PDF or it is damaged.",
  "hint": "Upload a valid, undamaged PDF. Try the Repair tool first.",
  "reason": "invalid_pdf",
  "status": 400,
  "title": "Bad Request",
  "type": "https://pdf123.xyz/developers/errors#invalid_document"
}

code 是粗粒度的類別，reason 是具體原因。錯誤碼頁列出兩者，並建議先依 reason 分支，再退回到 code。error 重複了 detail，給舊的用戶端使用。

在那台伺服器上，我唯一能觸發的 429 來自分段上傳：已經開著 32 個上傳時，再要求開始第 33 個就被拒絕。回應是 HTTP 429，reason 為 upload_limit_reached，code 為 rate_limited，帶有 retry-after: 60 標頭，同時有一般的 x-ratelimit-* 標頭。32 是伺服器的預設值，其他伺服器可以設成不同的數字。合併、壓縮這類操作呼叫在我的測試中沒有回傳過 429，但用戶端仍然應該處理它：開發者頁面把 rate_limited、狀態碼 429 列為配額用完時的回應。RFC 6585 把這個狀態碼定義為在一段時間內請求過多，並說明伺服器可以附上 Retry-After 告知用戶端該暫停多久。

收到 429，用戶端該做的事：

等滿 Retry-After 給的秒數（我看到的回應是 60），再送出同一個請求。不要在緊湊的迴圈裡重試。
如果 reason 是 upload_limit_reached，把不再需要的上傳收尾或放棄。DELETE /api/v1/uploads/{id} 可以中止一個上傳，沒完成的上傳一小時後自行過期。
等待要自己處理。SDK、pdfx 命令列與 MCP 伺服器不會自動重試。

什麼時候值得建立 API Key？

開發者頁面給了兩個理由：標示你自己的流量，以及呼叫託管的 MCP 端點 https://pdf123.xyz/mcp，後者一律要求帶 Key。在我執行的伺服器上，不帶 Key 請求 /mcp 回傳 401。Key 在那個頁面登入後建立，放在 X-API-KEY 標頭中傳送。在公開網站上使用 REST API、SDK 與命令列，不需要 Key。自行架設伺服器時，可以用環境變數 SECURITY_CUSTOMGLOBALAPIKEY 設定一個伺服器認可的 Key。

常見問題

PDF123 的 API 真的免費嗎？

匿名呼叫公開 API 不需要帳號，也不需要 Key，上面的範例兩樣都沒用。限制就是上面表格裡的那些，任何配額都以你自己回應上的標頭為準。

呼叫它一定要登入嗎？

不用。只有建立 Key 才需要登入，託管的 MCP 端點要 Key，REST API 不要。

能傳送超過 100 MiB 的 PDF 嗎？

可以，每個檔案最大 500 MiB，走分段上傳介面：先建立上傳，逐一傳送 32 MiB 的分段，完成後把它的 id 交給操作。TypeScript SDK 與 pdfx 會自動切換成這種方式。具體步驟見錯誤碼頁的「Files over 100 MB」一節。

怎麼知道我呼叫的伺服器有哪些限制？

呼叫 GET /api/v1/info/status。它回報那台伺服器的請求本體大小、分段上傳的大小與分段大小，以及 OCR 頁數上限，限制頁的數字就來自它。

Open tool

Process in the browser — no watermark, files removed after the job.

Open tool