图片血汗工厂

API

一张图,一个请求

图片、参数、钥匙全塞进同一个 POST /api/remove-background。 不用先问上传地址、不用自己把图传到对象存储、也不用轮询队列—— Worker 在边缘收下字节,交给后台的卡,能在 20 秒内出图就当场把图还给你。

额度:不带钥匙也能调,匿名按 IP 每天 10 张,不加水印、不收额外尺寸费; 长边超过 4096 px 的图会先等比缩到这个尺寸再处理(输出也随之变小,接口不会额外提示)。 注册账号后 API 每天 30 张,在网页上用则不占这 30 张。 免费额度用完之后自动扣预付张数:$10 一包 1000 张($0.01/张,约 ¥0.07),按张扣、不过期, 在账号页自助购买,付款走 Stripe。剩下多少看 GET /v1/me 的 credits。

拿一把钥匙

钥匙挂在账号下,先注册一个免费账号(邮箱或 Google),注册完当场发一把。

快速开始

最省事的形态:原始图片字节直接当请求体,工具在路径里,参数走 params。

curl -sS -X POST "https://photosweat.shop/api/remove-background" \
  -H "Authorization: Bearer sk_free_…" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg \
  -o cutout.png

它替你做掉的四件事

换一种写法

浏览器表单 / 需要附带 mask / 想要结构化结果时:

# multipart:image、可选 mask、params(JSON 字符串)
curl -sS -X POST "https://photosweat.shop/api/remove-background" \
  -H "Authorization: Bearer sk_free_…" \
  -F image=@photo.jpg

# 要 JSON(含 result_url)而不是图片字节
curl -sS -X POST "https://photosweat.shop/api/remove-background" \
  -H "Authorization: Bearer sk_free_…" -H "Accept: application/json" \
  --data-binary @photo.jpg

# 白底(原来要用 image.white-bg,现在并进 background 参数)
curl -sS -X POST "https://photosweat.shop/api/remove-background?params=%7B%22background%22%3A%22white%22%2C%22format%22%3A%22jpeg%22%7D" \
  -H "Authorization: Bearer sk_free_…" --data-binary @photo.jpg -o out.jpg

查今天还剩多少

接口

方法与路径作用
POST /api/remove-background去背景(目前唯一对外工具):传图 + 拿结果
GET /api/tools工具目录:哪些能用、价格、参数
GET /api/status服务健康:数据库、存储、调度器心跳;正常 200,降级 503(人看的版本在 /status)
GET /v1/me今天的额度用量、预付张数余额(credits)和每分钟上限;不带钥匙查本 IP 的匿名额度
POST /api/auth/credits/buy买一包 1000 张($10):返回 Stripe 收银台地址(需要登录)
POST /api/auth/email/start发一封 6 位邮箱验证码(注册前要先拿到它)
POST /api/auth/signup注册账号,返回账号下的一把钥匙(要带上一步的 code)
POST /api/auth/keys再发一把钥匙(需要登录)
GET /api/capabilities能力清单、参数与约束
GET /api/jobs/:id任务状态(202 之后用它取结果)

返回码

所有报错都是 JSON:code 是稳定的机器契约(只增不改,按它分支), error 是一句英文说明(措辞会改,别 match 它)。完整清单见 OpenAPI 的 Error schema 与 llms.txt。

HTTPcode含义 / 该怎么做
200—出图了。默认是图片字节,Accept: application/json 时是 JSON
202—还在跑。带着 job_id 和 status_url,去取结果即可,别重传图
400bad_request bad_json bad_param missing_image missing_mask bad_mask no_input请求本身不对:重试没用,不扣额度;bad_param 的 details 指出是哪一条
401unauthorized没钥匙或钥匙无效——带了坏钥匙不会退回匿名
404unknown_tool tool_paused job_not_found工具不存在 / 注册了但还没开放(不扣额度)/ 任务号查不到
410job_expired结果在出图 24 小时后被删了,重新提交一份
413 / 415image_too_large unsupported_media_type图太大(>10MB)/ 不是 JPEG·PNG·WebP(按字节头判断,不看请求头)
429quota_exhausted今天的额度用完了;register 给出注册地址,预付张数看 GET /v1/me 的 credits
429rate_limited一分钟内打太快(默认匿名 30 次、钥匙 120 次):按 retry-after 退避即可,日额度没被扣
500 / 502internal_error processing_failed storage_error我们这边的问题:额度已原路退回(用预付张数付的退回张数),退避后可以重试
503capacity_full service_unavailable共用队列今天满了(钥匙不受影响)/ 服务暂时不可用且没扣任何额度;按 retry-after 退避