# PopPic 白底图 Open API 接口文档

> PopPic 白底图 Open API：通过 HTTP 接口单张或批量生成商品白底图，保留真实阴影，精确叠加品牌 Logo。异步任务，每批最多 20 张，默认 0.65 元/张，以控制台个人中心为准。

- 网页版：https://open.poppic.cc/docs
- 接口基础地址：`https://open.poppic.cc/v1`
- 提交任务：`POST https://open.poppic.cc/v1/open-api/white-bg`（异步任务 · 最多 20 张 / 批次 · 仅 GPT Image 2）
- 查询任务：`GET https://open.poppic.cc/v1/open-api/white-bg/:id`
- 价格：默认 0.65 元/张，以控制台个人中心为准
- 更新于：2026-11-12

单张或批量生成白底图，保留真实阴影，精确叠加品牌 Logo。一个接口，接入现有工作流。

下文里以 `/v1/` 开头的路径都接在 `https://open.poppic.cc` 后面；示例代码里的 `BASE` 就是上面的接口基础地址。

## 鉴权与计费

创建 API Key，充值后在每次请求中传入 `Authorization: Bearer pp_...`。不要把密钥放在 URL、公开网页或客户端代码中。

默认 ¥0.65 / 张，实时价格以个人中心为准。提交时一次性预扣整批费用；余额不足返回 402，不发起生图。失败的图片自动退款，部分成功只收成功张数。重复查询和下载不收费。

同一 Key 下相同 `requestId` 和参数只创建一次任务。网络超时请复用它；参数改变但 ID 不变返回 409。每个 Key 每分钟最多 120 次请求（含查询/下载），建议每 5 秒查询一次。

## 请求参数

| 字段 | 说明 | 默认 |
| --- | --- | --- |
| `requestId` | 必填 UUID，客户端生成，用于防重扣费 | — |
| `images` | 必填；单个 Data URL，或 1–20 个 Data URL 的数组 | — |
| `model` | 只允许 gpt-image-2；具体厂商由后台管理 | gpt-image-2 |
| `angle` | default 默认 / eye_level 正视 / low_angle 微俯视 / high_angle 高俯视 | default |
| `whitespace` | 整数 5–40，边缘留白百分比 | 25 |
| `backgroundColor` | 六位 HEX 颜色，如 #F2F2F2 | #FFFFFF |
| `aspectRatio` | 1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9、9:21、1:4、4:1、1:8、8:1、1:3、3:1、2:1、1:2 | 1:1 |
| `imageSize` | 1K / 2K / 3K / 4K（实际能力受后台选定厂商约束） | 1K |
| `width / height` | 可选自定义像素；必须同时传，256–4096，优先于比例与分辨率档位 | 不传 |
| `logo.image` | 可选 Logo Data URL，推荐透明 PNG | 无 Logo |
| `logo.box` | x、y、width、height；背景比例坐标，不是像素 | 随 Logo 必填 |

图片格式为 `data:image/png;base64,...`（也支持 jpeg、webp），不支持任意远程 URL。单张解码后最多 5MB、4000 万像素；整个请求图片的 base64 合计最多 30MB。

Logo 的坐标原点在背景左上角，范围 0–1。例如 `x=0.05` 表示距左边 5%。框必须完全位于背景内，Logo 在框内等比居中，不拉伸、不交给 AI 绘制。所有图片使用同一个 Logo 和布局；如需不同布局，请分批提交。

固定使用保留阴影的处理算法。若背景校正失败，会沿用已有流程保留原图；Logo 仍在最后用代码叠加。模型不能保证商品细节绝对不变。

## 获取结果与 7 天保留期

提交返回 HTTP 202，包含 `id、status、imageCount、chargedCents、expiresAt、outputs`。用同一 API Key 请求 `GET /v1/open-api/white-bg/:id`。

状态为 PREPARING / QUEUED / RUNNING / COMPLETED / PARTIAL / FAILED。`outputs` 按输入顺序返回，每项含 `index、id、status、url、urlExpiresAt、downloadPath`。完成图片的 url 是私有 OSS 签名链接，可直接下载；链接失效后，携带 API Key 请求 downloadPath 获取新的 `{url, expiresAt}`。

**从接收请求起保留 7 天，到期立即拒绝下载（410），后台定期删除输入、Logo、中间文件和结果。** OSS 签名链接最长 5 分钟且不超过 7 天截止时间；它本身是临时凭证，请勿公开转发。Key 撤销后不能获取新链接，已经签发的链接最多再存活 5 分钟。撤销 Key 不取消已扣费的任务；账号仍可在控制台下载。

错误：

| 状态码 | 含义 |
| --- | --- |
| 400 | 参数错误 |
| 401 | Key 无效 |
| 402 | 余额不足 |
| 404 | 非本 Key 的请求或未完成图片 |
| 409 | requestId 冲突 |
| 410 | 到期 |
| 413 | 请求过大 |
| 429 | 限流 |
| 503 | 服务/模型未配置 |

输入校验失败和余额不足不会扣费。

## Python 完整示例

依赖 requests。将真实域名和 Key 放入环境变量，避免写死在源码。

```python
import base64, pathlib, time, uuid, requests, os

BASE = os.environ["POPPIC_API_BASE"]  # https://open.poppic.cc/v1
headers = {"Authorization": "Bearer " + os.environ["POPPIC_API_KEY"]}
def image(path, mime="image/png"):
    return "data:" + mime + ";base64," + base64.b64encode(pathlib.Path(path).read_bytes()).decode()

payload = {
    "requestId": str(uuid.uuid4()),  # 网络重试时复用；新批次换新 UUID
    "images": [image("product.png")],
    "model": "gpt-image-2",
    "angle": "default",
    "whitespace": 25,
    "backgroundColor": "#FFFFFF",
    "aspectRatio": "1:1",
    "imageSize": "1K",
    "logo": {"image": image("logo.png"),
             "box": {"x": 0.05, "y": 0.05, "width": 0.25, "height": 0.12}}
}
r = requests.post(BASE + "/open-api/white-bg", headers=headers, json=payload, timeout=180)
r.raise_for_status()
task = r.json()
deadline = time.monotonic() + 1800
while task["status"] in ("PREPARING", "QUEUED", "RUNNING"):
    if time.monotonic() > deadline:
        raise TimeoutError("保留 task.id，稍后继续查询，不要用新 requestId 重复下单")
    time.sleep(5)
    r = requests.get(BASE + "/open-api/white-bg/" + task["id"], headers=headers, timeout=30)
    r.raise_for_status()
    task = r.json()
for item in task["outputs"]:
    if item["downloadPath"]:
        r = requests.get(BASE.removesuffix("/v1") + item["downloadPath"], headers=headers, timeout=30)
        r.raise_for_status()
        # 签名 OSS URL 已携带临时凭证，不要把 API Key 发送到 OSS！
        result = requests.get(r.json()["url"], timeout=120)
        result.raise_for_status()
        pathlib.Path(f"result-{item['index']}.png").write_bytes(result.content)
print(task["status"], task["chargedCents"], task["expiresAt"])
```

## 微信充值

在个人中心选择金额，通过微信扫描二维码付款。余额以服务端验签后的支付通知或微信查单结果为准，刷新或关闭页面不会丢失已经支付的订单。请勿重复付款；未及时到账可点击“核对支付”。API 余额不与画布积分、会员包或小程序共用。
