---
title: "文件轉換 API"
description: "文件轉換 API 是一個 HTTPS API，在一次 POST /v1/convert/{name} 呼叫裡接收檔案、URL 或 HTML，並返回 Markdown。"
url: https://markitdown.ai/developers
updated: 2026-09-26
source: markitdown.ai
---

# 文件轉換 API

> 文件轉換 API 是一個 HTTPS API，在一次 POST /v1/convert/{name} 呼叫裡接收檔案、URL 或 HTML，並返回 Markdown。

匿名試用接受最大 10 MB、最多 25 頁的檔案，每小時每個 IP 3 次轉換、每天 10 次。Lite 每月 $20 起、單檔案最大 100 MB；Pro 每月 $50；Max 每月 $100。

- 每個檔案、URL 或內嵌文字一次 POST /v1/convert/{name} 呼叫
- 回應在 60 秒內返回 Markdown，或返回一個可供輪詢的轉換
- 與網頁應用使用同一個轉換引擎

## 文件轉換 API 如何工作

從 API key 到 Markdown，三步。每次呼叫最多等待 60 秒並返回結果；更長或多檔案的請求會返回 202 和一個可供輪詢的轉換，而不是一直佔用連線。

**請求**

```bash
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
  -H "x-api-key: mdai_…" \
  -F file=@nist-cswp-29-csf-2.0.pdf

# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
  -H "x-api-key: mdai_…" \
  -H "content-type: application/json" \
  -d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'

# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
  -H "x-api-key: mdai_…"
```

1. 建立 API key — 在「設定 → 開發者」裡建立一個 key（需要有生效中的訂閱），並在 x-api-key 請求標頭裡傳送它。
2. POST /v1/convert/{name} — 把檔案、公開 URL 或內嵌文字發到對應格式的端點。每次呼叫只發一種輸入。
3. 使用返回的 Markdown — 直接從回應裡讀取輸出，或在收到 202 之後等待 /v1/conversions/{id}。

## 回應與 webhook

下面的回應用經過核驗的 DOCX 解析器輸出來說明 API 契約；其中的轉換 ID 是佔位符。一次完成的轉換會返回 Markdown 和它所消耗的 credit。202 會帶一個指向該轉換的 Location 頭；用 ?wait= 輪詢它、訂閱它的事件流，或讓 webhook 在它完成的時候通知你。

**回應——或 conversion.completed webhook**

```text
{
  "id": "cnv_3f7c…",
  "object": "conversion",
  "name": "word",
  "status": "completed",
  "files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
  "usage": { "credits_charged": 1 }
}

POST https://your-app.example.com/webhooks
{
  "type": "conversion.completed",
  "data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}
```

訂閱 `conversion.completed` 和 `conversion.failed`，這樣一次較長或多檔案的轉換一旦完成，你就能立刻作出反應，而不必輪詢。投遞會用 Standard Webhooks 請求標頭簽名。

## 文件解析 API 與 Markdown 轉換 API

團隊在需要從檔案裡取出結構時，會去找文件解析 API；在輸出要落進提示詞或知識庫時，會去找 Markdown 轉換 API。這兩個說法指的都是這個服務。格式專屬的到達頁，比如 [pdf to markdown api](/pdf-to-markdown) 和 [url to markdown api](/url-to-markdown)，是指向對應轉換器的錨點——它們使用同一組 `/v1/convert/{name}` 端點。

- 轉換端點 — POST /v1/convert/{name}——每種格式一個端點——接收檔案、URL 或文字，返回 Markdown、純文字、HTML 或按頁輸出。
- API key — 按帳號簽發的 key 透過 x-api-key 請求標頭髮送，讓轉換可以接入任何伺服器或指令碼。
- 多檔案與 webhook — 把許多檔案發給一次轉換呼叫，拿回一個轉換；webhook 會報告每一次 conversion.completed 或 conversion.failed。
- Markdown 渲染 — POST /v1/convert/markdown/html 或 /markdown/text 把 Markdown 轉回 HTML 或純文字，不消耗 credit。

## 團隊把它接在哪裡

- RAG 攝取 — 在攝取任務裡轉換文件，再切分和嵌入。
- AI agent — 讓 agent 在流水線中途把任意檔案變成乾淨的文字。
- 內容流水線 — 把 Markdown 自動送進 CMS、文件站或知識庫。
- 內部工具 — 給你已經在跑的產品和背景工具加上文件轉換。

## 驗證、用量與限額

- API key 屬於你的帳號，只在 /v1 上生效，透過 x-api-key 請求標頭髮送——帳號需要有一個生效中的 Lite、Pro 或 Max 訂閱
- 用量與網頁應用共用同一套 credit——標準頁和 OCR 頁都是每頁 1 credit
- 套餐限速為 Lite 每分鐘 20 次、Pro 每分鐘 40 次、Max 每分鐘 60 次請求
- 每次 POST /v1/convert/{name} 呼叫都帶 Idempotency-Key，重試永遠不會重複計費
- 每個 v1 端點、請求欄位與回應都記錄在生成的 [API 參考](/docs/api) 裡；失敗會返回 problem+json，其中的 `type` URI 指向對應的[錯誤碼頁面](/docs/errors)

## 處理完成狀態

在文件轉換 API 客戶端裡，要同時處理直接完成和非同步處理。一次成功的提交可能直接返回已完成的結果，而 HTTP 202 表示回應返回之後工作仍在繼續。保留轉換標識，並在讀取輸出之前使用文件裡說明的 Location 或轉換狀態端點。不要僅僅因為 HTTP 請求成功了，就直接索引到假定的第一份輸出上。一次已完成的轉換也可能含有檔案級失敗，所以要檢查多來源請求裡的每個檔案。存下足夠的上下文，把每個返回結果和你應用提交的來源對應起來。這樣可以讓一次緩慢的轉換或部分失敗，不會悄悄變成下游系統裡的一份空文件。

## 請求限額與套餐限額

文件轉換 API 同時對請求和帳號施加限額。一次 multipart 請求最多包含 100 個檔案，合計上限為 100 MB。一次 URL 請求最多接受 20 個來源。你的訂閱另外決定 credit、儲存、單檔案限額和並行。一個 Pro 檔案可能被訂閱允許，卻因為太大而放不進一次 multipart 請求；這種情況要走文件裡說明的分塊上傳流程。不要靠假設「最高套餐就沒有傳輸限額」來繞過被拒絕的請求。讀錯誤訊息，並使用為原始檔大小準備的那種輸入方式。

## 保留來源上下文

把你自己的來源標識放在轉換標識旁邊，這樣一個結果就能追溯到提交它的那個任務。API 的 metadata 欄位攜帶的是呼叫方自帶的資料；它並不承諾會抽取網頁標題、作者或發布日期。如果你的應用需要這些事實，就在一個合適的獨立步驟裡去收集和驗證它們。在讀取文字之前，先確認輸出是就近返回的，還是透過一個被引用的產物返回的；當你的流程需要稽核軌跡時，保留原始文件。文件轉換 API 為下一階段準備內容，而你的應用仍然負責把這份內容和它的來源關聯起來，並決定保留多久。

## 上線前測試

在把文件轉換 API 接進生產流程之前，先測試不止一個成功的小檔案。要包含一個需要非同步完成的輸入、一個不支援或損壞的檔案、一次結果混合的多來源請求，以及一個你的客戶端必須當作限額錯誤來處理的回應。驗證你自己的重試邏輯不會在部分失敗之後把已經成功的檔案再提交一次。把 API 憑證放在伺服器上，不要放進瀏覽器程式碼或公開示例裡。在評估下游檢索或模型行為之前，先針對有代表性的來源型別檢查實際的 Markdown。一個能正確處理傳輸錯誤的客戶端，仍然需要內容層面的檢查，才能證明產出的文件是有用的。

## FAQ

### 如何對文件轉換 API 驗證？

在帳號裡建立一個 API key，並在 `x-api-key` 請求標頭裡傳送它。key 只作用於你的帳號。

### 真實的轉換流程是怎樣的？

用 POST /v1/convert/{name} 傳送檔案、公開 URL 或文字。文件在等待視窗內完成時，Markdown 就隨同一個回應返回；否則你會收到 202 和一個可供等待的轉換，用 GET /v1/conversions/{id}?wait= 取結果。

### 轉換是同步的嗎？

預設在等待視窗內同步：POST /v1/convert/{name} 會等結果並直接返回，或在轉換無法及時完成時返回帶 Location 的 202。傳送 Prefer: respond-async 可以跳過等待。

### 可以訂閱哪些事件？

出站 webhook 支援 conversion.completed 和 conversion.failed，所以轉換一完成你就能立刻作出反應，而不必輪詢。

### 哪些套餐包含 API 訪問？

API 訪問在付費套餐中提供。目前套餐限額與 credit 見定價頁。

### API 用量如何計費？

API 轉換和網頁應用共用同一個 credit 餘額。標準頁和 OCR 頁都是每頁 1 credit。

### 去哪裡找 pdf to markdown api 或 url to markdown api？

那些說法是格式到達頁，並不代表另有主機。使用 /pdf-to-markdown 上關於 pdf to markdown api 的說明，以及 /url-to-markdown 上關於 url to markdown api 的說明，然後呼叫這裡記錄的同一組上傳和轉換端點。

### API key 的速率限制是多少？

請求按帳號限速：Lite 每分鐘 20 次、Pro 每分鐘 40 次、Max 每分鐘 60 次。

## Related

- [Introduction](https://markitdown.ai/docs)
- [PDF to Markdown Converter](https://markitdown.ai/pdf-to-markdown)
- [markitdown.ai pricing for document conversion](https://markitdown.ai/pricing)