HiAPI API で gpt-6.1-terra を使ってEC商品画像を生成する

商品画像ワークフローに gpt-6.1-terra が適している理由

商品画像は、ECパイプラインの中で最後まで人手による制作に依存している工程の一つです。商品リストシステムを統合する開発者は、最終的に同じ壁にぶつかります。すべての SKU にメイン画像、クリーンな商品画像、そして多くの場合シーン画像が必要であり、これまでは素材ごとにカメラマン、レタッチャー、そして一連のスケジュールプロセスが必要でした。HiAPI 経由で gpt-6.1-terra を呼び出すことで、この作業のアーキテクチャ上の位置が変わります。画像は一度アップロードされた静的ファイルではなく、もともと商品カタログデータを扱っていたのと同じサービスレイヤーが生成する成果物になるのです。

実際の変化はこうです。画像生成はカレンダー上の予定ではなく、コード内の関数になります。あなたの商品レコード（タイトル、属性、色、素材、利用シーン）が入力となり、モデル呼び出しが変換となり、出力はレビューキューを経てから公開されます。この再定位は、開発者が気にするいくつかの意思決定に影響します。

• 生成をどこで実行するか。 内部エンドポイントの背後、キューワーカー内、あるいは新規 SKU のビルドステップとして実行できます。HiAPI は統一されたインターフェースを公開しているため、どの環境に移行しても呼び出しの形は変わりません。
• 何が変わらないか（決定性）。 プロンプトテンプレート、スロット検証、出力チェックはあなたのコードです。モデルはレンダリングを担当し、一貫性はあなたが制御します。
• カタログをどう拡張するか。 新しい SKU には撮影は不要です。有効なプロンプトペイロードと、通過する検証ゲートがあれば十分です。

有用なメンタルモデルは4段階のパイプラインです。構造化された商品データが HiAPI を通じてモデル呼び出しに入り、結果がレビューキューに入り、承認された素材がストアフロントへ昇格します。このガイドのすべてはこの4段階のいずれかに対応しており、以降の章ではプロンプト、リクエスト、そしてその周辺の防御策を分解します。

gpt-6.1-terra をクリエイティブツールではなくレンダリング依存として捉えれば、残りの統合作業は通常のエンジニアリング課題になります。スキーマ検証、リトライ、バッチ処理、レビューゲートです。

商品画像プロンプトの構成

何千もの SKU で再利用できるプロンプトと、一度しか使えないプロンプトの違いは構造にあります。カタログで使えるプロンプトは、人間が自由に入力するテキストではなく、アプリケーションが商品データから埋める名前付きスロットの集合です。これを5つのスロットに分解します。

主体

商品が何であるかを、平易で具体的な名詞で記述します。カタログ属性から抽出します。カテゴリ、素材、色、サイズ、顕著な特徴です。事実に忠実に保ちます。モデルはあなたが記述した内容をレンダリングするので、商品レコードにない情報は省略します。

構図

商品が画面内のどこに位置し、画面のどれだけを占めるか。典型的な値は中央配置、俯瞰、斜め45度、フルフレームです。メイン画像と商品画像の分岐点はここです。

ライティング

照明の配置と雰囲気。柔らかなスタジオ光、硬い指向性ライト、窓から差し込む自然光。ライティングは主観的な品質に最も影響する単一スロットなので、小さな語彙を定義して再利用します。

背景

商品の周囲の環境。シームレスな白背景、淡いグレーのグラデーション、名前付きのシーンコンテキスト。カタログ作業では背景を単調で一貫させ、シーンの多様性はシーン画像のバリエーションに任せます。

制約

出力を使い物にするためのルール。テキストオーバーレイなし、提供された以外のロゴなし、余計な小道具なし、商品は中央画面を占有、ラベルの邪魔な反射なし。制約は、見栄えの良い画像を掲載可能な素材に変える鍵です。

コードでは各スロットを型付きフィールドとして扱います。主体と制約は商品レコードと固定ポリシーから、構図、ライティング、背景は画像タイプでインデックスされた小さな列挙から取得します。固定順序で組み合わせます。主体、構図、ライティング、背景、制約の順です。そうすれば2つのプロンプト間の diff は表現のノイズではなく実際の変化を反映します。あるプロンプトがレビューを通らなかったとき、全体を書き直すのではなく1つのスロットだけを調整できます。

再利用可能なプロンプトテンプレート

以下のテンプレートは5スロット構造に従います。各テンプレートは {placeholders} を含む骨組みで、コードが商品データから埋めます。バージョン管理に含めます。プロンプトテンプレートは使い捨ての文字列ではなく本番設定です。

メイン画像

Subject: {product_name}, {color}, {material}, {defining_feature}
Composition: centered, three-quarter angle, product occupies roughly 60% of frame
Lighting: soft studio lighting with a subtle key light from upper left
Background: light neutral gradient, no visible horizon
Constraints: no text, no logos, no extra props, label fully legible, no harsh shadows

カテゴリのランディングページやリストのメインビジュアルに使用します。ここでは SKU 間の一貫性が新規性よりも重要です。

商品画像

Subject: {product_name}, {color}, {material}
Composition: straight-on, product centered and fully visible, even margins on all sides
Lighting: flat even studio lighting, minimal shadow
Background: pure seamless white
Constraints: no text, no logos, no props, no reflection artifacts, product edges crisp against background

商品画像は最も制約の多いテンプレートです。雰囲気を加えないでください。マーケットプレイスや比較グリッドは統一性を好みます。

シーン画像

Subject: {product_name}, {color}, {material}
Composition: {placement}, product in natural use context, shallow depth of field
Lighting: {lighting_mood}, consistent with {scene_time_of_day}
Background: {scene_description}, complementary tones to product color
Constraints: product remains the focal point, no readable text, no brand logos other than supplied, no people faces in sharp focus

シーンテンプレートは最も変化が多いので、SKU ごとにコピーを書くのではなく、小さなシーンライブラリで駆動します。同じカテゴリの商品間でシーンを再利用して、一貫した見た目を保ちます。

3つのテンプレートすべてで、制約ブロックは交渉の余地がありません。新しいテンプレートを追加するときは、これらの制約を逐語的にコピーし、その上のスロットだけを変更します。

実行可能な gpt-6.1-terra HiAPI リクエスト

HiAPI 経由で gpt-6.1-terra を呼び出すのは、プラットフォーム上の他のあらゆるモデル呼び出しと同じパターンに従います。単一のエンドポイントにリクエストを送り、HiAPI キーで認証し、正規化されたレスポンスを受け取ります。流れはクライアント → HiAPI ゲートウェイ → モデルで、ゲートウェイがルーティングを担当し、結果または構造化エラーを返します。

設定

キーと base URL は環境変数に置き、決してソースコードに書き込みません。

export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

リクエストの形

リクエストはモデル識別子、テンプレートから組み立てたプロンプト、そして画像タイプに必要な生成パラメータを運びます。最小の Node.js リクエストは次のとおりです。

const res = await fetch(`${process.env.HIAPI_BASE_URL}/v1/generate`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-6.1-terra",
    prompt: composedPrompt,
    params: { aspect_ratio: "1:1" },
    metadata: { sku: product.sku, template: "packshot-v3" }
  })
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`HiAPI ${res.status}: ${err.message}`);
}

const data = await res.json();

統合の注意点

• メタデータを送る。 SKU とテンプレートバージョンを各リクエストに付加すると、下流のデバッグとレビューが大幅に楽になり、出力を商品カタログレコードに関連付けられます。
• 送信前に検証する。 テンプレートスロットが空のリクエストや制約ブロックがないリクエストを拒否します。これにより、コストを払う前に大多数のひどい生成を阻止できます。
• エラーを明示的に扱う。 検証エラー（ペイロードが誤り）と一時的な障害（リトライに意味がある）を区別します。以降の章でリトライ戦略を紹介します。
• 素材だけでなくレスポンスも保存する。 リクエストペイロードを生成画像と一緒に永続化し、レビュー判断が当時何をリクエストしたかに遡れるようにします。

テンプレートに必要な具体的なパラメータ名は画像タイプによって決まります。これらのパラメータをテンプレートバージョンで固定し、テンプレート変更を再現可能にします。

バッチ処理、検証、人的レビュー

1枚の画像を生成するのはデモです。カタログを生成するのは運用課題です。実用的なフローは、バッチ生成器が自動検証に入力し、何かがストアフロントに入る前に人的レビューゲートを設けることです。

バッチ処理

SKU をキーとするキューでバッチを駆動します。各 SKU について、正しいテンプレートからプロンプトをレンダリングし、HiAPI にリクエストを送信し、結果をステータス pending_review のステージングストレージに書き込みます。並列度は有界にします。固定ワーカープールとバックオフは無制限の並列より推論しやすく、障害の影響範囲も小さくなります。

自動検証

人間が出力を見る前に、安価なチェックを実行します。

• リクエストの完全性。 すべてのスロットが埋まり、制約が存在し、テンプレートバージョンが記録されている。
• 素材の基本チェック。 画像がデコード可能で、サイズがターゲットスロットに一致し、アスペクト比が正しい。
• 重複検出。 出力をハッシュ化し、SKU 間で同一の画像が即座に浮かび上がるようにする。通常はテンプレートに問題があることを意味する。
• ポリシーチェック。 制約ブロックに違反しているように見える出力（例：意図しないテキストや小道具）をフラグし、優先レビューに回す。

検証に失敗したものはすべて理由付きで failed_validation バケットに入ります。検証失敗を自動リトライしないでください。それらは一時的な問題ではなく、テンプレートやデータの問題を示しています。

人的レビューゲート

レビュアーは生成画像、ソース商品レコード、レンダリングされたプロンプト、テンプレートバージョンを見て、承認または却下を決定します。承認は素材をストアフロントへ昇格させ、却下は短い理由を記録します。この理由がフィードバックループです。同じテンプレートバージョンに対する却下のクラスタは、より積極的にリトライするのではなく、そのテンプレートを修正するシグナルです。

小規模な SKU サンプルから始め、すべての出力をレビューし、却下率が安定してからサンプルを拡大します。レビューゲートこそが、誤りを公開せずにスケールするための鍵です。

コスト、レイテンシ、障害処理

生成はコストも時間もかかるため、本番システムには両方に対する明確な戦略が必要です。料金はリクエストと生成パラメータで計量されるため、コストは手計算の数字ではなく SKU ごとに割り当てる予算として扱います。HiAPI アカウントの料金パネルで現在のレートを確認し、コードで制限を強制します。

コスト管理

• バッチごとの予算。 各バッチ実行に最大生成回数を割り当て、達したら停止します。
• テンプレートバージョンごとに1回だけ試行。 検証失敗したリクエストは同じプロンプトでリトライをトリガーせず、テンプレート責任者に戻します。
• 積極的にキャッシュ。 ある SKU のプロンプトスロットとテンプレートバージョンが変わっていなければ、承認済み素材を再利用し、再生成しません。
• テンプレートの階層化。 商品画像には最も安価で十分な設定を使い、より重い設定は品質が最も重要なメイン画像やシーン画像のバリエーションに残します。

レイテンシ

生成は瞬時ではないため、非同期結果として設計します。リクエストをキューに入れ、呼び出し元にタスク識別子を返し、ワーカーが結果到着時に書き込みます。タイムアウトはユーザー向け HTTP リクエストではなく、キューのリースに結び付けます。

障害処理の意思決定ツリー

リクエストが失敗したら、分類してから行動します。

1. 検証エラー（4xx）。 ペイロードを修正します。リトライしないでください。
2. レート制限または一時的サーバーエラー（429/5xx）。 指数バックオフとジッターでリトライし、少数の試行回数に制限します。試行を使い果たしたら、SKU を deferred としてマークし、続行します。
3. 同じ SKU で繰り返し失敗。 直近の承認済み素材があればそれにフォールバックし、なければエラーと共に人的レビューに回します。
4. バッチ全体の系統的失敗。 バッチを停止し、エラーを可視化し、キューを空にし続けないでください。続行するだけでは失敗が倍増します。

このパターンは他の外部依存と同じです。リトライ回数を制限し、既知の利用可能なフォールバックを優先し、障害をそのテンプレートを所有するチームに見えるようにします。

フルカタログ展開前のチェックリスト

gpt-6.1-terra をカタログ全体に向ける前に、このリストを項目ごとに確認してください。各項目はスケール時にのみ現れる故障モードに対応しています。

• テンプレートがバージョン管理されコードに保存されている。 各プロンプトに責任者と変更履歴があり、各リクエストでバージョン文字列が送信される。
• スロット検証がサーバー側で強制されている。 空の主体や制約ブロックの欠落は、リクエストがあなたのサービスを離れる前に拒否される。
• 自動チェックが人的レビューより先に実行される。 デコード、サイズ、重複、ポリシーチェックが自動化され、結果が保存される。
• レビューゲートが稼働し人員が配置されている。 却下は理由と共に記録され、理由のクラスタが毎週テンプレートバージョンごとに見直される。
• リトライとフォールバック戦略が定義されている。 検証エラーは決してリトライせず、一時的エラーは有界バックオフでリトライし、繰り返し失敗は直近の承認済み素材にフォールバックする。
• コストガードレールが設置されている。 バッチごとの生成上限、承認済み出力のキャッシュ、テンプレート階層化が設定されテストされている。
• メタデータが永続化されている。 SKU、テンプレートバージョン、プロンプトペイロードが各生成素材と一緒に保存される。
• ロールバックできる。 生成が無効化されてもストアフロントは手動画像を提供し続けられ、切り替えは設定変更1つで済む。
• パイロットバッチがレビューを通過している。 1つのカテゴリから始め、1つのブランドまたは地域に拡大し、その後全面展開する。

パイロットを実行し、数サイクルにわたって却下率とバッチ失敗率を観察してから、手動ワークフローを削除します。パイロットから本番へ移行する準備ができたとき、リクエストの形は変わらず、変わるのは量だけです。