API 快速入门:转换你的第一个文件
创建 API 密钥、发送文件、等待任务完成并下载结果,附可直接复制使用的请求示例。
简要回答
在“控制台 → API 与密钥”中创建密钥,然后发送 POST https://maxscanner.app/api/v1/jobs/ 请求,附带公开的文件 URL、文件名和目标格式。API 会立即返回 jobId;每隔几秒轮询一次 GET /api/v1/jobs/{jobId}/,直到 status 变为 "completed",然后在五分钟内下载 output.downloadUrl。
快速入门
- 1打开“控制台 → API 与密钥”,选择“创建 API 密钥”,勾选“处理文件”,然后复制密钥(它只显示一次)。
- 2将密钥保存在 MAXSCANNER_API_KEY 之类的环境变量中,切勿写进客户端代码。
- 3调用 POST /api/v1/jobs/,传入 url、filename 和 format。保存 202 响应中返回的 jobId。
- 4每隔 2–10 秒调用一次 GET /api/v1/jobs/{jobId}/,直到 status 变为 completed 或 failed。
- 5立即下载 output.downloadUrl:签名链接会在五分钟后过期。
开始之前
所有请求都发送到 https://maxscanner.app/api/v1/,并以 Bearer 令牌的形式携带密钥。请求 URL 以斜杠结尾:不带斜杠的 URL 会收到 308 重定向,大多数 HTTP 客户端会自动跟随,但直接带上斜杠可以省去一次往返。
免费套餐每天允许 10 次请求、每月 100 次,足以构建和测试一个集成。付费套餐改用每月积分计费;每个端点消耗 0 到 3 积分。
- 基础 URL:https://maxscanner.app/api/v1/
- 请求头:Authorization: Bearer <your key>
- 请求体:JSON,Content-Type: application/json
- 文件:通过 URL 导入或直接上传,最大 50 MB
将 Word 文件转换为 PDF
jobs 端点会根据输入和输出格式自动选择合适的处理器。传入公开 URL 时,服务器会在创建任务时自行下载文件(最大 50 MB,须在 30 秒内完成;不跟随重定向,请使用最终的文件链接);私有文件请使用直接上传,并改为传入 sourceKey(参见“文件与上传”指南)。添加 Idempotency-Key 请求头,确保重试的请求不会创建第二个任务。
curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-0001' \
-d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'等待结果
任务以异步方式处理,因此大文件不会一直占用你的 HTTP 连接。轮询状态 URL:从约 2 秒的间隔开始,逐步退避到 10 秒。小型 Office 文件通常在 20 秒内完成;1080p 视频可能需要几分钟。当 status 为 completed 时,output 会包含内容类型、以字节为单位的大小,以及一个带签名的 downloadUrl。
curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY"下一步
当需要处理的文件不止寥寥几个时,请改用 Webhook 代替轮询;阅读任务指南了解重试规则;再根据你的需求选择对应的功能指南:OCR、PDF 工具、图片、媒体,或运行已保存的工作流。
常见问题
需要安装 SDK 吗?
不需要。该 API 基于普通的 HTTPS 和 JSON,任何能发送 HTTP 请求的编程语言或无代码工具都可以使用。代码示例指南提供了完整的 Node.js、Python、PHP 和 cURL 版本。
下载链接的有效期是多久?
五分钟。如果链接已过期,再次请求任务状态即可获得新的链接。
有测试模式吗?
请使用免费套餐进行测试:它提供相同的端点,并限制每个账户每天 10 次、每月 100 次请求。