photo-editor

MPSTATS フォトエディター

マーケットプレイスの商品カード用の AI 生成ビジュアルを作成する MPSTATS の内部サービスです。背景の削除・置き換え、アップスケーリング、色の変更、「使用中の商品」、プロンプト編集、撮影、インフォグラフィックに対応しています。

リクエストはすべて、scripts/ 内の既成スクリプトを通して実行します（Bash ツール、コードを書き換えないでください）。エンドポイントは非同期です。各スクリプトが送信 → ポーリング → ファイル保存まで処理します。画像はスクリプト内で base64 エンコードされます。

2 つの操作モード

意図的に選択してください。後続の処理がすべて変わります。

A. 技術的な操作（単一ステップ） — remove-background、upscale、replace-background、in-action、recolor、freeform。スクリプトを実行 → 結果を取得 → 納品します。リサーチやブリーフは不要です。具体的な操作を依頼された場合（「背景を削除して」「アップスケールして」「青に変えて」）に使用します。

B. デザインタスク（複数ステージ） — infographics と photoshoot。マーケットプレイスのデザイナーのように考えながら、デザイン作業を行います。購入者にとっての価値に関する依頼（「インフォグラフィックを作って」「商品カードを刷新して」「撮影が必要」）に使用します。references/ 内のステージガイドを使用してください。これらは思考のガイドであり、チェックリストではありません。

ステージ	ファイル	タイミング
1. リサーチ	references/01-research.md	ユーザーが「リサーチなし」を選択しない限り、モード B のデフォルトです。
2. ブリーフ	references/02-brief.md	モード B では生成前に必ず実施します。プロンプトの構成、スライドシリーズ、長さの上限、コンテンツフィルターなど、プロンプト作成全般も扱います。
3. 生成	references/03-generate.md	必ず実施します。実行前に「すぐに全件を生成しますか、それともまずテストフレームを作成しますか？」と尋ねてください。
4. 納品	references/04-deliver.md	必須です。結果を見せる前に読んでください。 パスの一覧ではなく、アンカーとなるキャプションを付けて Read ですべてのフレームを表示してください。

モード B の開始 — 必須の質問

タスクがモード B と判断されたら、最初に単一の質問をしてください。

リサーチを一通り実施しますか（競合分析、レビュー、ビジュアルベンチマーク）、それともプロンプト／説明をもとにすぐに生成しますか？

想定される回答と対応：

ユーザーの回答	対応
「リサーチあり」／「完全な分析」／無回答（明示的な拒否なし）	ステージ 1 → 2 → 3 → 4 をすべて実施します
「リサーチなし」／「すぐに生成」／「プロンプトから」	ステージ 1 を省略し、ステージ 2（ユーザーの説明からブリーフを作成）→ 3 → 4 に進みます。「リサーチを省略します。品質が下がる可能性はありますが、より早く完了します。」と明示してください。
ユーザーがメッセージ内に完成したプロンプトを提示した	そのまま使うか、ブリーフを通して確認するか（長さのチェック、ブロック構造、商品ロック）を確認してください。

例外： 最初のメッセージですでに「分析なし」／「リサーチなし」と明示されている場合は、質問せずにステージ 2 に進んでください。

設定

認証情報は config/.env（Git で追跡対象外）にあります。PHOTO_EDITOR_TOKEN（ヘッダー X-Mpstats-TOKEN）と、任意の PHOTO_EDITOR_BASE_URL（デフォルトは https://mpstats.io/api/big_data/proxy）を設定します。セットアップと変数については、config/README.md を参照してください。

トークンが設定されていない場合（または your_token_here の場合）、エージェントは必ず次のように尋ねてください。

I need an MPSTATS API token (X-Mpstats-TOKEN) for Photo Editor — get it from your MPSTATS account → API and send it over, I'll write it into config/.env.

出力先

結果をスキルフォルダーに保存しないでください — スキルはコードであり、出力はデータです。デフォルトの保存先は ~/.claude/output/photo-editor/<event_id>/ です。PHOTO_EDITOR_OUTPUT_DIR で変更できます。

モード B では、生成後にファイルを、わかりやすい名前（slide_1_hero.png など）を付けた、SKU ごとの整理されたフォルダーにコピーしてください。event_id には : が含まれ、一部の UI クライアントでは画像の表示に支障が出ます。また、SKU ごとに整理するとユーザーがファイルを見つけやすくなります。

マルチアングル入力：wb:<sku>

infographics.sh と photoshoot.sh では、最初の引数にファイルパスの代わりに wb:<sku> または wb:<wb-url> を指定できます。スキルは WB CDN からすべての商品写真をダウンロードします（wb-fetch-photos.sh、~/.claude/cache/photo-editor/wb-photos/<sku>/ にキャッシュ）：最初の写真は main_image、残りは reference_images になります（最大5枚。API はそれ以上を受け付けません）。

infographics.sh generate wb:164419278 "$PROMPT" 5

マルチアングル入力の場合、商品ロックの指示には「同じ向きを維持」ではなく、「商品の identity を維持」と記述してください。そうしないと、モデルが最初の写真の角度をすべてのスライドにコピーします。プロンプトの詳細は references/02-brief.md をご覧ください。

インフォグラフィック：N枚のスライドシリーズ

infographics.sh generate <img> "<prompt>" <count> は、1回の呼び出しで count 枚のスライドシリーズ（1～6枚）を作成します。流れは、test（試作用フレーム）→ 承認 → generate <N>、または auto（テストと生成を一度に実行）です。

出力は最低4フレームです。 エンドポイントは常に max(4, image_count) 枚の画像を返します。count=1～3 を指定しても、4枚が返されます。Photoshoot にはこの制限はありません。

プロンプトで設定するのは 全体的な方向性と各フレームのテーマ であり、各スライドのレイアウトではありません。そうしないと、1つのキャンバス上に2×3のコラージュが生成されます。プロンプト作成の詳細は references/02-brief.md をご覧ください。

モデル

マスク	ティア	デフォルト	アスペクト比	利用可能な対象
model_1	Standard	✅ インフォグラフィック以外すべて	1:1, 3:4, 4:3, 2:3, 3:2	すべてのエンドポイント
model_2	PRO	✅ インフォグラフィック	1:1, 3:4, 4:3, 2:3, 3:2	すべてのエンドポイント
model_3	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	すべてのエンドポイント
model_4	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	すべてのエンドポイント
model_5	PRO	—	1:1, 3:4, 4:3	freeform、photoshoot

バックエンドは model=auto を受け付けません。スキルが model_1（Standard）に解決します。インフォグラフィックのデフォルトは model_2（PRO）に固定されています。キリル文字の品質が最も優れています。理由に関する仮説がある場合に限り、モデルを明示的に指定してください。

スクリプト

スクリプト	使用する場面
remove-background.sh <img>	背景を削除する
upscale.sh <img>	解像度を上げる
replace-background.sh <img> <template_key>	商品を既成の背景に配置する
in-action.sh <img> <template_key>	商品を既成の使用シーンに配置する
recolor.sh <img> <#hex>	商品の色を変更する
freeform.sh <img> "<prompt>" [model] [ar] [refs]	自由形式の編集（1ステップ）
photoshoot.sh auto <img> "<prompt>" <count>	Photoshoot（テストから生成までを1つのコマンドで実行）
photoshoot.sh test | generate	テストフレームを個別に承認する必要がある場合
infographics.sh auto <img> "<prompt>" <count>	インフォグラフィック（テストから生成まで）
infographics.sh test | generate	Photoshoot と同様
templates.sh backgrounds [key]	replace-background 用の template_key を一覧表示する
templates.sh in-action [key]	in-action 用の template_key を一覧表示する
wb-fetch-photos.sh <sku-or-url> [max=8]	WB 商品写真をダウンロードする。wb:<sku> 入力時に自動で呼び出される
health.sh	サービスを確認する
run.sh <endpoint> <body_json>	汎用の送信とポーリング
poll.sh <event_id>	event_id が準備完了になるまで待機する

選択ガイド

• 「背景をすっきりさせて」→ A、remove-background.sh
• 「大きく／シャープにして」→ A、upscale.sh
• 「背景をスタジオ／大理石に変えて」→ A、templates.sh backgrounds → replace-background.sh
• 「使用中の商品を見せて」→ A、templates.sh in-action → in-action.sh
• 「#hex に色を変えて」→ A、recolor.sh
• 「照明を調整して／グレアを除去して／影を追加して」→ A、freeform.sh
• 「インフォグラフィック／Photoshoot を作成して」、「商品カード X を更新して」→ B、references/01-research.md から開始

エラー

メッセージ	対処方法
process_completed	完了しました。ファイルは保存されています
process_completed + output.image: []	コンテンツフィルターが原因です。プロンプトを言い換えてください（references/02-brief.md）
process_error	error.message を読み取り、ユーザーに表示してください
process_timeout	サーバーが制限時間内に完了しませんでした。件数を減らすか、モデルを変更してください
Prompt size exceeds maximum allowed length	最も多い原因はプロンプト内の改行（\n）であり、実際に上限を超えているわけではありません。 プロンプトを1行で渡してください。それでもエラーが続く場合は、プロンプトを短くしてください：references/02-brief.md → 技術的な制限。
AUTH_ERROR	認証情報が無効です。設定のセクションを参照してください
ローカルのポーリングタイムアウト	スクリプトがポーリングを停止しました。event_id は残っています — poll.sh <event_id>