---
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)