博客

使用指南

通过 HiAPI API 使用 qwen-image-2.1-turbo 生成电商产品图片

面向开发者的快速目录视觉工作流:透明 PNG 输出与可运行的 API 请求

2026年11月20日
暖沙色调的封面图形,带有宽阔的水平阶梯状色带,以赤陶色和棕褐色像气压图一样逐级下降。
本页内容

qwen-image-2.1-turbo 的适用场景

商品目录的图片工作表面上是创意问题,实质上是吞吐量问题。单张主图可以手工精修,但拥有数千个 SKU 的店铺需要一致的构图、可预期的交付周期,以及能直接接入现有素材流水线的输出。你选择的图像模型决定了你需要重建多少流水线。

通常有三条标准主导这一决策:

  • 负载下的延迟。每夜的目录任务属于批处理任务;一个在交互场景中表现良好的模型,仍可能让 10,000 个 SKU 的刷新变得痛苦。
  • 输出格式适配。如果你的合成阶段需要 alpha 通道,而模型只返回不透明图像,你就得自己新增一个分割步骤。
  • 对产品描述语言的提示词表现。产品提示词简短、具体且重复——能稳定处理这类提示词的模型,胜过一个在开放式艺术提示词上表现出色的模型。

本指南重点介绍前两条标准以及连接二者的请求模式。我们将探讨 turbo 变体在产品图片流水线中的定位、透明 PNG 输出如何改变你的后处理链路,并给出一个可直接放入 worker 的请求。最后讨论批量扩展时需要注意的问题,并在文本驱动生成不适用时,简要对比图生图方案。

产品图片任务分支为模型选择标准,以分叉的阶梯状条带表示。

透明 PNG 输出与你的后处理链路

可以把产品图片流水线看作四个阶段:请求构建 → 生成 → 输出处理 → 发布。turbo 变体是一次有意的押注:让第二阶段足够快、足够便宜,能够支撑目录规模,从而让你把工程预算花在第一和第三阶段上。

何时它是正确的首选

在以下情况下选择 qwen-image-2.1-turbo:

  • 你的提示词结构化且可重复——每个类目一个模板,留出材质、颜色、角度和背景意图的槽位。
  • 你需要为每个 SKU 生成大量变体(角度、配色、场景),而不是一张精心艺术指导的画面。
  • 你的下游合成已经自动化,因此干净的抠图比完整的成品场景更有价值。
  • 你想在引入参考图之前,先得到一个文本驱动的基线。

何时需要更强的模型

如果某个 SKU 需要与参考照片严格匹配的高度特定构图,或者瓶颈在于复杂场景下的输出质量而非数量,那么 turbo 层级就不是合适的默认选择。这种情况下,保留 turbo 处理大部分目录变体,将少量主图素材交给更重的生成路径——流水线形态保持不变,只更换模型标识符。

设计可替换的模型槽位

由于 turbo 层级主打规模,应将模型名称视为配置,而不是散落在代码库中的硬编码常量。在 worker 启动时读取一个 IMAGE_MODEL 环境变量,意味着你可以对部分类目 A/B 测试另一个模型,而无需改动请求代码。正是这一决定让本指南的其余内容具备可移植性。

turbo 变体作为四阶段条带流水线中压缩且抬升的台阶:接入、加速生成、输出处理、发布。

一个可运行的 HiAPI 产品图片请求

透明 PNG 是目录流水线中杠杆率最高的输出选择,因为它把昂贵的步骤——将产品从背景中分离——前移到生成阶段。你不再需要分割不透明渲染图,而是收到一个带 alpha 通道的素材,然后自行合成。

下游会发生什么变化

有了 alpha 通道,背景就变成渲染层面的关注点,而不是建模层面的关注点。同一张抠图可以放到白色影棚背景上作为 PDP 主图,放到生活方式场景中用于营销位,放到纯品牌色上作为类目磁贴——全部来自一次生成。这就是核心经济性:一个产品素材,多个已发布变体。

实际操作中,请规划以下步骤:

  • 校验 alpha 通道。检查图像是否确实具有非平凡的 alpha 通道,以及主体是否未在画面边缘被裁切。抠图接触边框属于生成失败,而不是合成问题。
  • 归一化画布。在合成前,在一致的画布上调整大小并填充抠图,使不同 SKU 的位置可预测。
  • 按发布位置分别合成。将背景预设作为数据保存(尺寸、颜色、可选背景素材),并从同一源 PNG 渲染每个发布位置。
  • 存储源文件,发布渲染结果。将透明原图持久化为规范素材,并将每个合成变体视为可重新生成的派生产物。

注意文件大小的取舍:alpha 通道会使 PNG 更大,而目录存储又会将其乘以每个变体。如果你的 CDN 提供 WebP 或 AVIF,请在发布时转换,同时保留 PNG 源文件。

透明抠图作为浮动图层:同一轮廓覆盖在每个背景变体上,然后向右流入存储步骤。

扩展到批量任务并避免集成陷阱

以下所有内容都运行在 HiAPI 统一接口之上——一个基础 URL、一份凭证、跨模型一致的请求形态。在锁定 schema 之前,请从 qwen-image-2.1-turbo 模型页面 获取准确的参数列表和当前字段名;这里重要的是模式本身。

请求形态

产品图片调用由提示词和输出规格组成。用模板构建提示词,使每个 SKU 只提供自己的变量:

import os, requests

HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")

def product_prompt(sku):
    return (
        f"studio product photo of {sku['name']}, {sku['material']}, "
        f"{sku['color']} finish, three-quarter view, soft even lighting, "
        "centered on a plain background, no text, no props"
    )

def generate(sku):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {HIAPI_KEY}"},
        json={
            "model": MODEL,
            "prompt": product_prompt(sku),
            "transparent_background": True,
            "n": 1,
        },
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()

关于请求体有两点说明。第一,显式请求透明背景——它是调用上的参数,而不是下载后再推断的东西。第二,每次调用保持较低的 n,并在任务层面并行化;一批单图请求的重试远比一次请求二十张图更干净,因为后者只要有一张失败就会损失整组。

防御性地处理响应

响应携带图像数据(URL 或编码后的负载,取决于你发送的参数)。将获取视为与生成分开的故障域:生成返回后,再下载、验证并上传到你自己的存储。从那时起,你的流水线引用的是你的存储桶,而不是临时结果——这正是让重试和重新渲染可控的关键。

与图生图路径的对比

可运行的脚本与可运行的目录任务之间的差距,几乎总是出现在那些枯燥的部分。

将提示词模板化为数据

将提示词片段按类目放在配置文件中,而不是代码中。每个 SKU 提供槽位;类目提供句子框架和负面约束("no text, no watermarks, no props")。当某个类目的构图不对时,你只需修复一个模板,而不是数千行数据。

有目的地重试

将可重试的失败(超时、临时服务器错误、速率限制)与终态失败(无效参数、被拒绝的提示词)区分开。对第一类使用指数退避和重试上限进行重试;对第二类立即失败并暴露原因,因为重试格式错误的请求只会消耗队列。这里幂等性很重要——用 SKU 加提示词哈希作为每个任务的键,使重试的任务覆盖而非重复。

在店面看到之前进行校验

在生成和发布之间插入一个校验关卡。低成本的自动检查能捕获大多数不良输出:

  • 存在 alpha 通道,主体未在边缘被裁切。
  • 分辨率满足你发布的最大位置的最低要求。
  • 与当前素材做感知哈希,标记意外的近似重复。

将未通过关卡的内容送入审核队列,而不是直接丢弃。静默失败正是目录悄无声息地填满颜色错误产品的方式。

注意并发上限

批处理任务往往以突发方式触及速率限制,而不是逐渐触及。将 worker 并发数限制在你认为的上限以下,使该上限可配置,并让队列吸收积压。一个被限流但能完成的流水线,好过一个来回震荡的流水线。

按输出而非按请求做预算

计费跟随你生成的输出,因此将每个 SKU 生成的素材数量作为成本信号进行跟踪。当某个类目开始为每个产品生成大量变体时,这是你应当有意做出的提示词设计决策,而不是在账单上才发现。

与图生图路径的对比

当产品尚不存在可用的照片时——新 SKU 还未拍摄、产品有尚未拍过的新颜色、或发布用的占位素材——文本驱动生成是正确的默认选择。提示词完整描述结果,透明输出为你提供可合成的素材,无需分割步骤。

图生图路径翻转了输入。你提供参考图,模型基于它工作,这正是当对真实产品的保真度不可妥协时所需要的:匹配实际的缝线、真实的硬件饰面、客户将收到的确切色调。在这种模式下,参考图是保持生成诚实的约束。

对大多数目录而言,一个实用的划分:

  • Turbo 文生图用于规模——变体、背景、类目磁贴、早期上架占位图。
  • 图生图用于任何客户会用来做出购买决策且视觉准确性至关重要的场景。

两者共享同一流水线骨架,因此切换只是一个模型标识符加一个输入字段,而不是重写。当你需要参考图驱动的输出时,qwen-image-3.0 图生图模型 可以接入同一个 worker,只需在提示词旁附带参考图。

先在一个类目上运行 turbo 路径,测量校验通过率,然后逐步扩展——模型页面列出了你需要接入的字段。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档