使用ガイド
HiAPI API で qwen-image-2.1-turbo を使って EC 商品画像を生成する
開発者向けの素早いカタログビジュアルワークフロー:透過 PNG 出力と実行可能な API リクエスト
このページの内容
qwen-image-2.1-turbo が適する場面
商品カタログの画像作業は、見た目はクリエイティブな問題だが、実態はスループットの問題である。単一のメイン画像なら手作業で作り込めるが、数千の SKU を抱える店舗には、一貫した構図、予測可能な納期、そして既存のアセットパイプラインにそのまま接続できる出力が必要だ。どの画像モデルを選ぶかによって、パイプラインをどれだけ作り直すかが決まる。
通常、この判断を左右する基準は三つある:
- 負荷時のレイテンシ。毎夜のカタログ処理はバッチ処理である。対話的な場面で良好な性能を発揮するモデルでも、10,000 SKU のリフレッシュを苦痛なものにし得る。
- 出力形式の適合性。合成段階でアルファチャンネルが必要なのに、モデルが不透明な画像しか返さなければ、分割ステップを自分で追加しなければならない。
- 商品説明の言葉に対するプロンプト性能。商品プロンプトは短く、具体的で、繰り返しが多い——こうしたプロンプトを安定して扱えるモデルは、オープンエンドなアート系プロンプトで優れるモデルに勝る。
本ガイドは最初の二つの基準と、両者をつなぐリクエストパターンに焦点を当てる。turbo バリアントが商品画像パイプラインのどこに位置づけられるか、透過 PNG 出力が後処理チェーンをどう変えるか、そして worker にそのまま組み込めるリクエストを提示する。最後に、バッチへ拡張する際に注意すべき点と、テキスト駆動の生成が適さない場合のイメージ・トゥ・イメージ手法との簡単な比較を述べる。

透過 PNG 出力と後処理チェーン
商品画像パイプラインは四つの段階として捉えられる:リクエスト構築 → 生成 → 出力処理 → 公開。turbo バリアントは意図的な賭けである:第二段階をカタログ規模を支えられるほど高速かつ安価にし、そのぶんエンジニアリングの予算を第一段階と第三段階に振り向けられるようにする。
正しい第一選択となる場合
次のような場合は qwen-image-2.1-turbo を選ぶ:
- プロンプトが構造化されていて再利用可能——カテゴリごとに一つのテンプレートがあり、素材、色、角度、背景の意図を差し込むスロットが用意されている。
- SKU ごとに多数のバリエーション(角度、配色、シーン)が必要で、作り込まれた一枚絵は求めていない。
- 下流の合成がすでに自動化されており、完成されたシーンよりもクリーンな切り抜きのほうが価値が高い。
- 参照画像を導入する前に、テキスト駆動のベースラインを得ておきたい。
より強力なモデルが必要となる場合
ある SKU が参照写真と厳密に一致する高度に特定的な構図を必要とする場合や、ボトルネックが数量ではなく複雑なシーンでの出力品質にある場合は、turbo 階層は適切な既定の選択肢ではない。その場合は turbo でカタログの大半のバリエーションを処理し、少数のメイン画像素材だけをより重い生成パスに回す——パイプラインの形態はそのままに、モデル識別子だけを差し替える。
差し替え可能なモデルスロットを設計する
turbo 階層は規模を主眼とするため、モデル名はコードベースの各所に散らばるハードコードされた定数ではなく、設定として扱うべきだ。worker の起動時に IMAGE_MODEL 環境変数を読み込むようにすれば、リクエストのコードを変更することなく、一部のカテゴリで別モデルを A/B テストできる。この判断こそが、本ガイドの残りの内容を移植可能なものにする。

実行可能な HiAPI 商品画像リクエスト
透過 PNG はカタログパイプラインにおいて最もてこの効く出力の選択である。なぜなら、高コストなステップ——商品を背景から切り離すこと——を生成段階へ前倒しできるからだ。不透明なレンダリング結果を分割する代わりに、アルファチャンネル付きの素材を受け取り、自分で合成する。
下流で何が変わるか
アルファチャンネルがあれば、背景はモデリング上の関心事ではなくレンダリング上の関心事になる。同じ切り抜きを、白いスタジオ背景に置けば PDP のメイン画像に、ライフスタイルシーンに置けばマーケティング枠に、ブランドカラーの単色に置けばカテゴリタイルに——すべて一度の生成から作れる。これが核心的な経済性である:一つの商品素材から、複数の公開済みバリエーションが生まれる。
実運用では、次のステップを計画しておく:
- アルファチャンネルを検証する。画像に実際に有意なアルファチャンネルがあるか、被写体が画面の端で切れていないかを確認する。切り抜きが枠に接しているのは合成上の問題ではなく、生成の失敗である。
- キャンバスを正規化する。合成前に、一貫したキャンバス上で切り抜きのサイズを調整しパディングを加えて、SKU 間で位置が予測可能になるようにする。
- 公開先ごとに個別に合成する。背景プリセットをデータとして保持し(サイズ、色、任意の背景素材)、同じソース PNG から各公開先向けにレンダリングする。
- ソースを保存し、レンダリング結果を公開する。透過の原画像を正規の素材として永続化し、各合成バリエーションは再生成可能な派生物として扱う。
ファイルサイズのトレードオフに注意する:アルファチャンネルは PNG を大きくし、カタログのストレージではそれがバリエーションごとに積み重なる。CDN が WebP や AVIF を配信できるなら、公開時に変換しつつ PNG のソースは保持しておく。

バッチ処理への拡張と統合の落とし穴を避ける
以下はすべて HiAPI の統一インターフェース上で動作する——単一のベース URL、単一の認証情報、モデルをまたいで一貫したリクエスト形式。スキーマを確定する前に、正確なパラメータ一覧と現在のフィールド名を 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 とプロンプトのハッシュを各タスクのキーにして、リトライしたタスクが重複ではなく上書きになるようにする。
店頭に表示される前に検証する
生成と公開の間に検証ゲートを挿入する。低コストの自動チェックで不良出力の大半を捕捉できる:
- アルファチャンネルが存在し、被写体が端で切れていない。
- 解像度が、公開する最大サイズの最低要件を満たしている。
- 現在の素材との知覚ハッシュを取り、意図しない近似重複を検出する。
ゲートを通らなかったものは捨てるのではなくレビューキューへ送る。静かな失敗こそが、カタログを気づかぬうちに色の誤った商品で埋め尽くしていく原因である。
同時実行数の上限に注意する
バッチ処理はしばしば徐々にではなく突発的にレート制限に達する。worker の同時実行数を想定上限より低く抑え、その上限を設定可能にし、バックログはキューに吸収させる。レート制限に遭いながらも完走するパイプラインのほうが、行きつ戻りつするパイプラインより優れている。
リクエスト単位ではなく出力単位で予算を組む
課金は生成した出力に追随するため、SKU ごとに生成する素材数をコスト指標として追跡する。あるカテゴリが商品ごとに多数のバリエーションを生成し始めたら、それは請求書で気づくのではなく、意識的に行うプロンプト設計上の判断であるべきだ。
イメージ・トゥ・イメージ経路との比較
商品に使える写真がまだ存在しない場合——新 SKU がまだ撮影されていない、これまで撮ったことのない新色の商品がある、公開用のプレースホルダー素材が必要——には、テキスト駆動の生成が正しい既定の選択である。プロンプトが結果を完全に記述し、透過出力が分割ステップなしで合成可能な素材を提供する。
イメージ・トゥ・イメージ経路は入力を反転させる。参照画像を提供し、モデルはそれを基に作業する。これは実商品への忠実性が妥協できない場合にまさに必要となる:実際の縫い目、本物の金具の仕上げ、顧客が受け取る正確な色合いに一致させること。このモードでは、参照画像が生成を誠実に保つ制約となる。
ほとんどのカタログにとっての実用的な区分けは:
- turbo のテキスト・トゥ・イメージは規模向け——バリエーション、背景、カテゴリタイル、初期掲載用のプレースホルダー。
- イメージ・トゥ・イメージは、顧客が購入判断に用い、視覚的な正確さが決定的に重要なあらゆる場面向け。
両者は同じパイプラインの骨格を共有するため、切り替えは書き直しではなく、モデル識別子と入力フィールドの追加で済む。参照画像駆動の出力が必要なときは、qwen-image-3.0 イメージ・トゥ・イメージモデル を同じ worker に接続でき、プロンプトの隣に参照画像を添えるだけでよい。
まず一つのカテゴリで turbo 経路を走らせ、検証の通過率を測ってから段階的に拡張していく——接続すべきフィールドはモデルページに記載されている。