跳到主要内容

查找下一个工具

文档/入门/API 快速入门:转换你的第一个文件
入门

API 快速入门:转换你的第一个文件

创建 API 密钥、发送文件、等待任务完成并下载结果,附可直接复制使用的请求示例。

简要回答

在“控制台 → API 与密钥”中创建密钥,然后发送 POST https://maxscanner.app/api/v1/jobs/ 请求,附带公开的文件 URL、文件名和目标格式。API 会立即返回 jobId;每隔几秒轮询一次 GET /api/v1/jobs/{jobId}/,直到 status 变为 "completed",然后在五分钟内下载 output.downloadUrl。

快速入门

  1. 1打开“控制台 → API 与密钥”,选择“创建 API 密钥”,勾选“处理文件”,然后复制密钥(它只显示一次)。
  2. 2将密钥保存在 MAXSCANNER_API_KEY 之类的环境变量中,切勿写进客户端代码。
  3. 3调用 POST /api/v1/jobs/,传入 url、filename 和 format。保存 202 响应中返回的 jobId。
  4. 4每隔 2–10 秒调用一次 GET /api/v1/jobs/{jobId}/,直到 status 变为 completed 或 failed。
  5. 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 次请求。

相关指南