API 文档

快速开始

第一次请求只需要 input.image_base64。省略 input.output 时，继续返回兼容旧客户端的原尺寸透明结果。

curl --request POST   --url https://removezero.com/api/v1/remove-background   --header "Authorization: Bearer ${REMOVEZERO_API_KEY}"   --header "Content-Type: application/json"   --header "Idempotency-Key: image-2026-08-28-0001"   --data '{"input":{"image_base64":"BASE64_IMAGE_DATA"}}'

使用 Bearer Key 验证

在个人中心创建 API Key，并在每次请求的 Authorization 请求头中发送。

Authorization: Bearer rz_live_your_api_key

• 把 Key 保存在服务器环境变量或密钥管理工具中。
• 不要把 Key 放进浏览器代码、移动端应用包、扩展、URL、公开仓库或日志。
• 条件允许时，为不同服务或环境使用不同 Key。
• Key 可能泄露时立即撤销并更换。

只从服务器调用

推荐路径是：浏览器或客户端 → 你的服务器 → RemoveZero API。Bearer Key 可以授权付费处理，公开客户端无法安全保存它。服务端付费请求必须省略 Origin 请求头。

发送移除背景请求

从服务器发送一份严格校验的 JSON 请求。必需请求头会在预留积分和处理图片之前完成验证。

POST https://removezero.com/api/v1/remove-background
Authorization: Bearer rz_live_your_api_key
Content-Type: application/json
Idempotency-Key: order-2026-08-25-0001

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA"
  }
}

• Content-Type 必须是 application/json，可以带 charset 参数。
• Content-Encoding 必须省略或为 identity；不接受压缩请求体。
• 不要发送 Origin 请求头。
• Idempotency-Key 长度为 1–128，只能使用字母、数字、句点、下划线、冒号和连字符。
• image_base64 必须是标准 Base64 图片字节，不能带 data:image/... 前缀。

自定义输出

output 对象可省略。它只在一次抠图推理后调整画布，因此整个请求仍只消耗 1 积分。

{
  "input": {
    "image_base64": "BASE64_IMAGE_DATA",
    "output": {
      "format": "webp",
      "background": "#ffffff",
      "width": 1600,
      "height": 1600,
      "padding_ratio": 0.08
    }
  }
}

固定 contain + center 规则

fit 不是请求字段。RemoveZero 始终保持主体比例，并把主体完整放入可用画布。

• 主体完整可见并居中。
• 不裁切、不拉伸。
• 剩余画布使用透明或指定颜色填充。
• 不支持 cover、智能裁切、重力位置或任意坐标。

向后兼容

现有客户端可以省略 input.output，只发送 input.image_base64。需要定制格式、背景、画布或留白时再添加 output。

成功响应

成功处理会返回 HTTP 200，并消耗 1 积分。输出包含准确的内容类型、画布尺寸和可由服务器解码的 Base64 数据。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "id": "REQUEST_ID",
  "status": "COMPLETED",
  "output": {
    "ok": true,
    "content_type": "image/webp",
    "width": 1600,
    "height": 1600,
    "output_base64": "BASE64_IMAGE_RESULT"
  },
  "usage": {
    "units": 1,
    "credits_used": 1
  }
}

解码结果

1. 确认 HTTP 200、ok: true 和 status: COMPLETED。
2. 读取 output.content_type，并且只接受 image/png 或 image/webp。
3. 对 output.output_base64 解码一次，再按内容类型保存。
4. 请求了尺寸时，核对 output.width 和 output.height。

结果以内联数据返回，不提供永久 URL。需要长期保存或交付时，应由你的应用保存解码后的字节。

import { writeFile } from "node:fs/promises";

const payload = await response.json();

if (!response.ok || payload.ok !== true || payload.status !== "COMPLETED") {
  throw new Error(payload.error?.code ?? "REMOVEZERO_REQUEST_FAILED");
}

const { content_type: type, output_base64: base64 } = payload.output ?? {};
const extension = type === "image/png" ? "png" : type === "image/webp" ? "webp" : null;

if (!extension || typeof base64 !== "string") {
  throw new Error("REMOVEZERO_OUTPUT_INVALID");
}

await writeFile(`removezero-result.${extension}`, Buffer.from(base64, "base64"));

计费与积分返还

每次请求处理一张图片。RemoveZero 会验证请求、原子预留 1 积分，并且只在抠图和指定输出都成功后结算。输出定制不会增加推理次数或额外消耗积分。

积分使用流程

如果暂时无法确认请求或返还，API 会返回 REFUND_PENDING、请求 ID 和 Retry-After: 30。请保留同一个 Idempotency-Key，不要用新 Key 重复提交同一张图片。

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "REFUND_PENDING"
  },
  "request_id": "REQUEST_ID"
}

幂等与重试

Idempotency-Key 绑定完整的序列化 JSON 请求体，包括图片和所有已发送的 output 字段。请同时保留原始请求字节和 Key。

• 相同 Key + 完全相同请求体：可以安全重试，不会二次预留积分或重复处理。
• 相同 Key + 请求体改变：返回 409 IDEMPOTENCY_CONFLICT。
• 终态请求再次使用相同 Key：返回 409 IDEMPOTENCY_REPLAY_UNAVAILABLE；不会重放 Base64 结果。
• 新 Key：新的请求，可能再次预留 1 积分。
• 即使 JSON 语义相同，空格、字段顺序或默认字段写法变化也可能被视为不同请求。

Retry-After 规则

429 RATE_LIMITED

等待 60 秒，再用完全相同的请求体和 Key 重试。

503 REFUND_PENDING

等待 30 秒，再用完全相同的请求体和 Key 重试。

503 UPSTREAM_BUSY

等待 10 秒；只有确实发起新尝试时才使用新 Key。

网络超时或 API_UNAVAILABLE

把结果视为未知，保留原始请求体和 Key 直到解决。

示例

请在你的服务器上替换占位符。API Key 不能出现在公开的浏览器代码中。

curl --request POST \
  --url https://removezero.com/api/v1/remove-background \
  --header 'Authorization: Bearer rz_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-08-25-0001' \
  --data '{"input":{"image_base64":"BASE64_IMAGE_DATA","output":{"format":"webp","background":"#ffffff","width":1600,"height":1600,"padding_ratio":0.08}}}'

常用输出起点

以下配方只是起点，不构成任何平台或类目的永久合规保证。平台名称只是标签，不是 API 枚举值。

{"format":"png","background":"transparent","width":1600,"height":1600,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1600,"height":2000,"padding_ratio":0.08}

{"format":"png","background":"transparent","width":1500,"height":2000,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":1920,"height":1080,"padding_ratio":0.08}

{"format":"webp","background":"#ffffff","width":2000,"height":2000,"padding_ratio":0.075}

{"format":"webp","background":"#ffffff","width":2048,"height":2048,"padding_ratio":0.08}

错误与排错

错误响应包含稳定的 HTTP 状态码和简短的 JSON 错误码。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE"
  }
}

安全排错

1. 记录 HTTP 状态码、错误码、存在时的 request_id、时间和 Idempotency-Key。
2. 不要记录或发送 Bearer Key、完整 image_base64 或包含图片数据的完整响应。
3. 先修正 4xx 对应的请求、凭据、余额或请求头问题。
4. 遵守 Retry-After；未解决请求继续使用原始请求体和 Key。
5. 状态持续无法解决时，只向支持提供非敏感标识。

请求限制

每次请求发送一张 JPG、PNG 或 WebP 图片的标准 Base64。解码输入最多 5 MiB，完整 JSON 请求体最多 7,500,000 字节。自定义输出每边最多 4,096 像素且不超过 4,194,304 总像素。若精确尺寸或格式无法放入内联响应，请求会失败并返还预留积分；API 不会静默改变尺寸或格式。