使用ガイド

hiapi API で grok-imagine/text-to-image を使いEC商品画像を生成する

Aug 5, 2026

ほとんどの商品画像パイプラインは、次のような要件に直面すると破綻します。同じ写真から3つの異なる形状を生成する必要がある場合です。カタログのグリッド用の正方形、モバイルの商品詳細ページ（PDP）用の縦長クロップ、そしてトップページのヒーローバナー用のワイド画像です。1枚のキービジュアルを再クロップしても、すべてのアスペクト比でうまく見えることはほとんどありません。商品が切れてしまったり、不自然な余白が生じたりします。grok-imagine/text-to-image はこの問題を回避します。必要な比率でネイティブに生成でき、こうしたバナー用途のために作られた2つのワイドフォーマット（2:1 と 20:9）を含み、hiapi API 上では1枚あたり $0.03 の均一価格で、解像度によって変わりません。

本ガイドでは、実際のリクエスト構造、テスト中に遭遇したスキーマの落とし穴、1つの商品ブリーフに対してショットリスト全体を一括生成するスクリプト、そしてカタログ規模を見据えた正直なコスト試算を紹介します。

価格の位置づけ

執筆時点で hiapi の料金ページで確認した内容は以下の通りです：

モデル	1枚あたりの価格	解像度	アスペクト比の制御
grok-imagine/text-to-image	均一 $0.03	1K または 2K、同価格	`2:1`、`20:9` を含む13種類
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	解像度による段階料金	同じ比率セット

品質ティアは細部（反射、生地の質感、小さな文字）で確かに大きな向上があります。数少ない本当のキービジュアルには追加費用を払う価値があります。しかしカタログ内の大部分の画像（グリッドのサムネイル、ライフスタイルのバリエーション、別アングル）では、ベースモデルで十分に近く、2〜3倍の価格差はバッチ用途では払う価値がありません。

実際に動作するリクエスト

このページのすべての画像は同じエンドポイントから生成されています：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

これにより taskId が返されます。GET /v1/tasks/{taskId} を status が success になるまでポーリングし、その後 output[0].url を取得してダウンロードします。この URL は署名付きで期限切れになるため、直接リンクするのではなく、バイト内容を即座に保存してください。

テスト中に私たちがつまずいた3つのスキーマの詳細は、自分で構築する前に知っておく価値があります：

aspect_ratio は自由形式ではなく、厳密に13値の列挙です。それ以外の値を送ると400が返り、完全なリストが添付されます：2:1、20:9、19.5:9、16:9、4:3、3:2、1:1、2:3、3:4、9:16、9:19.5、9:20、1:2。バナーに必要な2つの比率は 2:1 と 20:9 です。hiapi 上のほとんどの画像モデルは最大でも 21:9 までしか対応しておらず、ウルトラワイドの選択肢を提供しないものもあります。
resolution は小文字のみです。"2K" ではなく "2k" を使用してください。大文字形式を送ると、黙って変換されるのではなく、そのまま拒否されます。
入力スキーマは厳密です。余分なフィールドやスペルミスのあるフィールド（残存する negative_prompt、他のモデルの例からコピーした style キーなど）は無視されるのではなく、リクエスト全体が失敗します。

カタログ品質のクリーンな画像のためのプロンプト作成

一貫したカタログ出力を得るための最大のレバレッジは、望まないものを明示することです。上記の白背景のキービジュアルに対して有効だったプロンプトは次の通りです：

"マットな陶器製ハンドドリップコーヒードリッパーを純白のシームレス背景に配置、スタジオのソフトボックス照明、中央揃え、柔らかい接地影以外の影のグラデーションなし、文字なし、ウォーターマークなし、小道具なし、EC商品撮影、シャープなフォーカス"

PDPのサブ画像やメールバナー用のライフスタイルバリエーションでは、背景と光の手がかりを置き換えますが、同じ「文字なし／ウォーターマークなし／指定した小道具以外は置かない」という規律を保ちます。これがまさに、grok-imagine が商品自体に雑多なオブジェクトや判読不能なラベル文字を追加するのを防ぐポイントです：

"同じ陶器製ハンドドリップドリッパーを木製のキッチンカウンターに置き、隣に湯気の立つマグカップ、暖かい朝の光、浅い被写界深度、居心地のよい生活感のあるキッチン背景を柔らかくぼかす、文字なし、ロゴなし"

ウルトラワイドバナーのワークフロー

要件がカタログのサムネイルではなくトップページやカテゴリのバナーである場合、2:1 と 20:9 はまさに grok-imagine を特に採用する価値のある2つの比率です。コツは、クロップ結果がたまたま合うことを期待するのではなく、ネガティブスペースを直接プロンプトすることです。商品が画面のどこにあるか、そしてどの領域を空白にすべきかを記述します：

"マットな陶器製ハンドドリップコーヒードリッパーを画面の右3分の1に配置、ゴールデンアワーの屋外光、画像の左3分の2の領域にタイトルテキストを重ねるための十分な空白のネガティブスペースを確保、シネマティックなワイド構図、文字なし、ロゴなし"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

CMS が比率ではなく正確なピクセルサイズを必要とする場合は、最も近いサポート対象比率で生成してから、その画像をロスレスでクロップしてください。具体的なパディングの計算については、API で正確なサイズを実現するためのノートをご覧ください。

ショットリスト全体を一括生成する

1つの商品ブリーフには通常、1枚以上の画像が必要です。以下のスクリプトは、このページの4枚の画像を生成するために使用した実際のスクリプトを再現したものです。画像ごとに1つのタスクを送信し、完了までポーリングしてからディスクに保存します：

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

複数 SKU の完全なバッチを実行する場合は、まず3つのタスクをすべて送信してから、それらを並行してポーリングしてください（小さな asyncio かスレッドプールで十分です）。各タスクは通常1分以内に完了するため、直列で実行すると無意味なアイドル待ち時間が増えるだけです。

実際のカタログ運用のコスト

1枚あたり均一 $0.03 で計算すると、上記の3枚構成（キービジュアル＋ライフスタイル＋バナー）のコストはSKU あたり $0.09 です。規模を拡大すると：

50 SKU × 3枚 = 150枚 → $4.50
500 SKU × 3枚 = 1,500枚 → $45
2K のキービジュアルのみを grok-imagine-quality にアップグレード（$0.03 ではなく $0.10）すると、500 SKU の合計は $80 になります。それでも従来の商品撮影1回と比べれば端数にすぎません。

grok-imagine と他の製品ラインとの比較

画像を動かす必要がある場合、たとえば静止バナーではなくソーシャル広告用の6秒の商品モーションクリップであれば、同じシリーズが grok-imagine-image-to-video でカバーされ、これらの静止画の1枚を開始フレームとして使用します。このワークフローはショート動画ガイドで別途紹介しています。Nano-Banana ベースのカタログパイプラインと比較しているチームにとって、私たちの Nano-Banana ECガイドが最も近い並列の参考資料です。同じタスク API 構造で、モデルの強みが異なります。

よくある質問

grok-imagine/text-to-image はテキストプロンプトだけでなく参照画像（i2i）もサポートしていますか？ はい。ただしそれは別のモデルバリエーション（grok-imagine/image-to-image）で、独自の入力スキーマを持っています。本ガイドは純粋なテキストto画像のパスを扱っています。

リクエストが400と「additional properties」エラーを返すのはなぜですか？ 入力スキーマは厳密です。prompt、aspect_ratio、および任意の resolution のみを送信しているか慎重に確認してください。他のモデルの例からコピーした余分なフィールドを持ち込まないでください。

列挙から選ぶのではなく、1200×630 のような正確な比率を得ることはできますか？ 最も近いサポート対象比率（16:9 は多くのウェブバナーの形状に近い）で生成し、その後でロスレスにクロップしてください。具体的なパディング方法については、上記でリンクした正確なサイズのガイドをご覧ください。

2K 解像度は 1K と比べて待つ価値がありますか？ このモデルは両解像度で同じ価格なので、厳しいレイテンシ予算がない限りデフォルトで 2K を使用してください。無料でより多くのディテールが得られます。