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": "..."
}

身份认证档位

detect 是唯一无需账号即可使用的模式（未登录 100 次/时）。所有去水印模式均需至少注册免费账号。

免费（已登录） —— 在 /zh/sign-in 用 Google 或邮箱魔法链接登录，解锁所有去水印模式，不发放 API key。
Pro（$9 / 月） —— 发放 API key，请以 Authorization: Bearer uk_... 传入。配额按月计算，每月含 100 缓冲 credits，detect 不限次。

速率限制

detect 是唯一可在未登录状态下使用的模式：未认证 100 次/时，免费账号 500 次/时。其他所有模式需登录免费账号或 Pro。

配额组	模式	免费（已登录）	Pro
`light`	`visible`、`metadata`	10 / 天	5000 / 月
`heavy`	`invisible`、`all`	3 / 天	500 / 月
`uploads`	`POST /uploads`	200 / 时	不限
`detect`	`detect`	500 / 时	不限

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