開發者 API
用一個 API 將各種檔案轉換為 Markdown
在指令碼、自動化流程及產品中自動完成文件轉換。上傳支援的檔案，即可透過一次請求取得整潔的 Markdown 或純文字。
身份認證
在控制台建立 API 金鑰，然後透過 Bearer Token 或 X-API-Key 請求標頭傳送。請只在伺服器端保存金鑰，不要暴露於瀏覽器程式碼中。
curl -X POST https://www.word2md.net/api/v1/convert \
-H "Authorization: Bearer sk-your-key" \
-F "file=@./report.pdf" \
-F "output_format=markdown"介面
POST /api/v1/convert轉換檔案
使用 multipart 表單提交 file 欄位（最大 50 MB），並可將 output_format 設定為 markdown 或 text。
GET /api/v1/convert轉換能力
GET 此介面可查看支援的副檔名、檔案大小限制及目前額度規則。
GET /api/v1/usage用量及額度
GET 此介面可查看今日 API 用量、方案、剩餘額度及下次 UTC 重設時間。
支援的檔案類型
支援常見辦公文件、PDF、試算表、簡報、結構化資料、媒體、壓縮檔及圖片。
.docx.doc.pdf.pptx.ppt.xlsx.xls.csv.tsv.html.htm.xml.json.txt.md.jpg.jpeg.png.gif.webp.bmp.tif.tiff.mp3.wav.mp4.mov.avi.zip額度及計費
每個帳戶每天都有 API 免費額度。用完方案額度後，每次成功轉換會從訂閱餘額或一次性加油包扣除 1 積分。
| 方案 | 每日 API 額度 | 超額調用 |
|---|---|---|
| 免費版 | 50 / day | 加油包積分 |
| Pro | 500 / day | 加油包積分 |
| Pro+ | 1,500 / day | 加油包積分 |
| Ultimate | 已包含 | 已包含 |
回應格式
成功轉換會返回轉換內容、原始檔名、輸出格式、扣除積分及更新後的用量。
{
"success": true,
"object": "conversion",
"content": "# Report\n\n...",
"format": "markdown",
"filename": "report.pdf",
"credits_charged": 0,
"usage": { "tier": "free", "used": 1, "daily": 50, "remaining": 49 }
}錯誤及狀態碼
錯誤會以 JSON 返回，並包含穩定的錯誤碼及可讀的錯誤訊息。
401 | 缺少或無效的 API 金鑰 |
400 | 缺少檔案、副檔名不支援或檔案過大 |
402 | 每日額度及可用積分均已用盡 |
500 | 轉換服務失敗；已扣除的積分會自動退回 |
生產環境建議
- 使用 HTTPS，並將金鑰儲存至環境變數
- 上傳前驗證檔案大小
- 對暫時性 5xx 錯誤使用指數退避重試
- 讀取 usage 物件追蹤剩餘額度
- 處理完成後刪除敏感檔案
API 常見問題
可以轉換哪些檔案？
支援 Word、PDF、PowerPoint、Excel、CSV、HTML、XML、JSON、文字、Markdown、圖片、音訊、影片及 ZIP 檔案，具體取決於可用的轉換器。
免費額度如何計算？
免費帳戶每天有 50 次 API 轉換額度；Pro 每天 500 次，Pro+ 每天 1,500 次，Ultimate 不限次數。
每日額度用完後會怎樣？
超額成功轉換每次消耗訂閱餘額或加油包中的 1 積分；沒有剩餘積分時會返回 HTTP 402。
如何保護 API 金鑰？
請像保護密碼一樣保護金鑰：僅在伺服器端透過 HTTPS 保存，必要時定期輪換，洩露後立即撤銷。