Developers

API 文档

使用域名 api.markitdown.io 调用转换服务。注册后在账户中心创建 API Key。

管理 API Keys 注册领取每日积分

转换计费

每次转换消耗 1 积分

网页额度

注册用户每日赠送 100 积分，积分当日有效，不可累计到次日

API 额度

API 每日最多调用 10 次，每次同样消耗 1 积分

Base URL

text

https://api.markitdown.io/api/v1

下文路径均相对于 https://api.markitdown.io/api/v1。也可使用等价前缀 /api/convert/*（无版本号）。

鉴权

在请求头携带 API Key（二选一）：

http

Authorization: Bearer mk_live_xxxxxxxx
# 或
X-API-Key: mk_live_xxxxxxxx

Key 在 Account → API Keys 创建
API 每日上限 10 次；超出返回 429
网页转换每日 100 积分，与 API 次数分开计数，均不跨日累计

文件 → Markdown

POST /convert/to-markdown消耗 1 积分

bash

curl -X POST "https://api.markitdown.io/api/v1/convert/to-markdown" \
  -H "Authorization: Bearer mk_live_xxxxxxxx" \
  -F "file=@./document.pdf"

响应示例

json

{
  "success": true,
  "title": "document",
  "filename": "document.pdf",
  "markdown": "# Hello\n\n...",
  "download_url": "/api/download/xxxx.md",
  "file_size": 1234,
  "source_type": "input"
}

Markdown → 文件

POST /convert/from-markdown消耗 1 积分

bash

curl -X POST "https://api.markitdown.io/api/v1/convert/from-markdown" \
  -H "Authorization: Bearer mk_live_xxxxxxxx" \
  -F "markdown=# Hello MakeItDown" \
  -F "output_format=pdf" \
  -F "filename=hello"

常用 output_format：pdfdocxhtmlpptxepub

json

{
  "success": true,
  "filename": "hello_a1b2c3d4.pdf",
  "download_url": "/api/download/hello_a1b2c3d4.pdf",
  "file_size": 58081
}

下载结果

GET /download/{filename}

bash

curl -L "https://api.markitdown.io/api/download/hello_a1b2c3d4.pdf" \
  -H "Authorization: Bearer mk_live_xxxxxxxx" \
  -o hello.pdf

支持格式

GET /formats

bash

curl "https://api.markitdown.io/api/formats"

健康检查

bash

curl "https://api.markitdown.io/api/health"

JavaScript 示例

javascript

const form = new FormData()
form.append("file", fileInput.files[0])

const res = await fetch("https://api.markitdown.io/api/v1/convert/to-markdown", {
  method: "POST",
  headers: {
    Authorization: "Bearer mk_live_xxxxxxxx",
  },
  body: form,
})

const data = await res.json()
if (!res.ok) throw new Error(data.detail || "转换失败")
console.log(data.markdown)

Python 示例

python

import requests

url = "https://api.markitdown.io/api/v1/convert/to-markdown"
headers = {"Authorization": "Bearer mk_live_xxxxxxxx"}

with open("document.pdf", "rb") as f:
    r = requests.post(url, headers=headers, files={"file": f})

r.raise_for_status()
print(r.json()["markdown"])

错误码

状态码	含义
400	不支持的格式或转换失败
401	缺少或无效的 API Key
413	文件超过大小限制
429	今日 API 次数或积分已用尽
500	服务内部错误

积分与额度规则

注册用户每日获赠 100 积分，用于网页转换台；当日未用完清零，不可累计。
任意一次成功转换（网页或 API）消耗 1 积分。
API 额外限制：每个账号每日最多 10 次调用（与网页 100 次额度独立）。
额度按 UTC+0 或服务器日界重置；具体以账户中心显示为准。