HiAPI
ブログ

使用ガイド

muse-image-1.0/text-to-image をEC製品画像に活用する:開発者ワークフローガイド

HiAPI API によるアングルとライティングのプロンプトテンプレート、サイズ選択、バッチリクエスト

Nov 9, 2026
ほぼ黒に近い深緑の背景に、平らな真鍮と深緑のリボンが交互に編み込まれて開いた格子を形作っている——このガイドのカバーアート。
このページの内容

なぜ text-to-image がEC製品ワークロードに適しているのか

カタログ作業は本質的に反復的です。同じ製品をいくつかのアングルから撮影し、同じライティングで、同じ背景に置き、いくつかのサイズに展開する。この反復性こそが text-to-image モデルが得意とする領域です。主力製品のスタジオ撮影を置き換えるのではなく、カタログのロングテール部分を低コストかつ一貫した方法で埋めるために使います。

生成技術が本当に価値を発揮する場面:

  • 大量のバリエーション。 カラーバリエーション、わずかな SKU 差異、パッケージのリニューアルなど、再撮影のコストが画像そのものの価値を上回るケース。
  • プレースホルダーと発売前の素材。 リスティングページ、社内レビュー資料、A/B テストなど、最終的な撮影素材が揃う前にそれらしく見えるコンテンツが必要な場面。
  • 構図の探索。 フォトグラファーやスタジオのスケジュールを押さえる前に、真上からのフラットレイと45度のメインカットの見え方を試す場面。

適さない場面:規制対象の訴求表現、正確に判読できる必要があるパッケージの文字、顧客が細かな質感を比較するメイン画像。これらは依然としてカメラと人の手が必要です。

開発者にとってのメンタルモデルはパイプラインです。構造化された製品記述を入力し、プロンプトテンプレートをレンダリングし、モデルが1枚または複数の画像を返し、QA チェックがストアに掲載できるかを判断する。以下の各セクションでは、このパイプラインを賢くするのではなく、地味で再現性のあるものにする方法を説明します。

カタログパイプラインは平織りのようなもの:1本のプロンプトがチェック構造に入り、同じ構造から複数の独立した製品画像が生まれる。

HiAPI 経由で muse-image-1.0/text-to-image を呼び出す

すべてのリクエストは同じ HiAPI インターフェースを通るため、一度認証すれば呼び出すすべてのモデルに対して1つのクライアントを保持できます。モデル識別子は muse-image-1.0/text-to-image です。リクエストにはプロンプト、出力サイズの選択、そして固定したい生成ごとのオプションを含めます。

構造的には、1回の生成は次のとおりです。リクエストペイロードを構築し、HiAPI クライアント経由で POST 送信し、返された結果オブジェクトを読み取り、画像参照を所属する製品 ID とともに永続化します。最初の呼び出しから身につけるべき2つの習慣:

  1. プロンプトはリクエストにインラインで書かず、変数に保存する。 何百回も再利用し比較することになります。
  2. すべての出力について、正確にレンダリングされたプロンプトを記録する。 3週間後に画像に問題が見えたとき、プロンプトが唯一のデバッグ手がかりになります。
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

size は後から考えるものではなくテンプレートの一部として扱ってください。同じプロンプトでも異なるアスペクト比では被写体の構図が変わる可能性があります。続くセクションではプロンプト構造とサイズの決定の両方を扱います。

リクエストはクライアントからエンドポイントを経てモデルに届き、編まれたリボンが1枚の画像結果を返す。

一貫した撮影アングルのためのプロンプトテンプレート

カタログの一貫性は、少数のスロットだけを差し替える固定のプロンプト骨格から生まれます。すべてのプロンプトをゼロから書くと、画像ごとにズレが生じます。撮影タイプごとにテンプレートを1つ構築し、カメラ記述の文言をすべての製品間でバイト単位で同一に保ちます。

実用的な骨格:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

製品ごとに変わるのは subject_block だけです。camera_block はアングルごとの定数です:

  • メイン / 斜め45度: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • 正面: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • 真上からのフラットレイ: directly overhead top-down view, product centered, flat lay composition
  • ディテールアップ: close-up macro view of the product surface, shallow depth of field

実運用でこれらを機能させる2つのルール:

  • アングルを二度指定する。 明示的なアングルに構図の条項(例:"full product in frame with even margins")を組み合わせると、どちらか単独よりも信頼性が高まります。
  • 相対的な参照を避ける。 "Same angle as the last image" は text-to-image モデルには何の意味もありません。各プロンプトは単独で成立する必要があります。

テンプレートはレンダリングコードとともにバージョン管理下に置きます。camera_block を変更したらバージョン番号を上げ、コミット前に小規模なサンプルを再生成してください。文言の変更はカタログ全体の変更なのです。

ライティングと背景のためのプロンプトテンプレート

ライティングと背景は、生成された画像群を無関係な寄せ集めではなく同じ撮影のように見せる鍵です。どちらもテンプレートの定数部分に属し、方向と柔らかさを明示する必要があります。

確実に引き継げるライティングの表現:

  • 方向: key light from camera left、light from upper right、soft overhead light。方向は最も直感的な一貫性のレバーであり、撮影タイプごとに固定してください。
  • 質: soft diffused light、large softbox, gentle shadows、hard directional light with defined shadow edge。
  • 補助光と回り込み: subtle fill from the right, low-contrast shadows、clean highlight on the top surface。

背景の表現:

  • シームレススタジオ: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product。
  • ライフスタイルの天板: resting on a matte stone surface, softly out-of-focus neutral background。
  • 切り抜き向け: isolated on a plain white background, product fully in frame, generous margins for cropping。

実用的な注意点が2つあります。第一に、製品の表面や反射が多いほど、ライティングをより正確に記述する必要があります。ハイライトの位置がそのまま製品の見え方になるからです。第二に、同じ撮影タイプ内で背景を混在させないでください。グリッドタイルの1セットは背景を共有すべきです。そうでなければグリッドは3つの異なるサプライヤーから寄せ集めたように見えます。これらのブロックを定数として固定し、意図したときだけ変更してください。

出力サイズとアスペクト比の選択

バッチ処理の前に、掲載場所ごとにサイズを決めてください。異なるサイズで再実行するのはリサイズではなく完全な再生成だからです。まず掲載場所をアスペクト比に、次にフロントエンドが実際にレンダリングするピクセルサイズにマッピングします。

  • グリッドとカテゴリタイル: 正方形。製品グリッドのクロップは予測できないため、余白を十分に取った正方形の構図がほとんどのタイルレイアウトに適合します。
  • 製品詳細ページ: 正方形または4:3。サムネイルではなくズームビューアのサイズを基準に決めます。詳細ページが固定比率でクロップされる場合は、CSS で抵抗するのではなく正確に合わせてください。
  • バナーとヒーロー帯: ワイド。セーフエリアを明確に計画してください。製品を中央に配置し、両側にネガティブスペースを残してマーケティングコピーの場所を確保します。
  • メールとソーシャルメディア: プラットフォーム固有の比率に合わせます。余白を足して埋めるより再生成する方が安上がりです。

いくつかの経験則:

  1. 掲載場所ごとに1つの標準サイズを選び、再利用する。 1つのタイルグリッドに複数サイズが混在すると、目に見える品質差が生じます。
  2. より大きな枠を埋めるために生成画像を拡大しない。 より大きなサイズで生成して縮小してください。
  3. 比率が変わったら構図を再確認する。 正方形向けに構図した45度のメインカットは、ワイドクロップで製品のベースが切れる可能性があります。camera_block の構図条項を適宜調整してください。
  4. サイズをジョブレコードに保持する。 後で出力をレビューするとき、サイズはメタデータのノイズではなくコンテキストの一部です。

バッチリクエストとアイテム単位の結果処理

カタログ規模では、作業単位はリクエストではなくジョブです。つまり、製品1つ、撮影タイプ1つ、サイズ1つ、レンダリング済みプロンプト1つ。ジョブをまずデータとしてモデル化し、有界キューを通じて送信すれば、失敗は午後を無駄にするものではなく再実行可能な行になります。

堅牢なループは4つのことを行います:

  • プロンプトを決定的にレンダリングする:テンプレートと製品フィールドからレンダリングし、レンダリング済み文字列をジョブに保存します。
  • 同時実行数を制限する:アカウントと下流ストレージが耐えられる量に抑えます。カタログ全体のリクエストを一度に発行しないでください。
  • 結果をアイテム単位で処理する。 バッチ操作はアイテムごとに成功または失敗するため、各結果をその job_id の下に書き込み、バッチ全体がアトミックであるとは決して仮定しないでください。
  • 一時的なエラーのみバックオフ付きでリトライする。 検証エラー(不正な形式のプロンプト、サポートされないサイズ)はリトライしても同じように失敗するため、まず分類してからリトライしてください。
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

ジョブごとにステータス列(pending、done、failed)を保持し、失敗用のデッドレタービューを用意します。バッチが完了したら、単なる合計ではなく撮影タイプとサイズ別に件数を報告してください。回帰はそこに潜んでいます。

生成画像を公開する前の QA チェックリスト

生成画像にはゲートが必要であり、そのゲートは人が背後で確認するチェックリストであるべきです。自動チェックは安価な問題を捕まえ、レビュアーは高価な問題を捕まえます。

レビュー前の自動チェック:

  • 対象の掲載場所のアスペクト比とピクセルサイズが正しい。
  • 明らかに破損した出力がない。ファイルが正常に開けてデコードできる。
  • プロンプトで製品の配色を指定した場合、色が期待どおりである。
  • グリッドタイルにクロップ許容のための余白が残っている。

公開前の人手レビュー:

  • 製品はこの製品に見えるか。形状、比率、金具、仕上げはどうか。
  • 架空の文字、ロゴ、パッケージコピーはないか。生成された文字はよくある失敗点であり、ストアでは法的リスクにもなります。
  • ライティングと背景が、フルサイズだけでなくサムネイルサイズでもグループ内の他の画像と一致しているか。
  • 画面内に余計な物体、追加の部品、不合理な反射がないか。
  • 訴求表現や規制対象のラベルが生成技術によって改変されていないか。それらの画像は撮影フローに回すべきです。

承認された素材ごとにレビュアーとプロンプトバージョンを記録してください。顧客からの苦情や削除要請が来たとき、この履歴があれば影響を受けるすべての画像を一度に特定でき、セット全体を再生成または撤去できます。

まず1つの撮影タイプ、1つのサイズ、小規模な製品サンプルから始め、HiAPI インターフェース経由で実行し、出力がレビューを通過してからテンプレートを拡張してください。

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む