使用ガイド

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

Jul 2, 2026

ほとんどの画像モデルは商品を描けます。しかし商品をうまく描きかつ価格を正しく綴れるモデルははるかに少ないです。ECの場面——値札、プロモーションバナー、割引カード、パッケージラベル——では画像内の文字こそが鍵であり、文字化けが1文字でもあれば素材は却下されます。

z-image は hiapi 上の Turbo 級テキストto画像モデルで、まさにこのニッチな場面のために生まれました：高速なフォトリアル画像生成、画像内文字（英語と中国語）の正確さ、価格は1枚あたり $0.008——ほとんどの代替案の3分の1以下です。本ガイドのすべての画像は、その横に示されたまったく同じプロンプトから、以下でコピーするのと同じ /v1/tasks 呼び出しによって生成されており、各レンダリングはエンドツーエンドで約30〜60秒かかります。

商品画像になぜ z-image を選ぶのか

ECパイプラインにとって重要な3つの特性があり、z-image はその3つすべてで優れています：

文字レンダリング。 以下のプロンプトルールに従えば、プロモーションカード、物流バナー、ボトルラベルはすべての単語が正しく綴られた状態で返ってきます。
速度。 Turbo でチューニングされたモデルです。私たちのテストレンダリングは毎回1分をはるかに下回る時間で完了し、数百SKUの画像バッチ処理もコーヒー1杯の間に片付きます。
価格。 $0.008/枚（価格ページで確認済み）で、1,000枚のカタログ更新コストは $8 です。同じ作業を gpt-image-2（$0.03/枚）で行うと $30 かかります。

このモデルのより包括的な概要——キーの設定、一般的な例、いつ使うべきでないか——についてはZ-Image API：価格、APIキー、例、および適用場面を参照してください。本ガイドはECワークフローに焦点を当てています。

検証済みのAPIインターフェース

z-image は hiapi の非同期タスクエンドポイントで動作します。タスクを送信し、成功するまでポーリングし、出力をダウンロードします。私たちは実際のAPIに対して2つのスキーマ事実を確認しました（いずれもプラットフォーム上の一部の他のモデルとは異なります）：

input は prompt と aspect_ratio のみを受け付けます。 resolution フィールドを送ると HTTP 400（additional properties not allowed）が返ります——このフィールドを要求する gpt-image-2 とは異なります。
aspect_ratio は 1:1、4:3、3:4、16:9、9:16 のいずれかでなければなりません。 それ以外の値（私たちは 3:2 を試しました）は400で拒否され、有効な値が列挙されます。

出力解像度は比率に応じて固定です——私たちのレンダリング結果はPNGで返りました：1536×1536（1:1）、1344×768（16:9）、928×1232（3:4）、1728×1296（4:3）。

タスクを送信する

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

レスポンスはタスクIDを返します：

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

ポーリングしてダウンロードする

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

数秒ごとにポーリングし、data.status が success で data.output が存在するまで待ちます。fail は終端状態とみなしてください。実用的なヒント：生成直後、タスクは一時的に中間状態（私たちは archiving を観察しました）を報告し、その後でoutput配列が現れることがあります。したがってループはステータス文字列だけでなく出力URLの存在を条件にしてください。

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

すぐにダウンロードしてください。 output[0].url は expireAt タイムスタンプ付きの一時リンクです——タスク成功後すぐにバイトを自分のストレージ（S3/R2/CDN）に永続化してください。タスクが詰まっているように見える場合は、ここでハングまたはタイムアウトした hiapi タスクを診断する方法を紹介しています。

5つのECレシピ、実際の出力付き

以下のすべての画像は、示されたまったく同じプロンプトから生成された実際の z-image レンダリング結果です。一切の修正は加えていません。

1. 値札付きのメイン画像

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

文言に注意してください：表示文字は引用符で囲み、プロンプトはカードがこれらの単語のみを含むと述べています。最初の試行では文字をインラインで説明しました（「...reads exactly: SUMMER SALE on the first line and $19.99 on the second line」）、するとモデルは忠実に2行の間に単語「ON」を組版しました——指示語がレンダリング結果に漏れ出したのです。リテラル文字列は引用符で囲み、指示は引用符の外に置いてください。

2. ワイドなプロモーションバナー

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 を指定すると1344×768のバナーが得られ、店舗トップのヒーロー枠にそのまま収まります。

3. SNS向け縦型割引カード

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4（928×1232）はフィード投稿の形式に最も近い比率です。プラットフォームが要求する場合は、下流で4:5にトリミングできます。

4. 読めるパッケージラベル

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

これはこのセットで最も難しいテスト——曲面ガラス上の小さな文字——でしたが、ラベルは「10%」を含めてきれいに返ってきました。

5. カラーラインナップ（文字なし）

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

バリアント間で一貫した形状がカタログの帯として使える鍵です——z-image は1回の生成で3つの色違いマグカップの形をまったく同じに保ちました。

文字を活かすためのプロンプトルール

私たちの実際の実行でうまくいった（そして失敗した）経験から凝縮したものです：

リテラル文字列は引用符で囲みます。 text reads exactly: "SUMMER SALE"——モデルは引用符で囲まれていない周囲の語を候補のコピーとみなします。
「and no other words」（他の文字なし）を加えます。 そうしないとモデルが空間を埋めるために余分なバッジ文言を捏造することがあります。
文字をカメラに正対させます。 私たちが文字化けした唯一のレンダリングは、タグ上で角度をつけて吊るされた文字でした。同じコピーを平らなカードに置くと完璧でした。透視変形は字形が最初に崩れる場所です。
1枚の画像にテキストブロックを1〜2個まで。 テキストブロックを追加するごとに失敗確率が倍増します。複雑なレイアウトは下流で合成してください。
公開前に検証します。 この価格ならリトライループを十分に回せます：レンダリングし、OCRまたは目視で文字を確認し、不一致なら再生成します。失敗画像ごとに1回リトライしても、コストは代替モデルのほんの一部です。

バッチコスト

具体的なシナリオ：200 SKU × 各3素材（商品リスト画像、プロモーションバナー、SNSカード）= 600枚。

モデル	価格/枚	600枚	備考
z-image	$0.008	$4.80	Turbo 速度、画像内文字に強い
flux-schnell	$0.005	$3.00	最安だが文字レンダリングは重視していない
qwen-image-2.0	$0.025	$15.00	汎用品質が高い
gpt-image-2	$0.03	$18.00	`resolution` フィールドが必要；ECガイドはこちら

（価格は公開時点の hiapi 価格ページからのものです。）

バッチモードは上の generate() 関数をループに入れるだけです——少数のタスクを並行送信し、タスクIDを収集してからまとめてポーリングします。大量に推し進める場合は、まず hiapi がレート制限とバーストトラフィックをどう扱うかをお読みください。

はじめに

コンソールからAPIキーを取得し、上のコードスニペットを自分の商品カタログに向けてください——z-image モデルページにはモデルカードがあり、hiapi ドキュメントはタスクAPIを全面的に説明しています。1レンダリング $0.008 なので、自分のパイプラインに合うかどうかを知る最も安い方法は、今日の午後に最も扱いにくい10個のSKUで一通り実行してみることです。

重要なポイント

z-image の input スキーマは prompt と aspect_ratio のみ受け付けます——gpt-image-2 と異なり、resolution フィールドは HTTP 400 で拒否されます。
有効なアスペクト比は 1:1、4:3、3:4、16:9、9:16；出力PNGは比率に応じた固定サイズで返ります（例：1:1 は 1536x1536）。
プロンプト内のリテラル表示文字は引用符で囲み、「and no other words」（他の文字なし）を加えてください——引用符で囲まない指示語がレンダリング結果に漏れ出すことがあります。
文字はカメラに正対させてください。角度をつけた吊りタグは字形が最初に崩れる場所です。
$0.008/枚で計算すると、レンダリング-検証-リトライループでも1回の gpt-image-2 より約4倍安いままです。