DEVELOPER DOCUMENTATION / V1

让商品图,一次准备就绪。

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

POST/v1/open-api/white-bg

异步任务 · 最多 20 张 / 批次 · 仅 GPT Image 2

01 · 鉴权与计费

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

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

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

02 · 请求参数

字段说明默认
requestId必填 UUID,客户端生成,用于防重扣费—
images必填;单个 Data URL,或 1–20 个 Data URL 的数组—
model只允许 gpt-image-2;具体厂商由后台管理gpt-image-2
angledefault 默认 / eye_level 正视 / low_angle 微俯视 / high_angle 高俯视default
whitespace整数 5–40,边缘留白百分比25
backgroundColor六位 HEX 颜色,如 #F2F2F2#FFFFFF
aspectRatio1: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:21:1
imageSize1K / 2K / 3K / 4K(实际能力受后台选定厂商约束)1K
width / height可选自定义像素;必须同时传,256–4096,优先于比例与分辨率档位不传
logo.image可选 Logo Data URL,推荐透明 PNG无 Logo
logo.boxx、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 仍在最后用代码叠加。模型不能保证商品细节绝对不变。

03 · 获取结果与 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 服务/模型未配置。输入校验失败和余额不足不会扣费。

04 · Python 完整示例

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

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"])

05 · 微信充值

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