API 快速入門:轉換你的第一個檔案
建立 API 金鑰、傳送檔案、等待工作完成並下載結果,附可直接複製使用的請求範例。
簡要回答
在「主控台 → API 與金鑰」中建立金鑰,然後傳送 POST https://maxscanner.app/api/v1/jobs/ 請求,附帶公開的檔案網址、檔案名稱和目標格式。API 會立即傳回 jobId;每隔幾秒輪詢一次 GET /api/v1/jobs/{jobId}/,直到 status 變為 "completed",然後在五分鐘內下載 output.downloadUrl。
快速入門
- 1打開「主控台 → API 與金鑰」,選擇「建立 API 金鑰」,勾選「處理檔案」,然後複製金鑰(它只顯示一次)。
- 2將金鑰儲存在 MAXSCANNER_API_KEY 之類的環境變數中,切勿寫進用戶端程式碼。
- 3呼叫 POST /api/v1/jobs/,傳入 url、filename 和 format。儲存 202 回應中傳回的 jobId。
- 4每隔 2–10 秒呼叫一次 GET /api/v1/jobs/{jobId}/,直到 status 變為 completed 或 failed。
- 5立即下載 output.downloadUrl:簽署連結會在五分鐘後過期。
開始之前
所有請求都傳送到 https://maxscanner.app/api/v1/,並以 Bearer 權杖的形式攜帶金鑰。請求網址以斜線結尾:不帶斜線的網址會收到 308 重新導向,大多數 HTTP 用戶端會自動跟隨,但直接帶上斜線可以省去一次往返。
免費方案每天允許 10 次請求、每月 100 次,足以建立和測試一個整合。付費方案改用每月點數計費;每個端點消耗 0 到 3 點數。
- 基礎網址:https://maxscanner.app/api/v1/
- 請求標頭:Authorization: Bearer <your key>
- 請求主體:JSON,Content-Type: application/json
- 檔案:透過網址匯入或直接上傳,最大 50 MB
將 Word 檔案轉換為 PDF
jobs 端點會根據輸入和輸出格式自動選擇合適的處理器。傳入公開網址時,伺服器會在建立工作時自行下載檔案(最大 50 MB,須在 30 秒內完成;不會跟隨重新導向,請使用最終的檔案連結);私人檔案請使用直接上傳,並改為傳入 sourceKey(參見「檔案與上傳」指南)。新增 Idempotency-Key 請求標頭,確保重試的請求不會建立第二個工作。
curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-0001' \
-d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'等待結果
工作以非同步方式處理,因此大檔案不會一直佔用你的 HTTP 連線。輪詢狀態網址:從約 2 秒的間隔開始,逐步退避到 10 秒。小型 Office 檔案通常在 20 秒內完成;1080p 影片可能需要幾分鐘。當 status 為 completed 時,output 會包含內容類型、以位元組為單位的大小,以及一個已簽署的 downloadUrl。
curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY"下一步
當需要處理的檔案不止寥寥幾個時,請改用 Webhook 代替輪詢;閱讀工作指南了解重試規則;再根據你的需求選擇對應的功能指南:OCR、PDF 工具、圖片、媒體,或執行已儲存的工作流程。
常見問題
需要安裝 SDK 嗎?
不需要。該 API 基於一般的 HTTPS 和 JSON,任何能傳送 HTTP 請求的程式語言或無程式碼工具都可以使用。程式碼範例指南提供了完整的 Node.js、Python、PHP 和 cURL 版本。
下載連結的有效期是多久?
五分鐘。如果連結已過期,再次請求工作狀態即可獲得新的連結。
有測試模式嗎?
請使用免費方案進行測試:它提供相同的端點,並限制每個帳戶每天 10 次、每月 100 次請求。