使用ガイド
flux-3 と HiAPI API で EC 商品画像を生成する
プロンプトテンプレート、背景とライティングの制御、そして実際に動作する商品画像生成リクエスト
このページの内容
なぜ flux-3 が EC 商品画像に適しているのか
商品カタログのパイプラインが失敗する理由は、たいてい地味です。それは一貫性です。商品ページに必要なのはメイン画像 1 枚ではなく、複数の SKU、複数のアングル、季節ごとの更新にまたがる何十枚もの画像であり、それらはすべて同じ午後に同じスタジオで撮影されたかのように見えなければなりません。1 枚ごとにフォトグラファーへ依頼するのは遅くて高コストですし、1 枚ごとに任意の画像生成器へ任せると、個別にはもっともらしく見えても、並べるとちぐはぐな画像群ができあがりがちです。
そこに flux-3 が役立ちます。これは HiAPI API 経由で提供される画像生成モデルであり、商品パイプラインは画像生成を単なるもう 1 回の HTTP 呼び出しとして扱えます。プロンプトと商品パラメータを送信し、画像を受け取り、保存して、次の SKU を処理するだけです。ベンダー固有の SDK も、モデルごとの個別アカウントも、プロバイダーごとのグルーコードも不要です。
EC にとって特に重要なのは、flux-3 がプロンプト構造に対して予測可能に応答することです。商品写真は制約の強いシチュエーションです。被写体が 1 つ、中央配置または意図的に構図を決め、きれいな背景、そしてスタジオ風のライティングがあります。こうした制約はまさにテキストで表現できるものであり、テキストになれば創造的な判断ではなくテンプレート変数になります。これが「モデルに画像を頼む」ことと、商品カタログのタスクに生成ステップを持つことの違いです。
このガイドで扱う実際のワークフローは次のとおりです。再利用可能なプロンプト構造を定義し、背景とライティングの文言を調整してベースラインが正しく見えるまで詰め、その後は商品ごとに被写体のブロックだけを差し替えます。それ以外はすべてそのままにします。これこそが、ひとつの商品ラインで視覚的な一貫性を得るための方法です。
始める前に必要なもの
- HiAPI API キー、およびプラットフォームのモデル一覧から取得した現在の flux-3 モデル識別子。
- 構造化された商品データ:名称、素材、色、形状、およびモデルに描画してほしい目立つディテール。
- ベースラインプロンプトと生成出力を保存する場所。後でバージョンを比較できるようにします。

flux-3 の商品画像プロンプトの構成
1 つの商品にしか効かないプロンプトはあまり役に立ちません。自分で埋められるプロンプトこそが有用です。それを実現する方法は、記述を固定ブロックに分解し、各ブロックをコード内の変数に対応させることです。
5 つのブロック
- 被写体。 物体が何であるかを具体的な名詞で説明します。「マットな陶器のコーヒーマグ」は「素敵なカップ」より優れています。重要な場合はスケールの手がかり(「背が高く細い」「広口」)を加えます。
- 素材と表面。 仕上げと質感:ヘアラインアルミ、釉薬をかけた陶器、織られた綿、すりガラス。モデルのハイライトはここから生まれるので、明確にします。
- 背景。 商品が置かれる背景と天板:シームレスペーパー、スレート、柔らかなグラデーション、純白のインフィニティ背景。このブロックは意図的に短く地味に保ちます。これは足場であって、創造性の枠ではありません。
- ライティング。 方向、質、コントラスト:左からの柔らかなキーライト、大きな拡散光源、穏やかなフィル、物体下の繊細な影。このブロックが「スタジオ」感の大部分を決め、最も調整を重ねるブロックです。
- カメラフレーミング。 レンズがどう構図を取るか:中央配置の商品ショット、アイレベル、斜め 45 度、タイトなクロップ、上方に十分なネガティブスペース。
ブロックをテンプレートに変換する
これらのブロックは実行時に 1 つの文字列に組み立てられ、SKU ごとに被写体(ときには素材)だけを差し替えます:
product photo of {subject}, {material}, {background}, {lighting}, {framing}
記入済みの例:
product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above
テンプレートを安定させる 2 つのルールがあります。第一に、ブロックの順序を固定します——まったく同じ文言でも、ブロックを並べ替えると強調点が変わります。第二に、SKU をまたぐ際に固定ブロックを完全に同一の文字列のまま保ち、毎回書き換えないことです。微妙な文言の揺れは、商品カタログで背景とライティングが不揃いになる最も一般的な原因です。
創造性を入れるべきでない場所
固定ブロックには編集的な言葉を避けます。感情的な形容詞、スタイリングの飾り、シーンへの言及は入れません。変化は意図的なキャンペーンに任せ、商品カタログのテンプレートはきれいに保ちます。技術仕様書のように読めるテンプレートは、技術仕様書のように見える画像を生み出します——それこそが商品リストに必要なものです。

背景とライティングを制御する
背景とライティングは、画像群が一貫した商品カタログとして読めるかどうかを決める 2 つのブロックです。どちらも具体的で物理的な文言によく反応します。
背景:地味さを追求する
背景は美学ではなく物理的な設営として記述します。「シームレスなライトグレーのペーパー背景」や「純白のインフィニティ背景」は、既知のスタジオ配置を描写するため信頼できます。「ミニマル」や「美的」といった言葉は曖昧で、しばしばシーン要素がにじみ込みます。
有効なレバー:
- 表面タイプ: シームレスペーパー、マットなビニール、天然スレート、明るい木材。
- 色とトーン: ライトグレー、オフホワイト、ウォームサンド——明度を中から明るめに保ち、商品の輪郭が読めるようにします。
- 連続性: 「シームレス」または「インフィニティ」は、背景と床を融合させたいことをモデルに伝え、後処理が難しい地平線を消します。
- 空であること: 初期の試行で余計な物体が入り込む場合は、「空の背景、小道具なし」と明示する価値があります。
マーケット向けに透明背景の PNG が必要な場合は、まずきれいな単色背景で生成し、その後で切り抜きを行います。画像モデルに真のアルファチャンネルを出力させるよう求めるのは信頼できる方法ではありません。
ライティング:方向が第一、質は第二
ライティングの文言は 2 つの決定にきれいに分かれます。方向はハイライトと影がどこに落ちるかを決め、質はそれらのハイライトのエッジがどれだけ柔らかいかを決めます。
- 方向: 「左上からのキーライト」、「正面からの柔らかなキーライト」、「右からの光で左に穏やかなフィル」。ひとつ選び、商品ライン全体で保ちます。
- 質: 「大きな拡散光源」、「柔らかな影」、「均一な照明」。拡散した柔光は商品画像の安全なデフォルトです。光沢のある素材を白飛びさせないからです。
- コンタクトシャドウ: 「商品下の柔らかなコンタクトシャドウ」で物体を地面に接地させます。これがないと商品が浮いて見えます。
- コントラスト: 「低コントラストで明るく均一」は白背景のマーケット向けに適し、やや強めの方向性コントラストは高級なライフスタイル向けクロップに適します。
商品ラインの一貫性を保つ
一貫性はプロンプトの問題というより、バージョン管理の問題です。背景とライティングのブロックを名前付きプリセット(たとえば「ホワイトスタジオ」プリセットと「スレート」プリセット)として保存し、各生成ジョブでは SKU ごとにテキストを貼るのではなく名前でプリセットを参照します。プリセットを調整するときは 1 回だけ調整すれば、次のバッチは意図的に変更を引き継ぎ、揺らぎません。
結果がおかしいときは、一度に 1 つのブロックだけを変えて同じ商品を再生成します。背景とライティングを同時に変えると、どの文言が効いたのか判断できなくなります。

実際に動作する flux-3 HiAPI リクエスト
生成ステップは 1 回の API 呼び出しです。正確なエンドポイントパス、モデル識別子、リクエストフィールドはプラットフォーム上に文書化されており、変更される可能性があるためそこから取得してください。以下の形式はスクリプトに組み込むためのパターンです。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
presets = {
"white_studio": {
"background": "on a pure white infinity sweep, no props, empty backdrop",
"lighting": "soft diffused key light from the upper left, even fill, "
"soft contact shadow beneath the product, low contrast",
"framing": "centered eye-level product shot, generous negative space",
}
}
def build_prompt(product, preset_name="white_studio"):
p = presets[preset_name]
return (
f"product photo of {product['subject']}, {product['material']}, "
f"{p['background']}, {p['lighting']}, {p['framing']}"
)
def generate(product, preset_name="white_studio"):
payload = {
"model": "flux-3", # confirm the current identifier in the model list
"prompt": build_prompt(product, preset_name),
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations", # see docs for exact path
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
product = {
"subject": "a matte ceramic coffee mug",
"material": "glazed stoneware with visible clay texture",
}
result = generate(product)
print(result)
バッチ処理に組み込む
いくつかの習慣を守ると、単品ではなく商品カタログ全体に対して安全に実行できます:
- 各値は環境変数から解決する。 キーをソースコードやログから遠ざけます。
- レスポンスは信頼しないものとして扱う。 ドキュメント記載のフィールドから返却された画像参照またはペイロードを読み、ダウンロードして自分のストレージバケットへ保存します。一時 URL がジョブより長く生き残ることを前提にしないでください。
- 正確なプロンプト文字列を各出力と一緒に記録する。 画像メタデータとともに保存します。後で「なぜ SKU 1234 の画像は違って見えるのか」と誰かが尋ねたとき、答えは記憶ではなくデータベースにあるべきです。
- 一時的な障害にはバックオフ付きリトライを使い、 同時実行数を制限して、大量バッチがレート制限に引っかからないようにします。
- SKU とプロンプトバージョンごとにリクエストを冪等に保ち、 再実行が重複を散らかすのではなく同じ出力スロットを上書きするようにします。
テンプレートから本番パイプラインへ反復する
最初に検証したプロンプトは完成した資産ではなくベースラインです。本番化とは、パイプラインが再現・監査できるものに変えることです。
ステップ 1:少ないサンプルでベースラインを固定する
異なる素材カテゴリから 5〜10 個の商品を生成します——光沢のあるもの、マットなもの、布地、金属、透明なもの。これらはライティングブロックを異なる形で試します。テンプレートがこのサンプルで成立すればベースラインが得られます。光沢商品が白飛びしたり布地が平坦に見える場合は、商品カタログ全体を回した後ではなく、今そのブロックを調整します。
ステップ 2:プリセットに名前を付けバージョン管理する
プリセットには明示的なバージョン識別子を与え、変更は編集ではなく新バージョンとして扱います。単純な white_studio_v1 → white_studio_v2 という方式なら、旧プリセットでバッチを再生成して比較でき、「小さな改善」が SKU の半分にとってのリグレッションだった場合にロールバックもできます。
ステップ 3:プロンプトをパイプラインが読める場所に置く
2 つの層を保ちます。共有プリセット定義(背景、ライティング、フレーミング、バージョン)を 1 か所に置き、各 SKU の被写体と素材のフィールドを商品データベースに置きます。そして生成コードが両者を組み合わせます。これによりプリセットの変更は将来のすべてのジョブへ伝播し、被写体データは引き続き商品カタログチームが所有できます。
ステップ 4:出力を体系的に比較する
数十の SKU を超えると、並べて目視するレビューはスケールしません。より安価なシグナル:
- コンタクトシートレビュー: バッチを 1 枚のグリッド画像にまとめて異常を走査します。背景の揺れやフレーミングのずれはサムネイルサイズでもすぐに目立ちます。
- 背景を狙ったエッジサンプリング: 画像境界付近のピクセル色をサンプリングし、四隅がプリセットの想定色と異なる結果にフラグを立てます。これで最も多い失敗——背景が静かに色変化すること——を人の目なしで捉えられます。
- フレーム内位置チェック: 商品が中央にあり上方にネガティブスペースが必要なら、各画像で被写体のマスの位置を測り、異常にフラグを立てます。
フラグが立ったものはレビューキューへ回し、それ以外はすべて自動公開します。
ステップ 5:意図をもって再生成する
ベースラインが安定すれば、新しい SKU はプロンプトの問題ではなくデータの問題です。被写体と素材のフィールドを追加し、ジョブをキューに入れ、自動化に任せます。再生成の実行は意図的な変更——季節の背景、新しいライティングバリエーション——に取っておき、その際にプリセットのバージョンを上げます。
よくある落とし穴と回避方法
商品画像生成の失敗のほとんどは同じいくつかの問題であり、それぞれにプロンプト側またはパイプライン側の修正方法があります。
バッチ内の背景の揺れ
最もよくある不満:画像は個別には一貫しているのに、SKU 間でばらつく。原因はほぼ常に文言の揺れです——誰かが背景ブロックを書き換えたか、テンプレートが商品属性をそこに差し込んでいます。修正:背景とライティングを単一のプリセットソースからの固定文字列にし、コード内で組み立て後のプロンプトがプリセットテキストを逐語的に含むことをアサートします。
余計な小道具やシーン要素
モデルは背景を足したがります。小さな葉の一枝、折りたたまれた布、テーブル端らしき影などです。空であることを明示し(「空の背景、小道具なし」)、シーンの言語はできるだけ物理的かつスタジオ限定に保ちます。それでも残る場合は被写体の説明を簡略化します——被写体ブロックの装飾的な形容詞は、しばしばシーン内に対応する飾りを呼び込みます。
浮いた商品
コンタクトシャドウがないと物体は背景に貼り付いたように見えます。ライティングブロックに「商品下の柔らかなコンタクトシャドウ」を含め、商品が浮遊しているのではなく表面上に置かれていることを明示します。
フレーミングの不一致
クロップの混在はカテゴリページを台無しにします。フレーミングブロックは 1 つのフレーズに固定し、変化させません。複数のアスペクト比が必要な場合は、比ごとにプロンプトするのではなく、同じ構図で生成して後からクロップします。
過度に指定しすぎたプロンプト
商品の歴史、ブランド、ストーリーを長々と説明するプロンプトは、商品カタログ画像ではなく編集的な画像を生みがちです。テンプレートはショットリストのように読めるべきです。結果がしっくりこないときは、通常は言葉を足すのではなく削るのが修正方法です。
生成の失敗をコードの欠陥とみなす
1 つの悪い結果はパイプラインを書き直す合図ではありません。保存した正確なプロンプト文字列で再現し、1 つのブロックを変え、再生成してから結論を出します。プロンプトを各出力と一緒に記録することがこれを可能にします——そしてこれは最も早く身につけるべき、最もコストの低い習慣です。
まず 1 つのプリセット、1 つのサンプルバッチ、そして画像ごとに保存するプロンプトから始め、素材タイプ全体でベースラインが成立してから拡張しましょう。