POST
文件上传转换
/convert
✅ 可用
本地文件上传转换（multipart/form-data，字段名 file）：PDF / Word / PPT / Excel 与图片 → 结构干净的 Markdown
快速开始
请求头携带
Authorization: Bearer <你的API-Key>（兼容 X-API-Key 请求头）完成鉴权计费。以 multipart/form-data 上传本地文件（字段名 file），转换后同步返回 Markdown 纯文本。支持 PDF / Word / PPT / Excel 与图片（jpg / jpeg / png / bmp / webp，发票 / 身份证 / 订单等票据识别），旧版 Office（.doc / .ppt / .xls）自动兼容；CSV / HTML / JSON 等另供私有化 / 管理通道。远程文件转换请切换到「远程文件」接口。
三步接入
2
上传文件
以 multipart/form-data 上传到 POST /convert（字段名 file）
3
获取 Markdown
接口同步返回 Markdown 纯文本（text/plain）
Try it now
接入示例
选择你喜欢的语言，复制代码即可运行
cURL
Python
Node.js
Vue 3
Java
Go
Rust
convert.sh
将 YOUR_API_KEY 替换为你在控制台创建的 API-Key，选择语言即可复制运行。
接口参考
请求地址
POST https://note.prowyg.com/convert
（私有化部署时替换为你的服务地址）
请求头
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API-Key>（兼容 X-API-Key 请求头） |
Content-Type | 是 | multipart/form-data（curl 的 -F 会自动设置） |
请求参数
| 参数 | 位置 | 说明 |
|---|---|---|
file | form-data | 要转换的文件：PDF / Word / PPT / Excel 与图片；旧版 Office（.doc / .ppt / .xls）自动兼容 |
cols | query | 仅 CSV（私有化 / 管理通道）：逗号分隔的列名子集，如 id,total_amount |
max_rows | query | 仅 CSV（私有化 / 管理通道）：最多保留的数据行数，如 100 |
响应
成功返回 200，响应体为 Markdown 纯文本（text/plain），保留标题、列表与表格结构。
计费规则（两个接口通用）
统一按 积分 计费：1 页转换 = 1 积分；图片按张计 1 积分。转换前先扣减，失败自动退还。下表的文件类型为 API-Key 计费支持的格式；CSV / HTML / JSON 等更多格式仅在私有化 / 管理通道开放。
| 文件类型 | 扩展名 | 计价方式 |
|---|---|---|
.pdf | 按真实页数 | |
| PPT | .pptx / .ppt | 按幻灯片张数 |
| Word | .docx / .doc | 约 1000 字折算 1 页 |
| Excel | .xlsx / .xls | 约 100 有数据行折算 1 页 |
| 图片 | .jpg / .jpeg / .png / .bmp / .webp | 每张 1 积分 |
新用户注册即送 100 积分；积分可在「控制台」充值，后续亦可抵扣 AI 精华（1000 Token = 1 积分）。
错误码（两个接口通用）
| 状态码 | 含义 | 处理建议 |
|---|---|---|
200 | 转换成功 | 响应体即 Markdown 文本 |
400 | 参数错误 | 检查 file 字段，或 JSON 里的 url 地址 |
401 | Key 无效 | 检查 Authorization / X-API-Key 请求头 |
402 | 积分不足 | 前往「控制台」充值 |
403 | API-Key 不可用 | Key 被禁用或异常，请联系客服 |
413 | 超过上传大小上限 | 压缩或拆分文件 |
415 | 格式不支持 | 确认文件类型在支持列表内 |
500 | 转换失败 | 本次已自动退还积分，可重试 |
502 | 远程下载失败 | 检查 /convert/url 的 url 是否可访问 |
503 | 服务暂不可用 | 计费服务异常，稍后重试或联系客服 |
使用建议
上传的临时文件默认保留 24 小时内自动清理。
纯扫描图片型 PDF（无文字层）建议先转成图片再上传识别。
POST
远程文件转换
/convert/url
✅ 可用
远程文件转换（JSON 请求体，服务端代下载）：传入 url 即可转换 http(s) 链接指向的文件
快速开始
以
application/json 请求 POST /convert/url，请求体 {"url": "http(s)://…"}；服务端代下载后按与「文件上传」相同的引擎转换，同步返回 Markdown 纯文本（text/plain）。鉴权与计费同 POST /convert（Authorization: Bearer <API-Key>，兼容 X-API-Key）。
示例
convert.sh
# 远程文件（JSON 请求体，服务端代下载）
curl -X POST "https://note.prowyg.com/convert/url" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/report.pdf"}' \
-o report.md接口参考
请求地址
POST https://note.prowyg.com/convert/url
（私有化部署时替换为你的服务地址）
请求头
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API-Key>（兼容 X-API-Key 请求头） |
Content-Type | 是 | application/json |
请求参数
| 参数 | 位置 | 说明 |
|---|---|---|
url | JSON body | 远程文件地址（http / https）；无扩展名时按响应 Content-Type 兜底判断类型 |
cols | query | 仅 CSV（私有化 / 管理通道）：逗号分隔的列名子集 |
max_rows | query | 仅 CSV（私有化 / 管理通道）：最多保留的数据行数 |
响应
成功返回 200，响应体为 Markdown 纯文本（text/plain）。
常见失败
目标地址不可访问或下载超时返回 502；非 http(s) 链接返回 400。
支持的格式、计费规则与完整错误码同「文件上传」接口。