WIME OpenAPI#

电商 AI 创作平台，提供两个核心 Skill。

认证#

该 skill 仅支持 WIME_ACCESS_TOKEN。

安全与权限说明：该 skill 需要 WIME 专用凭证，并且会把用户明确提供的本地图片上传到 WIME 服务；当输入是远程图片 URL，或 WIME 返回远程抠图结果 URL 时，可能会拉取对应图片做处理。为降低风险，远程下载应仅用于用户提供或 WIME 返回的公开图片地址，不应用于 localhost、内网或其他非公开地址。

统一使用 scripts/wime_auth.py 的 get_auth() 函数：

python

from wime_auth import get_auth

auth = get_auth(uri_path="/waic/core/creationDesk/draw", body_dict=body)

resp = requests.post(
    f"{auth['base_url']}/waic/core/creationDesk/draw",
    headers=auth["headers"],
    data=auth["body_str"].encode("utf-8")
)

get_auth() 返回：

• base_url: API 根地址
• headers: 完整请求 headers dict（含 access-token）
• body_str: JSON 序列化后的 body 字符串（用于 data= 发送），body_dict 为 None 时为 None

配置方式#

bash

export WIME_ACCESS_TOKEN='你的token'

# 可选，默认 https://wime-ai.com
export WIME_BASE_URL='https://wime-ai.com'

若未配置 WIME_ACCESS_TOKEN，调用前应直接报错并提示用户先完成配置。

获取凭证#

访问 wime-ai.com，页面右下角有 API 对接 的联系方式，通过该入口申请获取 access-token。

如果当前环境未配置凭证，应直接告知用户先去官网联系获取，而不是盲目调用接口。

图片来源判断（通用前置步骤）#

用户输入可能是 本地路径 或 URL，统一处理为可访问的图片 URL：

text

判断用户输入:
  ├─ 本地路径 (如 /Users/.../image.jpg)
  │    → upload → imageUrl
  │
  └─ URL (以 http:// 或 https:// 开头)
       → 直接使用该 URL 作为 imageUrl
       → （若后续接口不接受外部 URL，则下载 → upload → imageUrl）

新版上传接口#

POST /waic/core/file/py/upload（multipart/form-data）

直接返回 data.url（可访问的图片 URL）， 不再返回 mediaId。

python

from wime_auth import get_auth

auth = get_auth()

with open("image.png", "rb") as f:
    resp = requests.post(
        f"{auth['base_url']}/waic/core/file/py/upload",
        headers={"access-token": auth["headers"]["access-token"]},
        files={"file": ("image.png", f, "image/png")}
    )
image_url = resp.json()["data"]["url"]

注意： 上传接口需要 access-token header。

URL 下载注意事项（仅本地路径场景需上传）#

• 如果用户直接给了 URL， 优先直接用，不需要下载再上传
• 只有本地文件才需要走上传流程
• 上传完成后清理本地临时文件
• 若必须下载远程图片进行处理，只允许公开 http/https 地址；拒绝 localhost、 .local、回环地址和内网 IP

Skill 1：抠图#

触发词： 抠图、去背景、透明背景、matting

新版流程（access-token）#

text

用户提供本地图片路径或 URL
  → [图片来源判断] → imageUrl
  → removeBg([{imageUrl}]) → taskItemIds
  → queryItemForSaas(taskItemId) 轮询 → 抠图结果 URL

接口： POST /waic/core/creationDesk/removeBg

⚠️ 新版抠图为异步接口，返回 taskItemIds，需轮询获取结果。

步骤：

1. 获取图片 URL：本地路径 → 上传获取 url；URL → 直接使用

2. 构建请求体： python

   import json
   body = {
       "data": json.dumps([{"imageUrl": image_url}]),
       "skill": True
   }
   
   

   注意 data 字段是 JSON 字符串（不是 object），内部为 imageUrl 数组。

3. 调用 removeBg，获取 taskItemIds

4. 用 taskItemIds[0] 轮询 queryItemForSaas， itemStatus == 2 且 url 有值时完成

输出给用户： 抠图结果 URL

Skill 2：商拍图#

触发词： 商拍图、商品图、AI 商拍、产品摄影

新版流程（access-token）#

text

用户提供本地图片路径或 URL
  → [图片来源判断] → imageUrl（原图 URL，记为 sourceImageUrl）
  → removeBg → taskItemIds → 轮询 → cutoutUrl
  → crop_alpha_bbox(cutoutUrl) → 本地裁剪图 (cropped.png)
  → upload(cropped.png) → croppedUrl
  → removeBg(croppedUrl) → 轮询 → croppedCutoutUrl（紧凑抠图）
  → draw(picList 使用 croppedCutoutUrl) → taskItemIds
  → queryItemForSaas 轮询 → 出一张返回一张

步骤：

1. 获取原图 URL：

   • URL 输入 → 直接用作 sourceImageUrl
   • 本地路径 → 上传获取 url，作为 sourceImageUrl

2. 首次抠图：调用 removeBg 传入原图 URL → 轮询获取 cutoutUrl

3. 裁剪非透明区域：使用 scripts/crop_alpha.py 的 crop_alpha_bbox(cutoutUrl) 裁剪最小外接矩形，去除多余透明边距

4. 上传裁剪图：将裁剪后 PNG 通过 /waic/core/file/py/upload 上传 → 获取 croppedUrl 及裁剪后宽高

5. 二次抠图：调用 removeBg 传入 croppedUrl → 轮询获取 croppedCutoutUrl

6. 构建 draw 请求：

接口： POST /waic/core/creationDesk/draw

python

body = {
    "ips": False,
    "needRank": True,
    "num": 4,
    "type": 1002,
    "data": {
        "aiStyle": True,
        "bgColor": "",
        "height": 1024,
        "width": 1024,
        "industry": "其他",
        "negPrompt": "",
        "prompt": "",
        "promptAi": "",
        "randomStyle": True,
        "referenceUrl": "",
        "seed": 0,
        "styleCode": "A0072",
        "skill": True,
        "picList": [
            {
                "imageUrl": cropped_cutout_url,
                "sourceImageUrl": source_image_url,
                "imageCaption": "",
                "width": crop_w,
                "height": crop_h,
                "left": calculated_left,
                "top": calculated_top,
                "scaleX": calculated_scale,
                "scaleY": calculated_scale,
                "type": 1,
                "parentId": ""
            }
        ]
    }
}

注意新版 body 结构： 外层有 ips/ needRank/ type，画布参数在 data 内， data.skill 必须为 True。

1. 提交后获得 taskItemIds
2. 轮询 queryItemForSaas（每个 taskItemId 单独查）， 每完成一张立即输出
3. 清理：删除本地临时裁剪文件

picList 位置与缩放规则#

根据 商品图裁剪后的宽高比 判断横竖版，分别计算缩放和位置：

python

canvas_w, canvas_h = 1024, 1024  # 画布尺寸
img_w, img_h = crop_w, crop_h  # 裁剪后的商品尺寸

if img_w >= img_h:
    # 横版/方图商品：商品宽度 = 画布宽度 × 60%
    scale = (canvas_w * 0.6) / img_w
else:
    # 竖版商品：商品高度 = 画布高度 × 80%
    scale = (canvas_h * 0.8) / img_h

# 安全 clamp：缩放后商品不能超出画布任意一边
scale = min(scale, canvas_w / img_w, canvas_h / img_h)

# 水平方向：居中
left = (canvas_w - img_w * scale) / 2

# 垂直方向：总空白区域中，上方占 65%，下方占 35%
total_v_blank = canvas_h - img_h * scale
top = total_v_blank * 0.65

裁剪脚本用法#

python

import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'scripts'))
from crop_alpha import crop_alpha_bbox

cropped_path, (crop_w, crop_h) = crop_alpha_bbox(cutout_url, "/tmp/wime_cropped.png")

结果轮询#

接口： POST /waic/core/task/queryItemForSaas

python

body = {"taskItemId": task_item_id}  # 单个 taskItemId（Long）
auth = get_auth(uri_path="/waic/core/task/queryItemForSaas", body_dict=body)
resp = requests.post(
    f"{auth['base_url']}/waic/core/task/queryItemForSaas",
    headers=auth["headers"],
    data=auth["body_str"].encode("utf-8")
)
# data.itemStatus == 2 且 data.url 有值 → 完成

轮询状态码（实测）#

itemStatus含义0需区分：调度延迟 vs 真正失败（见下方判定逻辑）1执行中（未出图）2完成（ url 字段有值）3执行中4排队中

判断完成的条件： itemStatus == 2 且 url 非空。

⚠️ itemStatus=0 的判定逻辑：

实测发现：任务在较长一段时间内 持续返回 status=0 仍可能最终成功。 不要因为连续几次 0 就判定失败。

推荐轮询策略：

• 完成条件： itemStatus == 2 且 url 非空
• 轮询间隔： 5~10 秒
• 默认最长等待： 3~10 分钟
• 在超时前， 不要仅因 status=0 就判失败
• 超时后仍无结果，标记为 "超时/未完成"

输出给用户： 每张图完成时立即返回结果 URL

---

API 路径对照#

功能路径图片上传POST /waic/core/file/py/upload抠图POST /waic/core/creationDesk/removeBg商拍图POST /waic/core/creationDesk/draw结果轮询POST /waic/core/task/queryItemForSaas

环境#

环境Base URL说明生产https://wime-ai.com线上环境

默认使用生产环境。 WIME_BASE_URL 可覆盖。

接口参考#

文件说明references/upload-image.md图片上传references/cutout.md抠图references/photo-shoot.md商拍图references/asset-query.md结果轮询 + 资产查询references/error-codes.md全局错误码

注意事项#

• 新版上传图片直接得到 URL，不再有 mediaId 概念
• 抠图为 异步 接口，需轮询获取结果
• 商拍图始终为 异步 接口，轮询时出一张返回一张
• body 中含 skill: true 的接口必须传此字段
• QPS 限制，超限返回 errcode=1000007
• 该 skill 依赖 WIME_ACCESS_TOKEN；发布到注册表时应显式声明该环境变量与主凭证需求