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
它替你做掉的四件事
- 上传:字节直接进 R2,你不需要 R2 账号,也拿不到任何存储凭据。
- 排队:请求自己等着结果;超过等待上限才回
202和status_url,任务不会丢。 - 记账:身份和额度都在服务端算,响应头带
x-quota-remaining,GET /v1/me随时可查。 - 重试:带上
Idempotency-Key请求头,同一把 key 重发不会多扣额度、不会多建任务(重放响应带x-idempotent-replay: true)。
换一种写法
浏览器表单 / 需要附带 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。
| HTTP | code | 含义 / 该怎么做 |
|---|---|---|
200 | — | 出图了。默认是图片字节,Accept: application/json 时是 JSON |
202 | — | 还在跑。带着 job_id 和 status_url,去取结果即可,别重传图 |
400 | bad_request bad_json bad_param missing_image missing_mask bad_mask no_input | 请求本身不对:重试没用,不扣额度;bad_param 的 details 指出是哪一条 |
401 | unauthorized | 没钥匙或钥匙无效——带了坏钥匙不会退回匿名 |
404 | unknown_tool tool_paused job_not_found | 工具不存在 / 注册了但还没开放(不扣额度)/ 任务号查不到 |
410 | job_expired | 结果在出图 24 小时后被删了,重新提交一份 |
413 / 415 | image_too_large unsupported_media_type | 图太大(>10MB)/ 不是 JPEG·PNG·WebP(按字节头判断,不看请求头) |
429 | quota_exhausted | 今天的额度用完了;register 给出注册地址,预付张数看 GET /v1/me 的 credits |
429 | rate_limited | 一分钟内打太快(默认匿名 30 次、钥匙 120 次):按 retry-after 退避即可,日额度没被扣 |
500 / 502 | internal_error processing_failed storage_error | 我们这边的问题:额度已原路退回(用预付张数付的退回张数),退避后可以重试 |
503 | capacity_full service_unavailable | 共用队列今天满了(钥匙不受影响)/ 服务暂时不可用且没扣任何额度;按 retry-after 退避 |