蜂巢 · AI 生成场景效果图

提供商品图(也可以附加参考图) , 使用指定场景ID,快速将商品生成特指定场景效果, 或是自己描述场景,生成效果图.
.

一、接口名称

• 接口地址：https://kf.fw199.com/gateway/ai/image/task/create
• 请求方式：POST
• Content-Type：application/x-www-form-urlencoded

将商品图放入指定（或自动选择的）场景中，异步生成电商场景效果图。创建后立即返回 task_id；通过 HTTP 回调 获取结果图。

推荐流程：

1. （可选）调用 [获取图片场景列表]接口, 选择 scene_id
2. 本接口创建 goods.scene_effect 任务
3. 等待 callback_url 回调

二、请求参数

公共参数

业务参数

images 示例（提交时作为字符串，不要改成 JSON Body）：

[{"url":"https://example.com/product.jpg","role":"product"}]

说明：

• url 须为公网可访问的商品图（jpg / jpeg / png / webp）
• 商品图使用 role=product

images图片中的role定义

三、请求示例代码（Java）

@Test
public void createSceneEffectTask() throws Exception {
    String apiUrl = "https://kf.fw199.com/gateway/ai/image/task/create";
    // 商品图公网 URL（与 HTTP 用例 @sourceImageUrl 一致）
    String sourceImageUrl =
            "https://gw.alicdn.com/imgextra/O1CN0195pSHaOCiVB2vH2e_!!890482188-0-picasso.jpg_.webp";
    // images 为 JSON 字符串，整体作为一个参数参与签名
    String images = "[{\"url\":\"" + sourceImageUrl + "\",\"role\":\"product\"}]";

    Map<String, String> data = new HashMap<>();
    data.put("appid", Config.AppId);
    data.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
    data.put("task_type", "goods.scene_effect");
    data.put("scene_id", "outdoor_sports_court"); // 场景 ID；省略或 auto 自动选景
    data.put("service_tier", "fast");             
    data.put("images", images);
    data.put("prompt", "");                       // 可选补充描述，空字符串也参与签名
    data.put("callback_url", "http://youdomain.com");
    data.put("width", "1024");                    // 0 或未传：输出尺寸跟商品原图
    data.put("height", "1024");
    data.put("sign", Utils.Sign(data, Config.AppSecret));

    String result = doHttpRequest(apiUrl, data);
    System.out.println("result:" + result);
}

四、返回结果

HTTP 状态码始终为 200，业务成败看 JSON 中的 code。创建接口只受理任务，不会在本次响应里返回图片 URL。

4.1 创建成功示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "ait20260908133532829845",
    "client_task_id": "ait20260908133532829845",
    "task_type": "goods.scene_effect",
    "status": "created",
    "duplicated": false
  },
  "trace_id": "e0e75b64-8fd3-4af1-afb9-b134de9db0a5"
}

4.2 异步回调成功示例

创建时传入 callback_url，任务终态后蜂巢向该地址 POST application/json：

{
  "task_id": "ait20260908133532829845",
  "client_task_id": "ait20260908133532829845",
  "task_type": "goods.scene_effect",
  "status": "success",
  "output": {
    "images": [
      {
        "url": "https://static.fw199.com/fc/ai-image/11/xxxxxx.png"
      }
    ]
  },
  "error_code": "",
  "error_msg": null
}

生成的图片请在2天内下载保存,过期会被清掉

业务侧建议：快速返回 HTTP 2xx；用 task_id / client_task_id 做幂等。

五、效果展示

原图:

生成场景图(场景ID:outdoor_sports_court):

生成场景图(场景ID:product_pedestal):