API 扫描

API 扫描通过接口调用把 PDF 变成逼真的扫描件,适合自动化流程和应用集成。创建任务、上传 PDF、轮询或等回调三步即可接入,色彩空间、分辨率、旋转、模糊、噪点、亮度、对比度和边框都可自定义,任何能发 HTTP 请求的环境或语言都能调用。

调用流程

  1. 创建任务

    POST /v1/scan-jobs

    带上 config 与可选的 webhookUrl,拿到 jobID 和预签名 uploadURL。

  2. 上传 PDF

    PUT {uploadURL}

    把文件直接 PUT 到上一步返回的 S3 预签名地址,无需再带 Token。

  3. 取回扫描件

    GET /v1/scan-jobs/{jobID}

    轮询状态或等 webhook 回调,completed 后用 downloadURL 下载。

适合这些场景

后端批量出件

合同、发票、报表在服务端生成后直接过一遍扫描,不用人工再走一次网页。

接进现有系统

CRM、ERP、工单系统里加一个「导出扫描件」,走接口调用即可。

自动化流水线

CI 或 n8n、Zapier 这类平台按事件触发,完成后用 webhook 通知下一步。

大量文件排队

任务式接口,创建后各自异步处理,可按 status、createdAfter 查询进度。

支持的语言与环境

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURL命令行 / CI
更多任何 HTTP 客户端

接口是标准的 HTTP + JSON,任何能发请求的语言或自动化平台都能接入。

代码示例

API Bearer Token

Token 与账号绑定,可随时重新生成。API 扫描需要专业版账号:没带有效 Token 时接口返回 401,账号没有专业版角色时返回 403。

试一试

调整参数,请求体会跟着一起变,然后依次调用三个接口。

扫描参数

试跑会用你的 Token 真实调用接口,需要专业版账号;参数和请求体可以随便看。

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

扫描任务信息

示例
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

接口参考

方法路径说明
POST/v1/scan-jobs创建扫描任务。带上 config 与可选的 webhookUrl,返回 jobID、status 为 created 的任务对象和预签名 uploadURL。
PUT{uploadURL}上一步返回的 S3 预签名地址,不在 api.lookscanned.io 上上传源 PDF,带 Content-Type: application/pdf 与 Content-Length;地址自带签名,不要再加 Authorization 头。
GET/v1/scan-jobs/{jobID}查询单个任务,用来轮询进度;created 时带 uploadURL,completed 时带 downloadURL。
GET/v1/scan-jobs列出自己的任务,可按 jobID、status、createdAfter 过滤。
状态createdprocessingcompletedfailed
  • 401 未带有效 Token
  • 403 账号不是专业版
  • 404 任务不存在

请求体参数

字段类型默认说明
webhookUrlstring · —任务完成后回调一次,这样就不必自己轮询。
config.colorspace'gray' | 'sRGB' · graygray输出图像的色彩空间,gray 即黑白扫描件。
config.resolutionnumber · 7272输出图像的分辨率,单位 DPI。
config.rotatenumber · —整份文档的旋转角度(度)。
config.rotate_varnumber · —随机旋转的浮动范围(度),用来模拟纸张放歪。
config.blurnumber · 00模糊强度。
config.noisenumber · 00噪点强度。
config.brightnessnumber · 11亮度,1 表示不改变。
config.contrastnumber · 11对比度,1 表示不改变。
config.borderboolean · falsefalse是否给页面加上扫描边框。
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpeg页面渲染成图片时使用的格式。

所有字段都可省略;「试一试」的初始值(分辨率 150、旋转 1、亮度与对比度 1.3)是网页端的推荐组合,不是接口默认值。

任务对象里要留意的字段

status
created / processing / completed / failed,决定下面两个地址是否出现。
uploadURL
仅 created 时给出,预签名上传地址,有时效。
downloadURL
仅 completed 时给出,预签名下载地址,有时效。
inputUploadedAt / completedAt
源文件上传完成、任务完成的时间戳,可用来算耗时。

常见问题

API 扫描需要专业版吗?

需要。没带有效 Token 时接口返回 401,账号没有专业版角色时返回 403;升级并登录后即可在本页获取 Token。

怎么知道任务什么时候完成?

两种方式:轮询 GET /v1/scan-jobs/{jobID},或在创建任务时传 webhookUrl,由服务在完成后回调一次。

结果和网页端的扫描一样吗?

一样。两边用的是同一套扫描效果实现,config 里的色彩空间、分辨率、旋转、模糊、噪点、亮度、对比度和边框对应网页端同名选项,相同参数得到一致的输出;区别只在处理位置——网页端在本地,API 在远程服务。

上传和下载地址能存起来复用吗?

不建议。uploadURL 与 downloadURL 都是有时效的预签名地址,过期后需要再查一次任务重新获取。

任务处理要多久?

取决于页数和分辨率。多数几页的文档在数秒内完成;分辨率越高、页数越多耗时越长。可以用 inputUploadedAt 和 completedAt 的差值统计实际耗时。

任务失败了怎么办?

状态会变成 failed。常见原因是上传的文件不是有效 PDF、加密受限或上传中断。确认文件可正常打开后重新创建一个任务即可。

可以查历史任务吗?

可以。GET /v1/scan-jobs 会列出你自己的任务,支持按 jobID、status、createdAfter 过滤,用来做对账或补下载。