Qwen-Image-2.1の使い方：Diffusersコード、背景透過、試せるAPI

Qwen-Image-2.1は、Alibabaが2026年9月20日にリリースしたオープンウェイト画像モデルです。これは、テキストから画像を生成し、最大10枚の参照画像を使った編集、そしてネイティブな透明（RGBA）出力を処理できる70億パラメータのジェネレーターです。このガイドでは、pip installから動作するHTTPエンドポイントの構築までを説明します。GitHub READMEにある4つの参照コードパス、重要な設定、他の画像APIと同様にモデルを呼び出せるようにするための小さなFastAPIラッパー、そしてプロンプトの変更やモデルの更新がアプリケーションを壊さないように、Apidogでそのエンドポイントをテストする方法について解説します。

まず背景を知りたい場合は、「What is Qwen-Image-2.1」でアーキテクチャとライセンスについて説明しています。ライセンスの概要は、Qwenから別途商用契約を取得しない限り、研究および非商用目的でのみ使用可能です。以下の内容はすべて評価用として問題ありません。

ボタン

始める前に

要件	詳細
Pythonパッケージ	`torch>=2.4.0`, `transformers>=5.17`, GitHub mainからの`diffusers`, `accelerate`, `pillow`
パイプラインクラス	`QwenImage21Pipeline` (生成と編集用の一つのクラス)
ウェイト	Qwen/Qwen-Image-2.1, bf16 safetensors
GPU	Qwenによる指定なし; 参照コードはbf16で1つのCUDAデバイスを対象とし、`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リリースではパイプラインクラスは含まれていません。

ステップ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")

注意点が2つあります。プロンプトでは看板のテキストが引用符で囲まれています。Qwenのテキストレンダリングは、このモデル群が選ばれる理由であり、リテラル文字列を引用符で囲むのは以前のリリースからの慣習です。そして、シードは明示的です。テストするすべてのリクエストでこの方法を維持してください。なぜなら、固定されたシードこそが画像エンドポイントを検証可能なほど再現性のあるものにするからです。

正方形以外の出力が必要な場合は、サポートされている表から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))

このアサーションは、後でApidogに移植する最初のテストになります。RGBAを要求したときにサイレントにRGBを返すモデルは、ユーザーがあなたより先に見つけるバグです。

ステップ3: 1枚または最大10枚の画像で編集

imageを渡すと、同じパイプラインが編集を行います:

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

ローンチ投稿では、ローカル編集は3つの方法で機能します。プロンプトで色によって参照する色付きの円、描画された注釈、または未修正のオリジナル画像と別々のマスク画像を2つの入力として渡す方法です。READMEには専用のマスク例がないため、最初に試すべきは2入力形式です: image=[original, mask]と、マスクされた領域に何が入るかを記述するプロンプトを組み合わせます[マスクの例が公開されたらREADMEと照合して確認してください]。

編集は、2.1の高速化が表れる部分でもあります。参照画像と指示はノイズ除去ステップ全体で静的であるため、モデルはそれらのキーバリューキャッシュを一度計算し、再利用します。10枚の参照画像を使っても、1枚の画像の10倍のコストがかかるわけではありません。

ステップ4: GPUに適合させる

QwenはVRAMの数値を公開していません。bf16パイプラインが適合しない場合、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がない場合は、ホスト型デモとQwen Chatをカバーする無料オプションがあります。

ステップ5: HTTP APIとしてラップする

アプリケーションコードはdiffusersをインポートすべきではありません。パイプラインを小さなサービスの後ろに配置し、バージョン管理、モック、テストが可能な契約を持つようにします。この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で実行します。X-Image-ModeとX-Seedという2つのレスポンスヘッダーは、テストがPNGをデコードせずに透明性と再現性をチェックできるようにするために存在します。これはラッパーにおける唯一の製品固有の選択であり、残りは単純なマルチパートエンドポイントです。

ステップ6: Apidogでエンドポイントをテストする

これでAPIになりました。そのため、gpt-image-2.5 APIやNano Banana 2 APIに適用するのと同じ規律がここに適用されます。Apidogでは、次の手順を実行します:

エンドポイントを作成します: POST {{base_url}}/v1/imagesとして、マルチパートボディを持つエンドポイントを作成します。ボディにはprompt、aspect、transparent、seed、steps、および繰り返し可能なreferencesファイルフィールドを含めます。base_urlを環境変数に設定し、同じコレクションがあなたのラップトップ、GPUボックス、またはモックを指すようにします。
テキストから画像を生成するリクエストを送信します: seed=42とネオンサインのプロンプトでリクエストを送信します。200、Content-Type: image/png、およびX-Image-Mode: RGBを確認します。
ポストプロセッサーでアサーションを追加します: ステータスが200であること、transparent=trueのときにX-Image-ModeがRGBAであること、レスポンスボディサイズが最低限のサイズを超えていること（2KBで返される2K PNGは空白画像であるため）、そしてX-Seedが送信した値と一致することを確認します。
透明度ケースと3つの参照画像を使った編集を送信します: 同様に、ファイルフィールドに画像を添付して送信します。それぞれをテストケースとして保存します。
スケジュールまたはCIでテストシナリオとして実行します: 量子化されたビルドや将来の2.2に切り替えた際、透明度がまだ機能しているか、そしてシードがまだ再現可能であるかを、このスイートが数分で教えてくれます。
GPUがビジーの間はモックします: Apidogのスマートモックは、同じ契約に対して定型のPNGを返すため、フロントエンドは開発を継続できます。

Apidogは定義したエンドポイントからOpenAPI仕様とドキュメントも生成するため、ラッパーの契約は動作した瞬間に共有可能になります。Apidogをダウンロードし、上記のエンドポイントをインポートして始めましょう。

オプション: PE-T2Iによるプロンプトリライト

デモスペースでは、Qwen-Image-2.1-PE-T2Iを使用して一行のリクエストを構造化された長いプロンプトに変換します。これは、拡張された英語プロンプトと推奨アスペクト比をJSONで返す微調整されたQwen3.5-VL 9Bです。これを/v1/imagesの前に2番目のサービスとして実行するか、スキップして自分で完全なプロンプトを作成することもできます。もし追加する場合は、個別にテストしてください。これはJSON契約を持つテキストAPIであり、壊れたリライターはジェネレーターのバグのように見える悪い画像を生成します。

よくある質問

1つのパイプラインで生成と編集の両方ができますか？ はい。QwenImage21Pipelineはプロンプトのみで呼び出されたときに画像を生成し、image（単一のPIL画像または最大10枚の画像のリスト）を渡すと画像を編集します。

透明なPNGを取得するにはどうすればよいですか？ プロンプトを「This is an RGBA image with transparency」で始め、背景が透明であると記述します。結果でimage.mode == "RGBA"を確認してください。

推奨設定は何ですか？ READMEによると、40推論ステップとbfloat16です。2.1のガイドライン値は記載されていません。以前のQwen-Imageリリースではtrue_cfg_scale=4.0を使用していたので、出力がアンダーガイドに見える場合はこれを試してみてください[確認]。

商用製品でこれを使用できますか？ デフォルトのライセンス下では使用できません。Qwen-Image-2.1はQwen Research Licenseのもとで提供されており、商用利用にはQwenからの別途ライセンスが必要です。詳細は「What is Qwen-Image-2.1」をご覧ください。

代わりにホストされたAPIはありますか？ Qwen Image 3.0および3.0 Proは、Alibabaが提供する画像ごとの料金設定のホスト型画像モデルです。2.1と3.0の比較では、セルフホストすべき場合とレンタルすべき場合について説明しています。

次は何をすべきか

これで、4つの動作する呼び出し、安定した契約を持つラッパー、そしてこのモデルにとって最も重要な2つのプロパティである透明性と再現性をチェックするテストスイートが手に入りました。次に、研究ライセンスがあなたの使用に適しているか、またはホスト型3.0 APIの方がより適しているかを判断し、どちらも同じApidogコレクションの後ろに置いておくことで、切り替えがベースURLの変更だけで済み、書き直しを必要としないようにしましょう。