如何使用 Qwen-Image-2.1：diffusers 代码、透明背景输出与可实测的 API

Qwen-Image-2.1 是阿里巴巴于 2026 年 9 月 20 日发布的开放权重图像模型：一个 7B 参数的生成器，同时支持文生图、最多 10 张参考图的编辑，以及原生透明（RGBA）输出。本指南带你从 pip install 一路做到一个可用的 HTTP 接口。内容涵盖 GitHub README 中的四条参考代码路径、真正重要的参数设置、一个小的 FastAPI 封装（让该模型像其他图像 API 一样可调用），以及如何在 Apifox 中测试这个接口，从而让提示词改动和模型更新不会弄坏你的应用。

如果想先了解背景，Qwen-Image-2.1 是什么一文涵盖了架构和许可。许可的简版说明：仅限研究和非商业用途，除非你与 Qwen 另行签订商业协议。下面所有内容都适合用于评估。

开始之前

要求	说明
Python 包	`torch>=2.4.0`、`transformers>=5.17`、来自 GitHub main 的 `diffusers`、`accelerate`、`pillow`
Pipeline 类	`QwenImage21Pipeline`（生成和编辑共用一个类）
权重	Qwen/Qwen-Image-2.1，bf16 safetensors
GPU	Qwen 未说明；参考代码面向一块 CUDA 设备并使用 bfloat16，以 `enable_model_cpu_offload()` 作为回退方案
默认输出	2048 x 2048；40 个推理步
可选	`Qwen-Image-2.1-PE-T2I` / `PE-I2I` 提示词改写模型

安装：

pip install "torch>=2.4.0" "transformers>=5.17" accelerate pillow
pip install git+https://github.com/huggingface/diffusers

diffusers 集成在发布当天通过一个专门的 PR 合入，因此早于 9 月 20 日的 PyPI 版本不包含这个 pipeline 类。

第 1 步：文生图

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16
).to("cuda")

image = pipe(
    prompt='A neon shop sign that reads "QWEN IMAGE 2.1", rainy night, reflections on wet pavement',
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("t2i_example.png")

有两点值得注意。提示词把招牌上的文字放在引号里；Qwen 的文字渲染正是人们选择这一系列模型的原因，而给字面字符串加引号是沿用自早期版本的惯例。另外，seed 是显式指定的。在你打算测试的每个请求中都保持这一做法，因为固定的 seed 才能让图像接口具备可复现性，从而可以对其断言。

需要非正方形输出时，请从支持的尺寸表中选用 width 和 height：

比例	尺寸
1:1	2048 x 2048
4:3 / 3:4	2400 x 1792 / 1792 x 2400
3:2 / 2:3	2528 x 1696 / 1696 x 2528
16:9 / 9:16	2752 x 1536 / 1536 x 2752

第 2 步：透明输出

透明效果由提示词驱动。README 推荐的措辞需要按字面使用，所以请直接照用：

image = pipe(
    prompt=(
        "This is an RGBA image with transparency. A cute cartoon dragon sticker. "
        "The image has alpha channel and the background is transparent."
    ),
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("transparent_example.png")

不要直接相信结果，要检查：

assert image.mode == "RGBA", image.mode
alpha = image.getchannel("A")
print("transparent pixels:", sum(1 for p in alpha.getdata() if p == 0))

这个断言就是你稍后要搬进 Apifox 的第一个测试。当你要求 RGBA 却静默返回 RGB 的模型，是一个用户会比你先发现的 bug。

第 3 步：编辑，单张图或最多十张图

传入 image 时，同一个 pipeline 就执行编辑：

from PIL import Image

input_image = Image.open("input.png")
edited = pipe(
    prompt="Change the background to a sunset beach",
    image=input_image,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
edited.save("edit_example.png")

需要多张参考图时传入列表（发布公告中的上限是 10）：

refs = [Image.open(f"ref_{i}.png") for i in range(3)]
result = pipe(
    prompt="These three characters are sitting around a campfire in a forest",
    image=refs,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
result.save("multi_ref_example.png")

发布公告中给出了三种局部编辑方式：在提示词中按颜色引用的彩色圆圈、手绘标注，或者把未改动的原图与单独的 mask 图像作为两个输入传入。README 没有提供专门的 mask 示例，因此建议先试双输入形式：image=[original, mask]，并在提示词中描述 mask 区域内要放入的内容 [VERIFY against the README once a mask example lands]。

编辑也体现了 2.1 在速度上的优化。参考图和指令在去噪步骤中保持不变，因此模型只计算一次它们的 key-value cache 并重复使用。十张参考图的成本明显低于一张的十倍。

第 4 步：在你的 GPU 上跑起来

Qwen 没有公布显存占用数据。如果 bf16 pipeline 装不下，README 提供了这些方案：

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

在服务化部署方面，README 指向 vLLM-Omni（支持 FP8）、SGLang 和 LightX2V。如果你完全不想写 Python，ComfyUI 提供原生支持和一个模板工作流。如果你没有 GPU，免费方案包括在线 demo 和 Qwen Chat。

第 5 步：封装成 HTTP API

应用代码不应该直接 import diffusers。把 pipeline 放到一个小服务后面，它就有了可以版本化、mock 和测试的契约。这个 FastAPI 封装大约 40 行，返回 PNG 字节：

# server.py
import io, torch
from fastapi import FastAPI, UploadFile, File, Form
from fastapi.responses import Response
from PIL import Image
from diffusers import QwenImage21Pipeline

app = FastAPI()
pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16
).to("cuda")

SIZES = {"1:1": (2048, 2048), "16:9": (2752, 1536), "9:16": (1536, 2752)}

@app.post("/v1/images")
async def generate(
    prompt: str = Form(...),
    aspect: str = Form("1:1"),
    transparent: bool = Form(False),
    seed: int = Form(42),
    steps: int = Form(40),
    references: list[UploadFile] = File(default=[]),
):
    if transparent and not prompt.startswith("This is an RGBA image"):
        prompt = ("This is an RGBA image with transparency. " + prompt +
                  " The image has alpha channel and the background is transparent.")
    refs = [Image.open(io.BytesIO(await f.read())) for f in references[:10]]
    w, h = SIZES.get(aspect, SIZES["1:1"])
    kwargs = dict(prompt=prompt, num_inference_steps=steps,
                  generator=torch.Generator("cuda").manual_seed(seed))
    if refs:
        kwargs["image"] = refs if len(refs) > 1 else refs[0]
    else:
        kwargs.update(width=w, height=h)
    image = pipe(**kwargs).images[0]
    buf = io.BytesIO()
    image.save(buf, format="PNG")
    return Response(buf.getvalue(), media_type="image/png",
                    headers={"X-Image-Mode": image.mode, "X-Seed": str(seed)})

用 uvicorn server:app --port 8000 运行它。两个响应 header，X-Image-Mode 和 X-Seed，是为了让测试无需解码 PNG 就能检查透明度和可复现性。这是封装中唯一带有产品特色的设计，其余部分就是一个普通的 multipart 接口。

第 6 步：在 Apifox 中测试该接口

现在它就是一个 API 了，你用于 gpt-image-2.5 API 或 Nano Banana 2 API 的那套方法在这里同样适用。在 Apifox 中：

创建接口为 POST {{base_url}}/v1/images，使用 multipart body：prompt、aspect、transparent、seed、steps，以及可重复的 references 文件字段。把 base_url 放进环境，这样同一个集合就能指向你的笔记本、GPU 机器或 mock。
发送一个文生图请求，使用 seed=42 和霓虹招牌提示词。确认返回 200、Content-Type: image/png 和 X-Image-Mode: RGB。
在后置操作中添加断言：状态码为 200，X-Image-Mode 等于 RGBA（当 transparent=true 时），响应 body 大小高于下限（一张 2K 的 PNG 返回时只有 2 KB，说明是空白图），并且 X-Seed 与你发送的值一致。
用同样的方式发送透明度用例和三张参考图的编辑用例，在文件字段中附上图片。各自保存为测试用例。
把它们作为测试场景运行，按计划或放在 CI 中。当你换成量化版本或未来的 2.2 时，这套测试能在几分钟内告诉你透明度是否仍然有效、seed 是否仍可复现。
GPU 忙的时候可以对它做 mock。Apifox 的高级 mock 会按同样的契约返回一张固定的 PNG，前端可以继续开发。

由于 Apifox 还能根据你定义的接口自动生成 OpenAPI 规范和文档，这个封装一旦跑通，它的契约就立刻可以被共享。

可选：用 PE-T2I 改写提示词

这个 demo Space 使用 Qwen-Image-2.1-PE-T2I 把一句话请求转成长结构化提示词，这是一个微调过的 Qwen3.5-VL 9B，返回包含扩展后英文提示词和建议宽高比的 JSON。可以把它作为第二个服务放在 /v1/images 前面，也可以跳过它自己写完整提示词。如果加上它，请单独测试：它是一个带 JSON 契约的文本 API，改写器出问题会生成看起来很像是生成器 bug 的糟糕图片。

常见问题

一个 pipeline 同时负责生成和编辑吗？是的。QwenImage21Pipeline 在只传提示词时执行生成，在传入 image（单张 PIL 图像或最多 10 张的列表）时执行编辑。

如何得到透明 PNG？在提示词开头写“This is an RGBA image with transparency”，并说明背景是透明的。检查结果中的 image.mode == "RGBA"。

推荐的参数设置是什么？根据 README，是 40 个推理步和 bfloat16。2.1 没有列出 guidance 值；更早的 Qwen-Image 版本使用 true_cfg_scale=4.0，如果输出看起来引导不足可以试这个值 [VERIFY]。

可以用于商业产品吗？按默认许可不可以。Qwen-Image-2.1 采用 Qwen Research License 发布；商业使用需要从 Qwen 获得单独许可。详情见 Qwen-Image-2.1 是什么。

有没有托管 API 可用？Qwen Image 3.0 和 3.0 Pro 是阿里巴巴的托管图像模型，按张计费。2.1 与 3.0 的对比涵盖了何时自托管、何时租用。

下一步

现在你已经有了四个可用的调用、一个契约稳定的封装，以及一套检查这个模型最关键两个属性（透明度和可复现性）的测试。接下来，判断研究许可是否适合你的用途，或者托管的 3.0 API 是否更合适，并把两者都放在同一个 Apifox 集合中，这样切换只是改一下 base URL，而不需要重写。

HiFox：将 Agent 变成真正的队友

另外，我们也在思考，AI 如何从个人提效走进团队协作。

HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。

👉 立即体验 HiFox：https://hifox.com

如何使用 Qwen-Image-2.1：diffusers 代码、透明背景输出与可实测的 API