hiapi API で qwen-image-2.0 を使ってEC商品画像を生成する

qwen-image-2.0 は Alibaba の第2世代テキスト-to-画像モデルで、hiapi の /v1/tasks インターフェース経由で提供され、価格は1枚あたり $0.025、デフォルト出力は 2K です。EC の観点で特に興味深い点が2つあります。この価格帯では、中国語の文字レンダリングが現在のすべてのテキスト-to-画像モデルの中で最もクリーンであること。そして、長く詳細な商品ブリーフに対するプロンプトへの追従性が非常に安定していること——これはまさに越境リストが本当に必要としているものです。

本ガイドはこのワークフローの実行可能なバージョンです。すべての API 呼び出しはターミナルにそのまま貼り付けられる内容で、プロンプトテンプレートはライブエンドポイントでレンダリングを検証済みであり、1枚あたりの価格は HiAPI 料金の最新の数字です。ここに理論的な内容はありません。コストの数字は qwen-image-2.0 が実際に受け付ける size 値に基づいており、マーケティング上の数字ではありません。

越境商品画像に qwen-image-2.0 を選ぶ理由

200 SKU を一度にマーケットプレイスのリスティングへ投入するとき、重要なことが3つあります。

1. 中国語の文字レンダリング。中国本土、香港、台湾、または東南アジア向けに販売されるほとんどの EC リスティングは、パッケージ、バナー、ラベルに読みやすい中国語が必要です。qwen-image-2.0 は hiapi 上で唯一、「瓶のラベルに太字セリフ体の中国語で玫瑰精华水と書かれている」といったプロンプトを書くと、モデルが指定したとおりの位置に指定したとおりの字形をレンダリングするモデルです。
2. 長い商品ブリーフへのプロンプト追従性。EC のブリーフは長くなります。素材、色の16進コード、表面仕上げ、光の方向、影の形、背景色、カメラアングル。ブリーフが長くなっても qwen-image-2.0 は全体の一貫性を保ちます——失敗モードは通常、小道具が1つ欠ける程度で、商品を捏造することはありません。
3. バリエーション爆発に耐えられるコスト帯。典型的な SKU ページは4〜6枚の画像（スタジオ撮影風、シーン、俯瞰、スケール比較、2つのバリエーション）を望みます。1枚 $0.025 なら1 SKU あたり $0.10〜$0.15です。200 SKU の新商品投入で $20〜$30。このコスト帯こそが、「すべてをゼロから生成する」を、部分的な撮影を外注してストックで補うより安くしているのです。

プロンプトごとのチューニング実験の詳細と、EC ではなくスタイル指向の6つのレシピの実践については、姉妹記事 qwen-image-2.0 プロンプトレシピをご覧ください。本記事はカタログのユースケースに焦点を当てています。

hiapi 上の qwen-image-2.0 の入力スキーマ

qwen-image-2.0 は統一された /v1/tasks インターフェースで動作し、これは hiapi が現在提供する唯一の画像エンドポイントでもあります。コードを書く前に、正しく理解しておくべき特殊ルールが1つあります。

• サイズパラメータの名前は size です——aspect_ratio でも resolution でも image_size でもありません。hiapi 上の他のモデル（nano-banana、flux シリーズ）は aspect_ratio を受け付けますが、qwen-image-2.0 は受け付けません。
• size 内の区切り文字は * で、x ではありません。"size": "2688x1536" は 400 を返します。"size": "2688*1536" なら正常に動作します。
• 受け付ける size 値は5つだけです。いずれも 2K です。

アスペクト比	size 値	用途
16:9（約 1.75:1）	2688*1536	メインビジュアル、バナー、リスティングカバー
4:3（約 1.37:1）	2368*1728	雑誌風見開き、2カラム広告枠
1:1	2048*2048	正方形のスタジオ撮影風画像、マーケットプレイスのサムネイル
3:4（約 0.73:1）	1728*2368	モバイルファーストの商品ページ
9:16（約 0.57:1）	1536*2688	縦型動画のカバー、TikTok/Reels の静止画

その他の値を送信すると、API はエラー内にリテラルの許可リストを返します。

{"code": 400, "message": "invalid input: size: value must be one of '2688*1536', '2368*1728', '2048*2048', '1728*2368', '1536*2688'"}

このエラーメッセージを権威ある情報源として扱ってください——将来そこに新しい値が現れれば、プラットフォームがそのスキーマを拡張したということです。

実行可能なリクエスト

呼び出し面はエンドポイントが2つだけです。POST /v1/tasks でキューに投入し、GET /v1/tasks/{taskId} でポーリングします。以下は下のスタジオ撮影風画像を生成する最小のリクエストです。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "input": {
      "prompt": "A clear glass cosmetic dropper bottle on a clean off-white seamless paper background, soft daylight from camera left, gentle elliptical shadow, the label reads 玫瑰精华水 in bold serif Chinese with a small line of English Rose Essence Water below, the liquid inside has a faint pink tint, studio product photography, sharp focus on the label, no other props, square 1:1 composition",
      "size": "2048*2048"
    }
  }'

レスポンス：

{"code": 200, "data": {"taskId": "tk-hiapi-01KW8R..."}, "message": "success"}

ポーリング用：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KW8R... \
  -H "Authorization: Bearer $HIAPI_TOKEN"

status フィールドは handling → archiving → success と遷移します。私たちのテスト実行では、2K で1枚あたりの合計実時間は25〜45秒でした。status が success になると、output[0].url に画像が保存されています——ただしこれは temp.hiapi.ai を指し、expireAt の Unix タイムスタンプが付いているので、すぐにダウンロードしてください。ページに埋め込んだりデータベースに固定したりしないでください。数時間で 404 になります。

このスタジオ撮影プロンプトをライブエンドポイントで実行すると、ガラスのドロッパー瓶が生成され、ラベルには中国語の文字 玫瑰精华水 がきれいにレンダリングされ、そのすぐ下に小さめのウェイトで英語のRose Essence Waterが表示されます。モデルは2行のテキストを正規のラベル領域に配置し、プロンプトにレイアウトのヒントは一切不要です——「the label reads X」という言い回しだけで十分です。

SKU 表をアップロード済みスタジオ撮影風画像に変える Python ループ

これは本ページで画像を生成する際に実行したループです。(slug, prompt, size) タプルのセットを受け取り、控えめな並列上限で同時に送信し、各タスクを完了までポーリングし、結果をダウンロードし、webp としてあなたのストレージにアップロードします。このパターンは意図的に退屈に書かれています——requests と concurrent.futures——なぜなら面白い部分はモデルだからです。

import os, time, io, requests, concurrent.futures as cf
from PIL import Image

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def submit(prompt, size):
    r = requests.post(BASE, headers=H, json={
        "model": "qwen-image-2.0",
        "input": {"prompt": prompt, "size": size},
    }, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, deadline_s=240):
    deadline = time.time() + deadline_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30)
        d = r.json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d.get('error')}")
        time.sleep(4)
    raise TimeoutError(f"task {task_id} not done in {deadline_s}s")


def render_one(item):
    slug, prompt, size = item
    task_id = submit(prompt, size)
    url = wait(task_id)
    png = requests.get(url, timeout=60).content
    buf = io.BytesIO()
    Image.open(io.BytesIO(png)).convert("RGB").save(buf, "WEBP", quality=88, method=6)
    return slug, buf.getvalue()


JOBS = [
    ("packshot-rose-water",  "A clear dropper bottle, label 玫瑰精华水…", "2048*2048"),
    ("packshot-tea-canister","A pale grey ceramic tea canister, label 龙井…", "2048*2048"),
    # … 200 more rows from your sheet …
]

with cf.ThreadPoolExecutor(max_workers=6) as pool:
    for slug, webp in pool.map(render_one, JOBS):
        with open(f"out/{slug}.webp", "wb") as f:
            f.write(webp)
        print(f"saved {slug}.webp ({len(webp)} bytes)")

このコードについて、コード自体からは見えない小さな注意点がいくつかあります。

• max_workers=6 は私たちが観察したスイートスポットです。8〜10 になると、キューの深さがスループットではなく追加の遅延として現れ始めます。モデル側はアカウントごとに並列を公平に配分しているようです。
• 保存前に品質 88 で webp に変換します。このエンドポイントが生成する 2K png は約 3〜4 MB ですが、webp は 200〜400 KB になり、商品ページのサイズでは視覚的に完全に同一です。転送が安くなり、しかもモデル自体が大量のテクスチャをすでにエンコードしているため、JPEG はこれらのテクスチャの扱いが苦手です。
• 一時 URL は一度しかダウンロードできません。アップロード手順が失敗した場合（S3 の障害、ネットワークの揺らぎ）、再レンダリングする必要があります——同じタスクの出力を取得する2回目のチャンスはありません。

EC に適した6つのプロンプトパターン

これらは、より冗長な代替案との社内 A/B 比較を経て生き残ったプロンプトの形です。中国語の商品ラベルを使う英語話者向けに書かれています——これが最も一般的な越境シナリオです。

パターン 1 —— 中国語ラベル付きの単品スタジオ撮影風画像

デフォルトの商品画像です。背景色は平易な英語で指定し、ラベルの文字はリテラルの中国語で指定して英語でフォントファミリーを添え、光源を1つ指定します。

A pale grey ceramic tea canister on a clean off-white seamless paper background. The label reads 龙井 in bold black serif Chinese with the small English subtitle Longjing Green Tea below. Soft daylight from camera right, gentle elliptical shadow, no other props. Sharp focus on the label, studio product photography, square 1:1 composition.

効いているのは2点、「reads X in bold serif Chinese」（qwen-image-2.0 はこれを想定されるラベル位置に置きます）と「sharp focus on the label」（モデルに文字を装飾ではなく焦点として扱わせます）です。

パターン 2 —— 空の皿を中心に組み立てるシーン画像

シーン撮影では、商品を先にではなく、シーンを先に説明し、最後に商品をそこに入れます。モデルは商品よりもシーンでぶれやすいので、シーンを先に固定します。

A wooden Japanese-style table near a wide window in late-morning daylight. The window casts a soft rectangle of light onto the table. In the center of the table is the pale grey ceramic tea canister from the previous shot, with a small wisp of steam rising from a cup beside it. Loose tea leaves are scattered to the right. Wabi-sabi aesthetic, soft shadows, shallow depth of field with focus on the canister. 16:9 widescreen composition.

私たちのテストレンダリングでは、缶には文字 龙井 が付き、そのすぐ下に英語のLongjing Green Teaがありました——スタジオ撮影風画像と同じラベルの規律です——蒸気、散らばった茶葉、窓の光もすべて説明どおりに表現されました。

パターン 3 —— 1回のレンダリングでのカラーバリエーショングリッド

バリエーションが同じ商品形状を共有する場合、3回ではなく1回の呼び出しでグリッド全体をレンダリングできます。安くなり、しかも各セルの照明は構造上一致します。

Three pairs of low-top canvas sneakers shot from a slight top-down angle, arranged in one horizontal row on a clean light-grey seamless background. From left to right: dusty rose, sage green, ivory cream. Identical sneaker silhouette, identical lighting, identical shadow. Each pair faces the camera with toes pointing forward. Studio product photography, 1:1 composition, evenly spaced.

このパターンなら、各バリエーションを個別にレンダリングして後から照明を合わせようとする必要はありません。「identical sneaker silhouette, identical lighting, identical shadow」という制約が、列全体を統一する鍵です。

パターン 4 —— バイリンガルプロモーションバナー

Shopee、Lazada、タオバオの共同ブランドキャンペーンでは、通常、同じ画像内に中国語の見出しと英語のサブ見出しの両方が必要です。qwen-image-2.0 は hiapi 上で唯一、1回のレンダリングで両方を正しく実現できるモデルです。

A horizontal ecommerce promotional banner on a soft pink gradient background. The main headline reads 双十一大促 in large bold black sans-serif Chinese in the center-left. Below the Chinese headline in smaller dark grey English serif: Double 11 Sale — Up to 50% Off. To the right is a clear glass dropper bottle of pink serum with a small white label. Subtle confetti texture in the background, clean and modern, 16:9 widescreen.

これを安定して機能させるコツは、中国語をプロンプトの先頭に置き、「large bold」という修飾語を付け、次に英語に「smaller」という修飾語を付けることです。順序を逆にすると、モデルは英語も見出しサイズにしてしまいがちです。バナー内の商品ラベルは緩めてよい部分です——私たちのテストレンダリングでは、文字を明示しなかったため qwen は瓶に汎用的な「Vitamin C Serum」ラベルを選びました。ブランドキャンペーンでは、リテラルのラベル文字をプロンプトに含めるか、後工程で本物のラベルを合成してください。

パターン 5 —— 越境マーケットプレイスのリスティングカード

Amazon や Tmall のリスティングタイルのように見える複合素材——商品、タイトル、価格、バッジ——の場合、プロンプトは写真のブリーフではなくレイアウトのブリーフのように読める必要があります。

A square ecommerce listing card on a white background. In the top two-thirds, a clear glass dropper bottle of pink rose-essence water labeled 玫瑰精华水 / Rose Essence Water. In the bottom third, on the left, the price 99 元 in large bold black Chinese characters with a small English subtitle Rose Essence 30ml below. On the right, a small green badge that reads 新品 in white. Clean modern layout, soft drop shadow under the product, 4:3 composition.

リスティングでは 1:1 ではなく 4:3（2368*1728）でレンダリングしてください——ほとんどのマーケットプレイスのリスティングコンポーネントのメインビジュアル枠は 4:3 で、正方形だと不格好なクロップになります。

パターン 6 —— パーソナライゼーションのためのオンデマンド生成

最後のパターンはユニットエコノミクスを変えます。1回のレンダリングが3セント未満になれば、キャンペーン用バナーを事前レンダリングするのをやめ、リクエスト時に顧客ごとにレンダリングできます——「王様、毎月のセットの準備ができました」のように、顧客の実名をバナーに焼き込めます。名前のハッシュでキャッシュし、TTL を設定すれば、わずかな CDN 請求でパーソナライズされたバナー画像が得られます。

制約はレイテンシです。1回25〜45秒のレンダリングは同期リクエストの流れには遅すぎますが、メール送信やプッシュ通知にはまったく問題ありません——キューに入れたときに生成し、メッセージ送信時に埋め込みます。

qwen-image-2.0 が苦手なこと

公平を期すため、以下の4つの作業は同じ /v1/tasks エンドポイント上の他のモデルに任せています。

• モーションブラー付きの手持ち撮影。スタジオ撮影風画像はスイートスポットです。演出していないように見えるもの——UGC 風、わずかな動き、不完全な構図——が必要なら、nano-banana-pro を試してください。「ラフな」構図の理解が優れています。
• ピクセル単位で一致する商品バリエーション。qwen-image-2.0 は呼び出し間で類似したバリエーションをレンダリングしますが、5つの異なる照明設定でまったく同じドロッパー瓶が必要なら、参照画像による条件付けができるモデルが必要です。hiapi 上の純粋なテキスト-to-画像モデルは、呼び出し間のピクセル一致を保証できません。
• 全身のフォトリアルな顔。アップの顔は問題ありませんが、全身や集合写真では顔の細部が柔らかくなりがちです。人物中心の EC——服の試着、美容デモ——では、qwen-image-2.0 を参照条件付けの動画モデルと組み合わせて動きのあるカットに使ってください。
• サブ秒のターンアラウンド。同期リクエストの内側ループで画像を生成する必要がある場合（ユーザーが画面の前で待っている）、25〜45秒は長すぎます。flux-schnell は約5秒で返し、1枚 $0.005 ですが、中国語の文字はレンダリングしません。まずレイテンシ予算で選んでください。

200 SKU 新商品投入の実際のコスト

代表的なケースで、エンドツーエンドのワークフローの数字を計算します。

ステップ	数量	単価	合計
SKU ごとのメインビジュアル/スタジオ撮影風画像	200 × 1	$0.025	$5.00
SKU ごとのシーン画像	200 × 1	$0.025	$5.00
SKU ごとのバリエーショングリッド（1回のレンダリングで約3バリエーション）	200 × 1	$0.025	$5.00
カテゴリごとのバイリンガルバナー（10カテゴリ）	10 × 1	$0.025	$0.25
SKU ごとのリスティングカード	200 × 1	$0.025	$5.00
画像生成の総コスト	810 回のレンダリング	—	$20.25

現在の hiapi 料金では、200 SKU の越境リリースの画像予算全体は約 $20 です。同じ作業をプレミアムモデル（1枚 $0.04 から）で行うと $30〜$140 になり、しかも1枚あたりの実行時間が長くなります。これが qwen-image-2.0 が埋めることを目指しているギャップです。中国語を理解する EC の作業を、レンダリング回数を数えなくなるほど低いコスト帯で実現します。

次にどこへ進むか

• qwen-image-2.0 プロンプトレシピを読んで、EC 専用ではないスタイル指向の6つのレシピを学んでください。
• コストの数字は hiapi 料金ページを権威ある情報源としてください——qwen-image-2.0 は現在1枚 $0.025 ですが、そのページを優先してください。
• 中国語の文字が不要なレイテンシ重視のフローでは、flux-schnell に切り替え、同じ /v1/tasks の形をそのまま使ってください——比較は FLUX.1 schnell を使ったEC商品画像の生成をご覧ください。

統一された /v1/tasks エンドポイントの意義は、モデルの切り替えが文字列1つの変更で済むことです。qwen-image-2.0 用のループを一度組み立てれば、同じ Python スクリプトで "model" フィールドを編集し、そのモデルの size スキーマに合わせるだけで、hiapi 上の任意の画像モデルに対してレンダリングできます。