图片血汗工厂

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

它替你做掉的四件事

一批图 + 回调

一次 1–10 张,共用一套参数;给了 callback_url 就不用轮询——每张图到终态时投递一次到你那边(job.done / job.failed;至少一次,按 job_id 去重),失败会退额度,回调里只有元数据和现签的地址,不带图片字节。

curl -sS -X POST "https://photosweat.shop/api/batch" \
  -H "Authorization: Bearer sk_free_…" \
  -H "Idempotency-Key: batch-1" \
  -F image=@a.jpg -F image=@b.jpg \
  -F 'params={"background":"white"}' \
  -F callback_url=https://your.app/hook \
  -F callback_secret=whsec_…

计费是整批原子的:有一张扣不动,整批不建单、已扣的退回。回调带 x-photosweat-signature: t=…,v1=…(hmac_sha256(secret, "<t>.<body>")),退避 30s/2m/10m/1h/6h,最多 6 次,按 job_id 去重。

换一种写法

浏览器表单 / 需要附带 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

Postman 与容量

不想先写代码:把这两个文件拖进 Postman,填一张本地 PNG 就能跑完建单→轮询→取图。

容量(2026-11-19 实测,生产库 37 张):单张 P50 4.5 s、P90 7.2 s;一个 worker 串行执行, 约 600–800 张/小时(≈1.4 万张/天),且与挖矿并行、不掉算力。 超量时同步接口等 20 秒回 202,任务不丢;加一张卡就多一份线性吞吐。

SDK(零依赖,下载即用)

不想自己写重试、轮询和幂等键:两个单文件客户端,只用标准库 / Node 自带的 fetch,拷进项目就能跑。

from photosweat import Client
ps = Client(api_key="sk_free_…")          # 不填就按匿名额度
job = ps.remove_background("photo.jpg", params={"background": "white"})
open("out.png", "wb").write(ps.result(job))

内置:同一次调用贯穿同一个 Idempotency-Key(重试不重复扣额度)、429/5xx 尊重 retry-after 退避、 202 之后按 status_url 轮询到终态、JPEG/PNG/WebP 按字节头识别(坏字节本地就拦,不发请求不扣额度)。

查今天还剩多少

接口

方法与路径作用
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 退避