Remove BG

概览

Remove BG 去除任意图像的背景,返回透明 PNG。一个端点、一个必填字段、一种响应结构。面向商品页、设计工具、广告创意流水线,以及任何需要规模化抠图的场景。

端点

POSThttps://api.codia.ai/v1/open/remove_bg

通过 Bearer Token 鉴权。在 codia.ai/dashboard/developer 获取 Key。

请求

字段	类型	必填	说明
`image_url`	string	JSON 模式必填	可公开访问的源图像 URL。
`image`	file	multipart 模式必填	通过 `multipart/form-data` 直接上传本地源图像。也兼容 `file` 字段名。

JSON URL 示例

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{
    "image_url": "your image url"
  }'

直接上传示例

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png'

Codia 会先校验 credits，再读取和上传 multipart 文件。credits 不足时直接返回 402，不会上传图片。

响应

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "image_url": "https://processed-image-url.com/result.png"
  }
}

字段	说明
`code`	`0` 为成功,非 0 表示输入或处理错误。
`message`	人类可读状态。
`data.image_url`	结果 PNG 的 CDN URL,透明背景。尽快下载并存到你方存储,URL 非长效。

输出特性

格式 —— 带 alpha 通道的 PNG。
分辨率 —— 与输入一致,受套餐上限约束(全档均支持 HD)。
边缘质量 —— 亚像素 matte、前景颜色去污染,无背景投影拖尾。
主体自阴影 —— 保留(如马克杯暗侧)。

性能

项	数值
典型处理时间	约 600 ms
端到端延迟	800 – 1200 ms
并发	套餐相关;常见套餐支持数百并发。

支持的输入

输入	建议
常见格式	JPEG、PNG、WEBP
最低分辨率	长边 400 px
大小上限	套餐相关,默认 25 MB
已含 alpha 的图	先在白底扁平化以保留预期透明度
极端运动模糊	可用,但边缘更柔和
主体/背景同色(白对白)	可用,建议加人工评审

错误码

`code`	含义
`0`	成功。
`40001`	`image_url` 缺失或不可达。
`40002`	格式不支持。
`40003`	超过大小限制。
`42900`	速率限制——回退后重试。
`50000`	服务端瞬时错误——指数回退重试。

非 0 code 应分流处理:瞬时错误重试,输入错误快速失败。

集成模式

商品上传(同步)

const res = await fetch('https://api.codia.ai/v1/open/remove_bg', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CODIA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image_url: sourceUrl }),
}).then((r) => r.json())

if (res.code === 0) {
  await saveToBucket(res.data.image_url)
}

批量摄取(异步)

大目录场景下按套餐并发上限起 worker 池,瞬时失败重试。低于最小分辨率的图跳过,不浪费调用。

合成

开发阶段把返回 PNG 合成到深色背景(如 #111),检查边缘 fringe。干净抠图能经受;出现光晕需检查输入。

常见问题

能用上传代替 URL 吗?

可以。发送 multipart/form-data，把本地图片放在 image 字段；如果图片已经是公网 URL，也可以继续使用 JSON image_url。

输出 URL 永久有效吗?

不是。请下载并存到自家存储,URL 下载后会过期。

按图片大小分档计费吗?

不。按成功调用计费,统一价。

未用额度会清零吗?

付费套餐按月滚动。详见定价。

可以保留投影吗?

默认去除全部背景(含投影)。企业部署可通过配置保留投影。

下一步

PDF to Visual Struct —— PDF 文档的结构化转换。
Visual Struct —— 图像的结构化转换。
完整参考:/api#remove-background。