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

EC商品カタログの成否は一貫性にかかっています。40個のSKUを扱う販売者に必要なのは40回の異なる撮影ではなく、見栄えの良い背景と、各商品を素早くそこへ配置する方法です。まさにこれが参照画像駆動の画像編集の実際のユースケースであり、hiapi API 上の grok-imagine/image-to-image が得意とするものです。シーンと商品画像を渡すと、両者を合成してクリーンでブランドトーンに合った画像を生成します。手動マスクも、独立した切り抜き工程も不要です。

本ガイドでは、このモデルの実際かつ検証済みのリクエストschema(マーケティングコピーではありません)、実際に課金される価格、カタログ全体に同じ背景を適用するバッチスクリプト、そして各家ECプラットフォームが異なるトリミング比率を要求する中で出力アスペクト比を制御する実用的なテクニックを扱います。

このモデルが実際に行うこと

grok-imagine/image-to-image はテキストプロンプトと少数の参照画像を受け取り、それらを融合して新しい画像を生成します。商品撮影において、これは次を意味します。

• 背景の統一 —— 各SKU写真を同じスタイル化されたシーン(テーブル、棚、スタジオ背景布)の前に配置し、撮り直しは一切不要。
• シーン合成 —— 商品の切り抜きと環境参照画像を組み合わせ、光と構図を一致させる。
• 参照画像間のスタイル転送 —— ある画像の色調や小道具を別の画像に持ち込みつつ、商品自体は編集しない。

これらすべてが1回のタスク呼び出しで完結し、出力画像1枚ごと、加えて送信する参照画像1枚ごとの少額費用で課金されます。

実際のschema(価格ページではなく、オンラインAPIに対して検証済み)

私たちは grok-imagine/image-to-image で POST /v1/tasks を直接プローブし、このモデルの入力schemaが正確に2つのフィールドを受け付けることを確認しました。

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

これだけです——resolution も aspect_ratio も strength パラメータもありません。payload内のそれ以外の内容は厳格なschemaによって拒否されます。

訂正すべき誤りが1点あります:hiapi の価格ページは現在、このモデルが「最大6枚」の参照画像をサポートすると主張しています。私たちは同一リクエストで6個と7個の画像URLをそれぞれ送信して直接テストし、両方とも拒否されました。

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

本稿執筆時点で実際に適用される制限は1回の呼び出しあたり3枚であり、6枚ではありません。このモデルを中心にパイプラインを構築する場合は3枚を前提に計画し、これと異なるマーケティングコピーは陳腐化したものと見なしてください。この制限に依存する自動化をリリースする前に、必ず実際の POST /v1/tasks 呼び出しで確認してください。これらの制限はプラットフォームの進化に伴い変化するためです。

自動アスペクト比:出力比率は最初の参照画像に従う

このモデルには aspect_ratio 入力フィールドがありません。では出力の形状はどこから来るのでしょうか。私たちは答えを見つけるために制御実験を行いました。同じプロンプト、同じ2枚の参照画像で、image_urls の順序だけを入れ替えました。

このレンダリングでは、商品写真(バックパック)が image_urls の1番目にリストされ、その後に背景シーンが続きました。出力は1248×832で返されました——商品写真自身の比率に一致する3:2の横長画像です。

同じプロンプト、同じ2枚の画像——しかし今回は背景シーンが1番目にリストされました。出力は1024×1024で返され、商品ではなくシーン参照画像自身のアスペクト比に一致する正方形のトリミングです。

ルールはこうです:grok-imagine/image-to-image の出力アスペクト比は、image_urls の中で先頭に来るURLから継承されます。プロンプトから構図のヒント(「商品写真」か「ワイドシーン」か)を読み取るのではなく、純粋に位置によって決まります。これを知れば、実に有用なレバーになります。特定のECプラットフォームが好むトリミングに合わせたい場合は、参照画像配列を並べ替えるだけです。Instagram風の正方形の商品リストには正方形の参照画像を先頭に、ワイドなバナー枠には横長の参照画像を先頭に置きます。

価格(オンライン価格表に対して確認済み)

モデル	呼び出しタイプ	価格
grok-imagine/text-to-image	テキスト → 画像	$0.03 / 画像
grok-imagine/image-to-image	参照画像駆動編集(本ガイド)	$0.03 / 画像 + 参照画像1枚あたり $0.003
grok-imagine-quality/text-to-image	テキスト → 画像、上位ティア	$0.07 / 画像(1K)
grok-imagine-quality/image-to-image	参照画像駆動編集、上位ティア	$0.08 / 画像(1K)、$0.10 / 画像(2K)、+ 参照画像1枚あたり $0.015

本ガイドで使用する grok-imagine/image-to-image のベーシックティアは解像度によって変わらず、均一料金です——-quality ティアのように2K/4Kの追加料金を支払うことはありません。数十個のSKUを同じシーンに合成するカタログ更新では、画像1枚あたり$0.036(商品写真1枚+シーン参照画像1枚)が予算策定の基準となる数字です。大量実行の前に必ず /en/pricing を再確認してください。料率は変更される可能性があります。

画像ごとによりシャープなディテールが必要で、約3倍の価格上昇を許容できる場合は、grok-imagine-quality ティアが同じワークフローのより高忠実度なバージョンです。参照写真がまったくない純粋なテキストから画像への商品モックアップについては、ベーシックティアのテキストから画像へのチュートリアルをご覧ください。

バッチスクリプト:1つのシーンでカタログ全体を

以下は最小限のPythonループです。再利用可能な背景シーン1枚を受け取り、フォルダ内の各商品写真と合成し、それぞれを独立したタスクとして送信し、完了までポーリングします。上記で確認したschemaを使用し、商品画像を先頭に置くため、各出力は商品写真自身のアスペクト比を継承します——シーンの比率が欲しい場合は順序を入れ替えてください。

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

本番パイプラインでは、ループ内でポーリングする代わりにタスクに callback.url を登録してください。完全なコールバックpayload構造については hiapi モデルカタログをご覧ください。taskId を商品SKUと一緒に保存しておけば、失敗したタスクをバッチ全体を再送信することなく再試行できます。

実際の商品写真の例

これらは両方とも同じ背景シーン参照画像を使って生成され、呼び出し間で商品写真だけを差し替えました——光、デスク、背景の植物が「カタログ」全体で一貫しており、これこそが再利用可能シーンワークフローの醍醐味です。

よくある質問

1回の呼び出しで3枚を超える参照画像を使えますか? いいえ。オンラインschemaは image_urls に maxItems: 3 を強制しています——これは他の場所のマーケティングコピーがどう言おうと、直接APIテストで確認済みです。最大3枚の参照画像(通常は商品+シーン、または商品+シーン+スタイル参照)を前提にプロンプトを設計してください。

出力のアスペクト比を制御するには? このモデルには aspect_ratio パラメータがありません。出力は image_urls の1番目の画像のアスペクト比を継承します——必要な比率に合わせて参照画像を並べ替えてください。

参照画像なしの純粋なテキスト生成をサポートしますか? いいえ——image_urls は必須フィールドです。純粋なテキストからの商品モックアップには、代わりに grok-imagine/text-to-image を$0.03/画像でご利用ください。

このモデルにはより高忠実度なバージョンがありますか? はい、grok-imagine-quality/image-to-image が$0.08/画像(1K)または$0.10/画像(2K)、加えて参照画像1枚あたり$0.015で同じ参照画像駆動ワークフローを実行し、よりシャープなディテールを提供します。

今すぐ試す

hiapi ダッシュボードからAPIキーを取得し、背景シーンを1枚用意して、カタログ全体を入れ替える前にまず少数のSKUで最初のタスクを実行してみてください——画像1枚あたり$0.036で計算すると、10個の商品でこのワークフローをテストするコストは1ドル未満です。