HTTP API
在脚本、自动化流程或你自己的程序里调用转换：上传文件，等待结果，下载 PDF 和 Word。不需要注册，也不需要密钥。
怎么用
- 1
提交
用 POST 上传文档（或粘贴的 Markdown、GitHub 链接），加上 ?wait=50 等待结果。
- 2
等待
一般文档几秒内完成；50 秒内没完成会先返回任务编号，再用 GET 继续等。
- 3
下载
结果里的 files 列出每个文件的下载地址，2 小时内有效。
无需密钥
直接调用，和网页使用同一套免费额度。
和网页同样的质量
风格、表格、公式、参考文献、Word 模板全部可用。
多种输入
Markdown（含图片文件夹或 .zip）、Word、LaTeX、PDF、GitHub 链接。
结果自动删除
转换结果 2 小时后自动删除，也可以随时用 DELETE 立即删除。
快速开始
把 report.md 转成 PDF 和 Word。完成时返回 200，files 里是下载地址：
curl -F "file=@report.md" -F 'options={"formats":["pdf","docx"]}' \
"https://mdpdfword.com/api/v1/jobs?wait=50"如果返回的是 202（还在排队或转换），用任务编号继续等待：
curl "https://mdpdfword.com/api/v1/jobs/JOB_ID?wait=50"接口
| 请求 | 作用 |
|---|---|
POST /api/v1/jobs?wait=50 | 提交转换，最多等待 wait 秒（上限 50）。完成返回 200，否则返回 202 和任务编号。 |
GET /api/v1/jobs/{job_id}?wait=50 | 查询任务；带 wait 时一直等到完成或超时。 |
DELETE /api/v1/jobs/{job_id} | 立即删除这次的结果文件。 |
GET /api/v1/info | 可用的风格、各项限额和当前排队情况。 |
提交的字段（multipart/form-data）
| 字段 | 作用 |
|---|---|
file | 要转换的文件，可以重复多次：文档和它用到的图片、.bib 等。也可以是一个 .zip。 |
paths | 可选：与 file 顺序对应的相对路径列表（JSON），用于保留文件夹结构，例如 ["report.md", "images/a.png"]。 |
markdown | 直接提交 Markdown 文字（代替 file）。 |
url | 公开 GitHub 仓库里的 Markdown 文件链接（代替 file），图片会一起取回。 |
template | 可选：一份 .docx 模板，结果沿用它的页面、字体、样式、页眉页脚。 |
options | 转换选项（JSON 对象），见下表。 |
转换选项（options）
| 选项 | 作用 |
|---|---|
formats | ["pdf", "docx"]（默认）、["pdf"] 或 ["docx"]；Word、LaTeX、PDF 输入还可以用 ["markdown"] 只要可编辑的 Markdown。 |
theme | 风格名称，默认 business；可选值见 /api/v1/info。 |
toc | true：生成目录。 |
number_sections | true / false：标题是否自动编号。 |
docx_fonts | windows（默认）或 mac：Word 里使用的中文字体名称。 |
main | 上传多个文档时，指定要转换的那一份（相对路径）。 |
filename | 提交 markdown 文字时的文件名。 |
track_changes | Word 输入：accept（默认）或 reject 修订。 |
keep_source_format | Word、LaTeX 输入：false 表示改用所选风格的格式。 |
pdf_ocr | PDF 输入：true 表示同意把 PDF 发给 SoMark 做增强识别（见下方隐私说明）。不写就不会发送。 |
返回结果
status 依次为 queued（排队）、running（转换中）、done（完成）或 error（失败，error 和 code 说明原因）。warnings 列出需要注意的地方，例如缺少的图片。
{
"ok": true,
"job_id": "Vq3…",
"status": "done",
"version": 3,
"main": "report.md",
"elapsed": 4.2,
"files": [
{
"format": "pdf",
"name": "report.pdf",
"size": 182340,
"url": "https://mdpdfword.com/files/results/…/report.pdf",
"file_id": "…"
},
{
"format": "docx",
"name": "report.docx",
"size": 48211,
"url": "https://mdpdfword.com/files/results/…/report.docx",
"file_id": "…"
}
],
"warnings": [],
"pdf_pages": 3,
"expires_in_minutes": 120
}Python 示例
import json
import requests
API = "https://mdpdfword.com/api/v1/jobs"
with open("report.md", "rb") as f:
job = requests.post(API, params={"wait": 50}, files={"file": f},
data={"options": json.dumps({"formats": ["pdf", "docx"]})},
timeout=70).json()
while job.get("status") in ("queued", "running"):
job = requests.get(f"{API}/{job['job_id']}", params={"wait": 50}, timeout=70).json()
if not job.get("ok"):
raise SystemExit(f"{job.get('code')}: {job.get('error')}")
for out in job["files"]:
with open(out["name"], "wb") as f:
f.write(requests.get(out["url"], timeout=120).content)错误代码
| code | 作用 |
|---|---|
bad_request / no_document | 400：参数不对，或没有找到要转换的文档。 |
file_too_big / total_too_big / too_many_files | 413：超过文件大小或数量限制。 |
too_many_active / rate_hour / rate_limited | 429：同时提交太多或超过每小时额度；请稍后重试（有 Retry-After 头时，按它给出的秒数等待）。 |
busy / storage_full | 503：服务器繁忙，过几分钟再试。 |
not_found | 404：任务不存在或已过期。 |
pdf_scanned | 任务失败：这是扫描件，需要设置 pdf_ocr: true 才能识别。 |
timeout / conversion_failed | 任务失败：文档太复杂或内容有误，error 里有说明。 |
限额
和网页相同：每个来源 IP 同时最多 2 份、每小时 30 份；单个文件 20 MB，总共 60 MB、300 个文件；单份最长转换 5 分钟；结果保存 2 小时。
本服务运行在一台机器上。为了不让网页上的用户排在脚本后面，API 请求共用其中一部分转换名额，繁忙时排队可能更久。请按顺序提交，不要并发批量调用。
隐私
上传的文件只用于这次转换，结果 2 小时后自动删除。PDF 默认只在本站服务器读取；只有请求里写明 "pdf_ocr": true，PDF 才会发送给第三方 SoMark 做增强识别，内容敏感的文件请不要设置。详见隐私政策。 隐私政策
常见问题
需要注册或 API 密钥吗？
不需要。直接调用，和网页使用同一套免费额度。
可以在网页前端（浏览器 JavaScript）里直接调用吗？
不可以。为了防止其他网站把访客的文件转到这里，接口不允许跨站调用。请从服务器端或脚本调用。
和 MCP 有什么区别？
MCP 给 Claude Code、Codex 等 AI 助手用；HTTP API 给脚本和程序用。转换质量和额度相同。
接口会变吗？
/api/v1 是稳定版本：以后只会增加字段，不会改变已有字段的含义。网页内部用的 /api/jobs 不保证稳定，请不要依赖。