拾影CUTOUT
控制台

一张图片，两种处理方式。

无需选择人像、商品或发丝模型。上传图片后由系统自动选择处理流程，返回原尺寸透明 PNG 或灰度蒙版。

地址与认证

POSTBASE_URL/v1/remove-background

进入 API 接入 页面，登录后即可自助生成密钥（也可通过控制台 → API 密钥进入）；管理员也可在后台分配。创建弹窗同时提供完整地址、密钥和示例，完整密钥仅显示一次。所有正式调用使用请求头 X-API-Key: YOUR_API_KEY。密钥使用当前账号的积分，受后台权限和有效期约束；撤销后立即失效。网页登录 Cookie 无法替代 API Key。

将密钥存放在你自己的服务端环境变量中，避免写入前端代码、公开仓库或链接参数。接口路径和请求头两种模式完全相同，只需改变 mode。

两种处理方式

模式实际处理适用情况
local
本机快速高质量处理（默认）		本地通用分割 → 检查蒙版置信度 → 必要时追加精细分割；检测到人脸时融合人像发丝；蓝色山体与植被全景可自动切换天空分离；最后边缘细化与颜色去污染。全程不调用外部大模型。日常批量处理、人像、动物、商品、车辆、植物等显著主体。
ai
AI 超智能处理		先执行本机流程 → 将原图及初步结果缩略图交给管理员选定的视觉模型 → 判断主体、细节、场景与策略 → 本机完成精修。按需要增加通用精细、人像或风景去天空处理。主体复杂、需要语义判断、局部误保留、风景去天空；比本机模式耗时更长。

本机模式仍使用服务器上的专用视觉模型，不依赖外部聊天模型。AI 模式不生成虚构发丝或替换原图，模型返回的策略与区域须通过数值和类型校验。场景判断不是质量保证：玻璃、运动模糊、相近颜色与极细结构仍可能抠取不完整。

接入示例

cURL · 本机处理
curl --fail-with-body -X POST "BASE_URL/v1/remove-background" \
  -H "X-API-Key: $CUTOUT_API_KEY" \
  -F "image=@photo.jpg" \
  -F "mode=local" -F "output=cutout" \
  --max-time 180 --output result.png

调用 AI 模式将 mode=local 改为 mode=ai。下载蒙版将 output=cutout 改为 output=mask。每个成功请求各计费一次。在 Windows PowerShell 中使用 curl.exe，并按 PowerShell 语法设置环境变量和换行。

PYTHON · requests
import os
import requests

with open("photo.jpg", "rb") as image:
    response = requests.post(
        "BASE_URL/v1/remove-background",
        headers={"X-API-Key": os.environ["CUTOUT_API_KEY"]},
        files={"image": ("photo.jpg", image, "image/jpeg")},
        data={"mode": "local", "output": "cutout"},
        timeout=(10, 180),
    )
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text[:500]}")
with open("result.png", "wb") as result:
    result.write(response.content)
print(response.headers.get("X-Processing-Ms"), "ms")
print(response.headers.get("X-Credits-Charged"), "credits")
NODE.JS 20+ · AI 处理
import { readFile, writeFile } from "node:fs/promises";
const form = new FormData();
form.append("image", new Blob([await readFile("photo.jpg")],
  { type: "image/jpeg" }), "photo.jpg");
form.append("mode", "ai");
form.append("output", "cutout");
const response = await fetch("BASE_URL/v1/remove-background", {
  method: "POST", headers: { "X-API-Key": process.env.CUTOUT_API_KEY },
  body: form, signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
await writeFile("result.png", Buffer.from(await response.arrayBuffer()));

请求参数

请求体为 multipart/form-data。不要手动设置 Content-Type 边界，请交给请求库自动生成。仅接收上传文件，不抓取用户指定的图片 URL。

参数必填说明
image是JPG / PNG / WebP，最大 15 MB、1600 万像素；不支持动画。按 EXIF 方向处理，保留已有透明区域。
mode否local（默认）或 ai。模式权限由密钥控制。
output否cutout（默认）：RGBA 透明 PNG；mask：L 灰度 PNG，白色保留，黑色移除，灰色半透明。
optimize否旧接口兼容参数，默认 false。新接入直接使用 mode=ai，无需再传 optimize。

旧版 fast / quality / portrait 仍可调用，沿用各自处理及计费规则，供已有应用平滑迁移。历史质量模式权限兼容新本机与 AI 模式；新建密钥分别授权两种新模式。

响应与错误

HTTP 200 返回 image/png 二进制，成功响应不是 JSON。返回图像尺寸与修正方向后的输入一致；内部推理会按计算预算缩放，原尺寸输出不代表逐像素恢复。

响应头含义
X-Request-ID请求追踪 ID，排查问题时提供。
X-Processing-Ms等待队列、识别、模型调用与编码的总服务耗时；不含上传下载。
X-Cutout-Mode / X-Optimized实际请求模式及是否完成 AI 优化。
X-Cutout-Strategy / X-Cutout-Subject新模式的实际处理分支与主体类别。local 未进行语义分类时为 object，识别人脸后为 person。
X-Cutout-Warningambiguous-subject 表示没有明确前景或几乎全图被保留，请检查结果；空值表示未触发该检查。
X-Credits-Charged本次实际扣除积分，免费体验或免计费账户为 0。
X-Image-Width / X-Image-Height / X-App-Version输出尺寸与服务版本。
HTTP原因与处理
401密钥缺失、无效、停用或过期，检查 X-API-Key。
402积分不足，请购买套餐。
403密钥无模式权限，或匿名体验请求 AI 模式。
413 / 422文件过大、格式损坏、像素超限或参数错误；修正输入再提交。
429仅匿名体验免费次数已用完，请注册或登录；正式 API 无按时间计数的调用上限。
502AI 渠道异常、超时或返回格式无效，本次退款；可重试或显式切换 local。
503队列繁忙或 AI 未配置，等待或联系管理员。
500内部处理失败，提供请求 ID / 调用时间协助排查。

应用错误通常为 {"detail":"错误说明"}，参数校验错误的 detail 可能为数组。代理层错误可能返回 HTML，应先检查状态码和 Content-Type。

计费、并发与重试

两种模式分别按后台设置的积分计费。AI 价格已包含本机处理，不再额外收取优化费。先预留积分，成功后结算；失败释放预留。套餐售价格与调用积分独立配置，在工作台可查看当前单次价格。

当前为 CPU 服务，自动处理使用独立计算队列，有限并发下繁忙会返回 503。建议从串行调用开始，在 503 时按 Retry-After 或指数退避加随机抖动重试，最多 3 次。API 当前不提供幂等键；客户端超时不等于服务端失败，盲目重试可能形成多次成功调用和扣费。先用调用记录核对。

匿名体验只支持本机模式，同一 IP 默认累计免费 2 张，成功才扣次，免费张数可在后台配置，文件上限 6 MB / 800 万像素。新注册账号默认赠送 10 积分，以当前系统设置为准。生产应用请使用正式接口，不要依赖网页体验接口。

积分与统计

GETBASE_URL/v1/usage

携带同一 X-API-Key，返回当前客户的 balance、unmetered、近 30 天 total / successful / average_ms / credits、按日及模式统计和 recent 调用记录。客户之间隔离，同客户多密钥汇总。管理员后台可按客户、密钥、模式与状态筛选并导出 CSV。

健康检查

GET /healthz 无需认证；模型加载预热结束后返回 status=ok、版本和公共模式。GET /api/config 可读取当前公开价格、默认模式和 AI 是否启用。

图片与效果边界

服务不持久保存上传图或结果，只记录调用元数据；AI 模式会向已配置的外部渠道发送两张缩略图，其数据政策由该渠道决定。风景通常没有唯一前景：AI 风景策略默认保留地形与植物、移除天空，自动判断也可能有误。照片中已经丢失的细节无法可靠恢复；请检查透明背景下的实际结果。