gpt-image-2.5-flare を EC 商品画像に活用：hiapi API によるバッチワークフロー

商品撮影は通常、商品カタログの公開作業の中で最も時間のかかる工程です。SKU ごとにスタジオ撮影を行い、季節ごとの背景ごとに撮り直し、プラットフォームごとに異なるアスペクト比のルールに合わせてまた撮り直す必要があります。hiapi の gpt-image-2.5-flare は、その作業の大部分をひとつのモデル ID に集約します。テキストプロンプトから商品画像を生成することも、既存の写真を編集すること（背景の差し替え、ライフスタイルシーンへの配置、チャネルごとのサイズ調整）も、商品そのものに手を加えることなく行えます。このガイドでは、3 つの実践的なワークフローと未編集の API 出力を使ってデモを行い、その後、1 枚ずつではなくカタログ全体にバッチ適用する方法を紹介します。

以下の画像に登場する商品（「MOSS」とラベルされた緑色のガラス瓶と、「AER」とラベルされたコバルトブルーのケトル）は、この技術をデモするための概念的な小道具であり、実際の顧客撮影ではありません。ただし、すべての画像は hiapi API の実際の未編集出力であり、シミュレーション画像ではありません。

なぜ「ひとつのモデル ID」が重要なのか

gpt-image-2.5-flare は、渡す内容に応じて 2 種類の異なるタスクを処理します。

• image_urls を省略すると、テキストプロンプトのみから画像を生成します（テキストから画像生成）。
• image_urls を追加すると、提供された写真を編集する動作に切り替わります（画像から画像編集）。同じモデル、同じエンドポイント、同じ料金です。

カタログにとって、これは見た目以上に重要です。商品を初めて撮影する場合でも、既存の写真を再利用する場合でも、2 つのモデル ID や 2 つの料金体系を使い分ける必要がありません。さらに、バッチ処理に特に適した 2 つの特徴があります。

• 品質ティアであり、単一の固定コストではない。 リクエストごとに low / medium / high / xhigh / max を選択できるため、500 SKU のサムネイル一括処理とトップページの十数枚のメイン画像を同じ単価で課金する必要はありません。
• 柔軟なアスペクト比。 リクエストごとに 1:1、4:5、9:16、16:9 などの比率を選択できるため、同じ商品画像を撮り直すことなく、正方形のマーケットグリッド、縦長のモバイルフィード、ワイドバナーに切り抜けます。

各呼び出しは hiapi の非同期タスク API を通じて行われます。POST /v1/tasks でタスクを送信し、その後 GET /v1/tasks/{id} をポーリングする（またはコールバックを使用する）と、ステータスが success になるまで待機します。「レスポンスで直接画像を返す」同期呼び出しはありません。生成にも編集にも数秒かかります。

ステップ 1：ゼロからクリーンなスタジオショットを生成する

シンプルで十分な光量のスタジオ写真から始めます。これが後のステップで編集するベース素材になります。

import os
import time
import requests

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


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" は初回処理の妥当なデフォルトです。この記事のすべての画像は同じティアを使用しています。追加のディテールがコストに見合う場合にのみ、個別の SKU を high に引き上げてください（下記の料金表を参照）。

ステップ 2：商品を再生成せずに背景を再設計する

ここがカタログ作業を本当に削減するワークフローです。スタジオショットを image_urls として渡し、変更したい内容だけを記述します。商品そのものはピクセル単位で一致したまま——同じ瓶の形、同じキャップ、同じラベル——背景だけが変わります。

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

同じパターンはまったく異なる商品にも当てはまります。ここではコバルトブルーのケトルで、背景を温かいピーチ色のスタジオ背景布に差し替えたもので、同じ方法で生成されています。

これが「季節ごとのリフレッシュ」や「新市場テーマ」タスクの核心です。各 SKU につき 1 回の編集呼び出しで、商品には影響せず、背景だけが変わります。これを 500 回実行すれば、撮り直しなしでカタログ全体のテーマを一新できます。

ステップ 3：商品をライフスタイルシーンに配置する

スタジオショットはマーケットグリッドの表示に適していますが、ライフスタイルシーンはランディングページや広告で商品を売り込むのに適しています。同じ編集パターンで、より大きなプロンプトを使用します。モデルは背景色を変えるだけでなく、正確な商品を説得力のある実世界のシーンに配置します。

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

各編集プロンプトに制約的な文言（「keep the original ... completely unchanged」）を残してください。これが、周囲のすべてを変えながら商品がずれるのを防ぐ役割を果たします。

カタログ全体向けのバッチ自動化

単発の編集呼び出しも有用ですが、カタログ規模では、各 SKU に対して同じパターンを無人で実行することに価値があります。本番環境で有効な構造は次のとおりです。

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

少数以上の画像を処理する場合、次の点が重要です。

• 行ごとの冪等キー。 SKU／バリアントごとに異なる Idempotency-Key ヘッダーを送信します。これにより、タイムアウト後に再試行されたリクエストが重複タスクを作成し、二重に課金されることを防ぎます。
• 同時実行数を制限し、一気にすべて送信しない。 小さなスレッドプール（または非同期セマフォ）を使えばレート制限に達しません。429 が返った場合はバックオフして再試行し、ハードな失敗として扱わないでください。
• 画像の用途に応じて品質ティアを選ぶ（一律の基準ではない）。サムネイルやグリッド一覧は通常 low/medium で十分ですが、トップページのメイン画像や広告クリエイティブには high や xhigh を使う価値があります。
• 異なるアスペクト比は元画像ではなく、同じ編集済みソース画像から派生させる。まず背景差し替え編集を 1 回実行し、その結果から 1:1、4:5、9:16 のクロップ版をリクエストすることで、すべてのチャネルでまったく同じ商品表現を表示できます。
• 出力 URL はすぐにダウンロードまたは再アップロードする。 タスク出力は期限切れになります。一時 URL を永続的な画像ソースとして使わないでください。

料金

gpt-image-2.5-flare は、出力画像の枚数に応じて品質ティアごとに課金されます。ゼロからの生成でも編集でも同じ料率です。

品質	1 枚あたりの価格
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

medium ティアでは、500 SKU のカタログのテーマを再設計し、商品ごとに背景差し替え編集を 1 回行う場合、コストは約 $33.60 です。すべてのモデルの完全で最新の料金表は料金ページをご覧ください。

よくある質問

編集で商品が意図せず変わってしまうことはありますか？ 編集プロンプトを単一の変更（「背景のみを変更する……」）に限定し、変更してはならないもの（形状、色、ラベル文字、カメラアングル）を明示的に列挙してください。上記の例では、各編集を通じて商品が変わらないことを示しています。

同じモデルで生成と編集の両方ができますか？ はい、gpt-image-2.5-flare はひとつのモデル ID です。image_urls を含めると既存の写真を編集し、省略するとプロンプトのみから生成します。

1 回の編集呼び出しで何枚のソース画像を渡せますか？ image_urls を通じて最大 16 枚まで渡せますが、ほとんどのカタログ編集では 1 枚だけで十分です。つまり、再設計したい写真 1 枚です。

再試行時の二重課金を避けるにはどうすればよいですか？ リクエストごとに一意の Idempotency-Key ヘッダーを送信してください。同じキーでの再試行リクエストは、新しいタスクを作成するのではなく、元のタスクを返します。

関連記事

初めての呼び出しを設定する場合は、gpt-image-2.5-flare API ガイドから始めて、最小限の動作例と非同期タスクのライフサイクルについて詳しく学んでください。商品撮影以外のプロンプトパターンについては、GPT Image 2.5 Flare プロンプト：実際の出力付きコピー＆ペーストレシピをご覧ください。完全なパラメータとスキーマはモデルページに、一般的な API 規約（認証、タスクポーリング、コールバック）は hiapi ドキュメントに記載されています。

自分のカタログで試す準備はできましたか？ hiapi ダッシュボードから API キーを取得し、最初の商品写真で上記のスタジオショット例を実行してください。