版本 v1 · REST API
API 文档
Base URL: https://miniaipdf.com/api/v1
简介
MiniAIPDF REST API 提供完整的 PDF 处理能力，包括压缩、AI 结构化提取、文档对比、电子签名和异步批量处理。 所有接口返回 JSON（PDF 下载类除外），使用标准 HTTP 状态码。
使用前请先在 API Keys 页面 创建密钥。 免费套餐每月 100 次调用，无需信用卡。
认证
所有请求需在 Header 中携带 Bearer token：
HTTP
Authorization: Bearer mak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API Key 以 mak_ 开头，创建后仅显示一次完整密钥，请立即保存。
⚠️ 请勿将 API Key 提交到 Git 或暴露在前端代码中。泄露后请立即在 API Keys 页面删除并重新创建。
配额与限速
套餐月调用量速率限制价格
Free100 次10 次/分$0
Growth1,000 次30 次/分$25/月
Scale10,000 次100 次/分$100/月
Enterprise无限500 次/分联系我们
超出月配额返回 429，响应体含 upgradeUrl。 超出速率限制返回 429 并附 Retry-After header。 查看详细定价 →
接口列表
POST
/api/v1/compress压缩 PDF 文件，返回压缩后的 PDF 二进制
POST
/api/v1/extract从 PDF 中提取结构化 JSON 数据（AI）
POST
/api/v1/compare对比两份 PDF，返回差异报告（AI）
POST
/api/v1/sign在 PDF 最后一页叠加签名图片
GET
/api/v1/info查询当前 Key 的用量信息与套餐状态
POST
/api/v1/jobs创建异步任务（extract / summarize / compare）
GET
/api/v1/jobs/:id轮询异步任务状态与结果
POST /api/v1/compress
上传 PDF，返回压缩后的二进制 PDF 流。
字段类型说明必填
fileFilePDF 文件（multipart/form-data）必填cURL
curl -X POST https://miniaipdf.com/api/v1/compress \ -H "Authorization: Bearer mak_..." \ -F "file=@document.pdf" \ -o compressed.pdf
响应 Headers：X-Original-Size、X-Compressed-Size
POST /api/v1/extract
用 Claude AI 从 PDF 中提取结构化字段。传入一个 JSON schema（字段名 → 类型）， 返回对应的 JSON 对象。适合发票、合同、表单等场景。
字段类型说明必填
fileFilePDF 文件必填schemastringJSON 字符串，如 {"total":"number","date":"string"}必填promptstring额外提取说明（如"金额单位为人民币"）可选cURL
curl -X POST https://miniaipdf.com/api/v1/extract \
-H "Authorization: Bearer mak_..." \
-F "file=@invoice.pdf" \
-F 'schema={"invoice_no":"string","amount":"number","date":"string","vendor":"string"}'响应示例
{
"data": {
"invoice_no": "INV-2024-0042",
"amount": 12800.00,
"date": "2024-03-15",
"vendor": "Acme Corp Ltd."
},
"meta": {
"fileName": "invoice.pdf",
"pages": 2,
"chars": 1842,
"truncated": false,
"model": "claude-haiku-4-5",
"durationMs": 623
}
}支持类型：string number boolean array integer。未找到的字段返回 null。
POST /api/v1/compare
对比两份 PDF 的内容差异，AI 生成结构化差异报告（Markdown 格式）。
字段类型说明必填
fileAFile第一份 PDF（原版）必填fileBFile第二份 PDF（修订版）必填cURL
curl -X POST https://miniaipdf.com/api/v1/compare \ -H "Authorization: Bearer mak_..." \ -F "fileA=@contract_v1.pdf" \ -F "fileB=@contract_v2.pdf"
响应示例
{
"report": "## 总体评估\n修订版新增了第5条违约责任条款...",
"meta": {
"fileA": "contract_v1.pdf",
"fileB": "contract_v2.pdf",
"charsA": 4200,
"charsB": 4850,
"truncated": false
}
}POST /api/v1/sign
在 PDF 最后一页的指定位置叠加签名图片，返回签名后的 PDF。
字段类型说明必填
pdfFilePDF 文件必填signatureFile签名图片（PNG / JPG）必填positionstring"bottom-right" | "bottom-left" | "top-right" | "top-left" | "x,y,w,h"可选cURL
curl -X POST https://miniaipdf.com/api/v1/sign \ -H "Authorization: Bearer mak_..." \ -F "pdf=@contract.pdf" \ -F "signature=@my_signature.png" \ -F "position=bottom-right" \ -o signed_contract.pdf
GET /api/v1/info
返回当前 Key 对应用户的用量统计与套餐信息。
cURL
curl https://miniaipdf.com/api/v1/info \ -H "Authorization: Bearer mak_..."
响应示例
{
"userId": "user_xxxxxxxx",
"plan": "growth",
"usage": {
"apiCallsThisMonth": 87,
"monthlyLimit": 1000,
"remaining": 913,
"uploadsToday": 3,
"uploadsTotal": 124
},
"version": "v1"
}异步任务 — /api/v1/jobs
对于大文件或批量场景，使用异步任务接口：提交任务后立即返回 jobId， 轮询 GET /api/v1/jobs/:id 获取结果。
POST /api/v1/jobs — 创建任务
字段类型说明必填
typestring"extract" | "summarize" | "compare"必填fileFilePDF 文件（extract / summarize 时必填）必填schemastring字段 schema JSON（type=extract 时必填）可选fileAFile第一份 PDF（type=compare 时必填）可选fileBFile第二份 PDF（type=compare 时必填）可选响应示例
{
"jobId": "a1b2c3d4-...",
"type": "extract",
"status": "pending",
"pollUrl": "/api/v1/jobs/a1b2c3d4-...",
"createdAt": "2024-03-15T10:00:00.000Z"
}GET /api/v1/jobs/:id — 轮询状态
JavaScript
// Poll until done
async function waitForJob(jobId) {
while (true) {
const res = await fetch(`https://miniaipdf.com/api/v1/jobs/${jobId}`, {
headers: { Authorization: 'Bearer mak_...' }
});
const job = await res.json();
if (job.status === 'done') return job.result;
if (job.status === 'failed') throw new Error(job.error);
await new Promise(r => setTimeout(r, 2000)); // wait 2s
}
}status含义
pending已创建，等待处理processing正在处理中done处理完成，result 字段包含结果failed处理失败，error 字段包含错误信息通用响应 Headers
Header说明
X-RateLimit-Plan当前套餐名称（free / growth / scale / enterprise）X-Usage-This-Month本月已调用次数X-Usage-Limit本月调用上限（unlimited 套餐无此 header）X-Usage-Remaining本月剩余调用次数X-Response-Time服务端处理耗时（如 "423ms"）Retry-After速率限制时返回，值为等待秒数错误码
状态码场景说明
400Bad Request请求参数错误（缺少必填字段、格式不正确）401UnauthorizedAPI Key 无效、缺失或格式错误403Forbidden无权访问该资源（如访问他人 job）404Not Found资源不存在（如无效 jobId）422UnprocessablePDF 无法处理（损坏、无文本、加密）429Rate Limited超出速率限制或月配额，见响应体 upgradeUrl502AI ErrorAI 服务暂时不可用，请稍后重试500Server Error服务端内部错误所有错误均返回：{ "error": "描述信息" }
SDK & 代码示例
官方 SDK 支持 Node.js 和 Python，零依赖，开箱即用。
🟩⬇🐍⬇
Node.js SDKv1.0.0
no npm needed — download & require
Python SDKv1.0.0
no pip needed — download & import
Node.js — 5 行提取发票
JavaScript
const { MiniAIPDF } = require('./miniaipdf');
const client = new MiniAIPDF('mak_your_key_here');
const { data } = await client.extract(fs.readFileSync('./invoice.pdf'), 'invoice.pdf', {
invoice_no: 'string', amount: 'number', date: 'string', vendor: 'string',
});
console.log(data); // { invoice_no: 'INV-001', amount: 12800, ... }Python — 异步大文件处理
Python
from miniaipdf import MiniAIPDF
client = MiniAIPDF("mak_your_key_here")
with open("report.pdf", "rb") as f:
job = client.jobs.create("extract", f.read(), "report.pdf",
schema={"title": "string", "total": "number"})
result = client.jobs.wait(job["jobId"]) # 自动轮询，最长等 5 分钟
print(result)需要帮助？
发邮件到 api@miniaipdf.com， 或查看 定价方案以升级获取更高配额。