REST API

图片、PDF 与文件处理 API

所有文件处理工具使用同一任务接口，通过 toolName 选择操作。下方有每个工具的参数和完整调用示例。

1. 创建 API Key

注册并验证邮箱，登录免费账号。
打开设置 → API 密钥（也可从左下角用户菜单进入），填写名称并创建。
完整密钥只显示一次，复制到服务端环境变量 API_KEY。遗失时删除旧密钥并重新创建。

Authorization: Bearer $API_KEY

上传、处理任务、任务查询、下载和规则管理需要有效 API Key 或已登录的网页会话。外部脚本、MCP 和自动化请用 API Key，勿将密钥写入前端代码。撤销后立即失效。

每个 Key 默认最多 120 次请求/分钟，包括轮询。处理额度按账号共享，换 Key 不会增加每日额度：免费账号默认每日 20 次任务，Pro 默认 100 次；实际配置见 GET /api/tools/entitlements。

2. 上传 → 创建任务 → 查询 → 下载

请求	输入 / 返回值
POST /api/tools/files	multipart 字段 file → data.file.id；每次上传一个文件
POST /api/tools/jobs	{toolName, input: {fileId / fileIds, execution: "async", …}} → data.job.id
GET /api/tools/jobs?id=JOB_ID	data.job.status + data.job.result
GET /api/tools/artifacts?id=ARTIFACT_ID&download=1	返回二进制文件（需鉴权），产物 ID 位于 data.job.result.data.artifact.id
DELETE /api/tools/jobs?id=JOB_ID	取消未完成任务；已终止任务可能返回 409

异步创建返回 HTTP 202（status: accepted），不表示处理完成。每隔 2 秒查询，直到 data.job.status 为 completed、failed、cancelled 或 expired。成功结果在 data.job.result.data；失败详情在 data.job.result.error.details。图片/PDF 检查只返回 JSON，不会产生下载文件。

处理模式 mode: must_pass 要求所有规则通过；best_effort 允许返回候选文件并附警告。rules 可内联，也可传 ruleId 引用保存的规则，两者不要同时提交。图片单文件工具每次传一个 fileId；多张图片需逐张创建任务。

上传文件和产物通常保留 24 小时，以 expiresAt 为准。任务创建可带 Idempotency-Key，网络重试时用相同 key 和相同请求体，避免重复处理。免费账号单次合计 25 MB、100 页、40 MP，多文件任务最多 10 个输入；Pro 多文件上限 100 个，单次处理引擎限制仍适用。

3. 按工具选择参数和示例

材料预检 · validate_file

POST /api/tools/validate

file 为已知属性，rules 为约束；不上传或读取文件。ruleId 使用已保存规则，需鉴权。

{
  "file": {
    "name": "example.png",
    "mimeType": "image/png",
    "bytes": 180000
  },
  "rules": {
    "maxBytes": 200000
  },
  "mode": "best_effort"
}

打开工具，按表单生成调用代码

图片压缩 · compress_image

POST /api/tools/jobs

fileId、targetBytes（bytes）、format、allowDownscale；可用 rules.maxBytes 校验输出。

{
  "toolName": "compress_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "jpeg",
    "targetBytes": 200000,
    "allowDownscale": true,
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片格式转换 · convert_image

POST /api/tools/jobs

fileId、format；可选 background（#RRGGBB）、dpi（仅 JPEG/PNG）。

{
  "toolName": "convert_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "webp",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片尺寸调整 · resize_image

POST /api/tools/jobs

fileId、width/height 至少一项（像素）、fit（contain/cover）、allowUpscale、format、dpi。

{
  "toolName": "resize_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "width": 1200,
    "fit": "contain",
    "allowUpscale": false,
    "format": "jpeg",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片裁剪 · crop_image

POST /api/tools/jobs

fileId、crop: {x,y,width,height}，均为像素；坐标从左上角开始。format 指定输出格式。

{
  "toolName": "crop_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "crop": {
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 200
    },
    "format": "png",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片背景去除 · remove_background

POST /api/tools/jobs

在线移除图片背景，保留主体并下载透明 PNG。直接在浏览器中处理，适合制作商品图片、人物照片和设计素材，无需手动描边或安装软件。

{
  "toolName": "remove_background",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片属性检查 · inspect_image

POST /api/tools/jobs

fileId；返回真实像素、DPI、EXIF/GPS 等属性，不生成下载文件。

{
  "toolName": "inspect_image",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

图片转 PDF · convert_image_to_pdf

POST /api/tools/jobs

fileIds 按页面顺序；pageSize（original/a4/letter）、pageOrientation（portrait/landscape）、marginPoints（0–144 pt）、pageDpi（36–600）。

{
  "toolName": "convert_image_to_pdf",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "pageSize": "a4",
    "pageOrientation": "portrait",
    "marginPoints": 24,
    "pageDpi": 150,
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

PDF 检查 · inspect_file

POST /api/tools/jobs

fileId；返回真实 PDF 页数、尺寸、字体、内嵌图片等，不生成下载文件。

{
  "toolName": "inspect_file",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

PDF 压缩 · compress_pdf

POST /api/tools/jobs

fileId；rules.maxBytes 指定目标大小（bytes）。严格模式不达标时任务失败并返回规则报告。

{
  "toolName": "compress_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rules": {
      "maxBytes": 200000
    },
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

PDF 合并 · merge_pdfs

POST /api/tools/jobs

fileIds，至少 2 个，按数组顺序合并；可选 rules 校验合并结果。

{
  "toolName": "merge_pdfs",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

PDF 拆分与选页 · split_pdf

POST /api/tools/jobs

fileId、pageRange（例如 1-3,5,2）或 pages 数组；页码从 1 开始，可重新排序和重复。

{
  "toolName": "split_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "pageRange": "1-2",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

PDF 旋转 · rotate_pdf

POST /api/tools/jobs

fileId、rotation（90/180/270）；可选 pageRange/pages，不填则旋转全部页面。

{
  "toolName": "rotate_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rotation": 90,
    "pageRange": "1",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

材料打包 · create_submission_package

POST /api/tools/jobs

fileIds、packageName、namingTemplate；免费模板为 {index}-{name}.{ext}，自定义模板需 Pro。ZIP 含文件、清单和逐文件报告。

{
  "toolName": "create_submission_package",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "packageName": "submission-package",
    "namingTemplate": "{index}-{name}.{ext}",
    "execution": "async"
  }
}

打开工具，按表单生成调用代码

错误、权限与集成

401：缺少、无效或已撤销的密钥；403：账号或 Key 没有权限；429 / rate_limited：请求频率或每日任务额度耗尽。仅在允许重试时退避重试。invalid_input：检查参数；subscription_required：请求超出方案能力；processing_failed / 规则失败：查看 error.details 中的报告。异步失败通过任务状态返回，轮询 HTTP 200 不代表处理成功。

工具目录、OpenAPI 和只校验声明属性的 /api/tools/validate 可公开访问；网页游客处理使用另一个受会话及 IP 配额限制的入口，不提供匿名自动化凭据。账号间的文件、任务、规则和产物互相隔离。

规则管理使用 /api/tools/rules（GET/POST/DELETE），任务历史使用 GET /api/tools/jobs。OpenAPI 包含完整 schema；MCP 与 REST 共用工具和账号额度。Pro 购买与充值尚未开放。

OpenAPI 3.1 MCP 机器可读工具目录

# CLI: ATTACHREADY_BASE_URL + ATTACHREADY_API_KEY
node scripts/tools-cli.mjs run convert_image --input '{"fileId":"FILE_ID","format":"webp"}' --wait