STEPLP

仕様・API

AI画像ジョブ v0.1

gpt-image-2・一括生成・RAG。

LP AI 画像ジョブ v0.1

目的

管理 API 経由で OpenAI gpt-image-2 により LP 用画像を生成・編集し、S3 互換ストレージへ保存する。API キーはサーバのみ（ai-features.md）。

エンドポイント（管理）

メソッドパス説明
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobsジョブ作成（queued で返却。処理はバックグラウンド）
POST/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobs/batch一括ジョブ作成（全画像ステップまたは step_indices 指定）
GET/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobs/{job_id}状態・結果の取得（ポーリング用）
GET/v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobs/batches/{batch_id}一括ジョブの状態一覧

権限: editor 以上。OPENAI_API_KEY 未設定時は 503（error.code: ai_unavailable）。

リクエスト（POST）

JSON フィールド:

フィールド型必須説明
promptstring✓画像生成・編集の指示（最大 32000 文字）
modestringgenerate（既定）または edit
size_presetstring下表のいずれか。省略時 sp_vertical
qualitystringlow | medium | high | auto。省略時 low（OpenAI ガイドの試行向け推奨に合わせる）
source_object_keystringedit 時必須編集元オブジェクトキー。ws/{workspace_id}/lp/{lp_id}/ 配下のみ許可

サイズプリセット → OpenAI size

size_presetOpenAI size用途メモ
sp_vertical864x1536縦スワイプ LP 既定（9:16 ピクセル比。gpt-image-2 の size 制約に準拠）
sp_square1024x1024正方形
sp_landscape1536x1024横長補助

各 size_preset ごとに、ジョブワーカーは OpenAI へ送る直前のプロンプト末尾に、公式が Limitations で述べる 文字配置・構図の難しさと、Swipe LP ビューアの object-fit: cover を踏まえたレイアウト指示（英語）を追記する。prompt_plain と prompt_sha256 は ユーザーが POST した本文のまま（追記は監査用ハッシュに含めない）。

sp_vertical では、編集プレビューの一般的な端末ビューポート（約 390×844）と生成画像（864×1536）の比率差、および端末ごとの cover クロップを前提に、重要な見出し・価格・バッジ・CTA を 中央 70% 幅に収め、上下左右の外周は装飾背景として扱うよう追記する。安全領域は構図上の見えない目安であり、端末モック・枠・ガイド線・安全領域ボックスは画像内に描かせない。プレビュー比率は見た目の基準として維持し、端末差への耐性は生成物の余白設計で吸収する。

OpenAI Image API 呼び出しでは 画像生成ガイド に沿い、output_format: jpeg と output_compression（既定 92）を付与して受信・デコードのレイテンシを抑える。ストレージ上の拡張子・Content-Type は実バイト列から判定する。

ジョブ状態

status説明
queued受付済み、未処理
runningOpenAI 呼び出しまたは保存中
succeeded成功。result_url / result_object_key が有効
failed失敗。error_code / error_message を参照

レスポンス（GET / POST 201 本文）

主要フィールド（スネークケース JSON）:

  • id, status, mode, size_preset, quality
  • prompt_sha256, prompt_preview（監査用。全文は DB の prompt_plain に保持しレスポンスには含めない）
  • result_url, result_object_key, result_width, result_height（成功時）
  • error_code, error_message（失敗時）

成功時のオブジェクトキー規則は 手動アップロード（POST .../assets）と同型: ws/{workspace_id}/lp/{landing_page_id}/{ulid}_{filename}。

実装メモ

  • 処理本体は BackgroundTasks から run_lp_ai_image_job（別 DB セッション）。
  • 編集は OpenAI Images Edits（multipart）。参照元は自前ストレージから get_object_bytes。
  • 管理画面の各画像ステップでは ゼロから生成（generate + image_flow）と 元画像を微修正（edit + source_object_key + prompt）を選べる。編集元は当サーバのメディアURL（/media/ws/...）または定義に保存した media.objectKey。
  • 一括生成（v0.1）: POST …/image-jobs/batch で共通 batch_id を付与。auto_plan_steps（既定 true）で LPナレッジ・参考LP解析から画像枚数と各スライド補足を推測し、不足する画像ステップを自動追加してからジョブ化する。リクエストの definition は編集画面の未保存内容を含められる。各ジョブは単体の generate + image_flow と同じプロンプト組み立て。管理画面の「ナレッジから構成を推測して一括生成」から利用。
  • Workspace ブランド情報の横断参照は次版。

参考URL（LPナレッジ）

creatorKnowledge.referenceUrls に登録したURLは、POST …/creator-knowledge/analyze-reference-urls で実際に参照する。

種類処理
自社 …/p/{publicId}DB から公開定義を取得し、ステップ構成・補足をテキスト要約
その他の https URLスマホ幅（390px）でページ取得 → スクショ + ページ上の img / OG / favicon を収集 → Vision 要約。素材は ws/…/ref-assets/ に保存

結果は creatorKnowledge.referenceAnalyses に保存（下書き保存で定義に残る。公開・ZIP には含めない）。
取り込んだ画像は logoAssets / photoAssets にマージ（重複は objectKey / url で除外。ロゴ最大8・写真最大24）。
画像ジョブ（generate / edit）の prompt_plain には === REFERENCE LP / PAGE === ブロックとして注入される。generate 時は先頭ロゴの objectKey を knowledge_logo_object_key に記録（監査用）。

ナレッジ RAG（ゼロから生成）

generate + image_flow でジョブ作成時、サーバは creatorKnowledge をチャンク化し、当該スライドの補足＋役割＋トーンをクエリに OpenAI Embeddings（OPENAI_EMBEDDING_MODEL、未設定時 text-embedding-3-small）で top-k 検索する。結果は === RETRIEVED KNOWLEDGE === として prompt_plain に注入（embedding 失敗時はキーワード簡易マッチ）。

重複防止: === REFERENCE LP / PAGE === を付与するときは、knowledge_tone 内の Analyzed reference pages ブロックと RAG の参考URLチャンクは省略する（商品・訴求・トーンは BRAND CONTEXT と RAG に残す）。

取り込み済み logoAssets / photoAssets は === KNOWLEDGE ASSET CATALOG === に fileName 一覧を載せる。補足に ファイル名（または .png 等の拡張子付きヒント）が含まれると === MATCHED KNOWLEDGE ASSETS === を付与し、当該 objectKey を Images Edits の入力に自動切替（mode=edit・source_object_key）。このとき prompt_plain は 短い edit 専用文（compose_knowledge_asset_edit_prompt）とし、長い compose_prompt_plain 全文は使わない。

レイアウト種別（TOP / 手順 / 事例 / CTA / 一般 / 文字なし）は resolve_image_slide_layout_kind で一意に決め、compose_prompt_plain とワーカーの OpenAI 追記 suffix で同じ分類を使う。

解析前に画像生成すると、Web 側が自動で解析 API を呼ぶ（サーバ定義を更新）。

先頭画像スライド（TOP）

1枚目の画像スライドは、参照LPのような 文字入りモバイルLPヒーロー（大見出し・サブコピー・アイコン行・背景）を既定とする。LPナレッジの商品名・訴求は見出し素材としてプロンプトに渡す。補足で 見出し: … / サブ: … と書けばその文言を優先する。文字なし と書いた場合のみ文字少なめに戻す。

※ 生成物は 静止画（gpt-image-2）。動画ステップやループ動画は別機能（LP定義の video ステップ＋メディアアップロード）。

2枚目以降の画像スライド（セクション）

Swipe LP の画像ステップは 原則すべて画像内に読める日本語コピーあり（実 LP にテキストなしのページだけを置かない想定）。compose_prompt_plain が補足からレイアウト種別を選ぶ。

補足の意図（例）既定の見え方
（特になし・短い説明のみ）セクション見出し＋サブコピーまたはラベル付き箇条書き（一般セクション）
顧客の声・事例・メリット訴求 等セクション見出し＋短文引用（写真付きカード）
手順・利用の流れ・アイコンとテキスト・図解 等セクション見出し＋番号付きステップ（各ステップにアイコン＋短い日本語ラベル）
CTA・来店予約・ボタン 等短い見出し＋CTA ボタンモック
文字なし / テキストなし の明示のみ例外として文字控えめ

見出し: / サブ: が補足にあれば、スライド位置に関わらずその文言を優先する。

関連

ソース: docs/spec/ai-lp-image-jobs-v0.1.md