API 参考

Base URL：https://erased.ink/api/v1

所有成功响应均为 application/json。错误响应统一为 application/problem+json（RFC 7807），详见错误码。

`POST /uploads`

申请一个短时效的 R2 预签名 PUT URL。

请求体

{
  "filename": "photo.png",
  "content_type": "image/png",
  "size": 4823109
}

字段	类型	说明
`filename`	string	仅用于响应头；`object_key` 由服务端生成。
`content_type`	string	必须是 `image/png`、`image/jpeg`、`image/webp`、`image/avif`、`image/heic`、`image/heif`、`image/jxl` 之一。
`size`	integer	上限 10485760（10 MB）。

响应 200

{
  "upload_url": "https://...",
  "object_key": "in/2026-05-24/job_xxx.png",
  "expires_at": "2026-05-24T10:15:00Z"
}

必须在 expires_at 之前把文件 PUT 到 upload_url。

`POST /jobs`

创建一个处理任务。

请求体 —— 三种形态

POST /api/v1/jobs 支持三种请求体形态，按你手头有什么选一种：

Content-Type	必填字段	适用场景
`multipart/form-data`	`image`（文件，≤10MB）或 `object_key`； `mode`；`options`（JSON 字符串，可选）	一次调用完成上传 + 处理。`curl -F` 即可使用。
`application/json` + `image_base64`	`image_base64`（解码后 ≤1MB）、`content_type`、 `mode`	纯 JSON 工具链（Zapier、n8n）。小图。
`application/json` + `object_key`	`object_key`（来自 `POST /uploads`）、 `mode`	大文件 / 批量 —— 搭配预签名上传使用。

示例（object_key 形态）

{
  "object_key": "in/2026-05-24/job_xxx.png",
  "mode": "visible"
}

响应 —— 同步（`visible`、`metadata`）

{
  "id": "job_xxx",
  "status": "succeeded",
  "mode": "visible",
  "result_url": "https://...",
  "result_expires_at": "2026-05-25T10:00:00Z",
  "processing_ms": 412
}

响应 —— 异步（`invisible`、`all`）

{
  "id": "job_xxx",
  "status": "queued",
  "mode": "invisible",
  "poll_url": "/api/v1/jobs/job_xxx",
  "poll_after_ms": 2000
}

响应 —— `detect`（只读，不返回 `result_url`）

{
  "id": "job_xxx",
  "status": "succeeded",
  "mode": "detect",
  "processing_ms": 487,
  "report": {
    "visible": {
      "detected": true,
      "confidence": 0.87,
      "region": [1820, 120, 80, 80],
      "label": "Gemini sparkle"
    },
    "metadata": {
      "c2pa": { "present": true, "manifest": { "claim_generator": "Gemini ..." } },
      "exif_ai_tags": { "Software": "Gemini" },
      "png_text_chunks": null,
      "xmp_digital_source_type": null
    },
    "invisible_external": {
      "synthid": {
        "status": "unsupported_locally",
        "verify_url": "https://support.google.com/gemini/answer/16722517"
      }
    },
    "overall_assessment": "Likely AI-generated by Gemini. C2PA Content Credentials present."
  }
}

detect 永远不会写出新文件，原图保持不变。

`GET /jobs/:id`

轮询异步任务（同步任务在 KV 中保留约 30 分钟内也可读到该记录）。

响应 —— 仍在处理

{
  "id": "job_xxx",
  "status": "processing",
  "mode": "invisible",
  "poll_after_ms": 2000
}

响应 —— 成功

形如上面同步成功的响应。

响应 —— 失败

{
  "id": "job_xxx",
  "status": "failed",
  "mode": "invisible",
  "error_code": "pipeline_error",
  "error_message": "..."
}

`GET /clean` —— URL 入参，返回图片

一次同步调用：传入公网图片 URL，响应体直接是处理后的图片。适合 <img src="..." /> 内嵌和 CDN 缓存。

GET /api/v1/clean?image=<encoded-https-url>&mode=visible

→ 200 OK
   Content-Type: image/png
   Cache-Control: public, max-age=86400
   <bytes>

支持模式：visible、metadata、invisible、all。detect 返回 JSON 不返图，被拒绝。
鉴权：仅匿名 / Free。Pro 请走 POST /jobs。
体积上限：10MB（fetch 前用 HEAD 校验 Content-Length）。
错误：4xx/5xx 响应体始终是错误占位 PNG；真正的错误类型在 X-Error-Type header。
SSRF：只接受 https://；私网 IP 拒绝。

身份认证档位

匿名 —— 无需凭证，受每小时配额限制。
免费 —— 在 /zh/sign-in 用 Google 或邮箱魔法链接登录，享受更高的每小时配额，仍不发放 API key。
Pro（$9 / 月） —— 发放 API key，请以 Authorization: Bearer uk_... 传入。配额按月计算，每月含 100 缓冲 credits，detect 不限次。

速率限制

配额组	模式	匿名	免费	Pro
`light`	`visible`、`metadata`	30 / 时	100 / 时	5000 / 月
`heavy`	`invisible`、`all`	5 / 时	15 / 时	500 / 月
`uploads`	`POST /uploads`	60 / 时	200 / 时	不限
`detect`	`detect`	100 / 时	500 / 时	不限

heavy 在每小时限制之外还有每日 12 次上限（匿名与免费档）——匿名/免费按 ip+fp 计，登录用户按账号计。Pro 由月度配额管理。

超出配额时返回 429，并附带 Retry-After 头与 RFC 7807 错误体。失败的任务会自动退回对应配额。

API 参考

POST /uploads

请求体