image-edit

image-edit

このスキルは、Starchild 上のすべての画像編集および画像補正リクエストに使用します。

対象: 一般的な編集、背景の置き換え、超解像、古い写真の復元、カラー化、人物の削除、ポートレートのレタッチ (肌の滑らか化、シミの除去、歯のホワイトニング)、スリム化、カラーグレーディング、芸術的なフィルター、画像の合成、アウトペインティング、ローカル編集、テキストのレンダリング、多角度からの生成、ビフォーアフター比較、車の色変更、カーラッププレビュー、フィットネス/医療の変化比較。

基本原則: 提供されたスクリプトを呼び出してください。プロキシ/課金の処理を再実装しないでください。

image-edit と他の画像スキルの使い分け:

• image-edit → ユーザーが既存の画像を編集、補正、または変換したい
• image-portrait → ユーザーが参照写真から顔/本人の特徴を保持したポートレートを作成したい
• image-create → ユーザーがテキストの説明から何かを生成したい (ソース画像なし)

---

1. クイックスタート — 基本的な編集 (最も一般的)

⚠️ 実行コンテキスト — まずこれを読んでください。 以下のコードブロックは Python であり、シェルコマンドではありません。Starchild の bash ツールは /bin/bash -c を実行するため、exec(open(...)) を解析できません — bash コマンドに直接貼り付けると syntax error near unexpected token 'open' で失敗します。 また、python3 -c 内の exec(open(...)) は、スクリプトがパス解決に __file__ を使用するため NameError: __file__ で失敗します。

bash ツール経由で呼び出す場合は、from exports import とともに python3 - <<'EOF' を使用してください:

python3 - <<'EOF'
import sys
sys.path.insert(0, "skills/image-edit")
from exports import edit_image
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="make the sky more dramatic with golden sunset colors",
    action="enhance",
)
print(result)
EOF

ヒアドキュメント (<<'EOF') はすべての引用符と改行を保持します — エスケープは不要です。

exec(open('skills/image-edit/edit_image.py').read())
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="make the sky more dramatic with golden sunset colors",
    action="enhance",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}

スクリプトはローカルファイルを読み取り、base64 でエンコードして、データ URI として fal.ai に送信します — 手動での URL 公開は不要です。

2. クイックスタート — 公開 URL

exec(open('skills/image-edit/edit_image.py').read())
result = edit_image(
    image_url="https://example.com/photo.jpg",
    prompt="replace the background with a tropical beach",
    action="replace_bg",
)

ユーザーへの結果の配信 — 重要

ユーザーに生の fal.media URL を決して渡さないでください。 fal は制限的な CSP ヘッダーでファイルを提供します。唯一信頼できる配信経路は、すでにダウンロード済みのローカルファイルです:

1. 各画像の local_path (例: output/images/xxx.png) を使用してください — スクリプトは成功時に必ずダウンロードします。
2. ファイルが output/images/ に保存され、ワークスペースのファイルパネルで表示できることをユーザーに伝えてください。
3. Web チャンネルでは、ユーザーがチャット内でプレビューできるようにインラインで埋め込んでください:

   ![edited](output/images/<filename>.png)
   

4. Telegram / WeChat では、send_to_telegram(file_path="output/images/...", message_type="image") または send_to_wechat(file_path="output/images/...", message_type="image") で送信してください。

---

3. パラメータ

パラメータ	必須	デフォルト	説明
image_path	はい*	—	ソース画像のローカルワークスペースファイルパス
image_url	はい*	—	ソース画像の公開 HTTPS URL
prompt	いいえ	自動	編集指示 (何を変更するか)
action	いいえ	"edit"	操作タイプ (§4 を参照)
model	いいえ	"nanopro"	モデル: "nanopro" (高速 ~25 秒) または "gpt" (最高品質 ~150 秒)
aspect_ratio	いいえ	None	出力比率: 1:1、3:4、4:3、9:16、16:9。None = 元の比率を保持。

*image_path または image_url の少なくとも一方を指定する必要があります。両方が指定された場合、image_path が優先されます。

---

4. アクション — 操作タイプ

F: 複数画像 / 一般的な編集

アクション	キー	説明
一般的な編集	edit	プロンプトに従って画像を修正します
画像合成	blend	人物や被写体を新しい背景やシーンに配置します
アウトペインティング	extend	画像を現在の境界を超えて拡張します
ローカル編集	local_edit	画像の特定の領域のみを修正します
構造の再設計	restructure	レイアウト、グリッド、列数、要素の配置を変更します — 「構図を保持」を上書きします
テキストレンダリング	text_render	画像内にテキストを追加または変更します
マルチアングル	multi_angle	1 枚の写真から異なる視点を生成します
ビフォー / アフター	before_after	並べて比較する画像を生成します

G: プロフェッショナル編集

アクション	キー	説明
背景の置き換え	replace_bg	被写体を保持したまま背景を差し替えます
超解像	upscale	画像の解像度をアップスケールして高画質化します
写真の復元	restore	古い写真の傷、破れ、色あせを修復します
カラー化	colorize	白黒写真にリアルな色を追加します
人物の削除	remove_person	写真から特定の人物を削除します

V: レタッチ / 美容

アクション	キー	説明
ポートレートのレタッチ	retouch	肌のなめらかさ、シミの除去、歯のホワイトニング
スリム化	slim	顔や体のプロポーションをさりげなく調整します
強調	enhance	色補正、照明の改善、品質の向上
アーティスティックフィルター	filter	特定の芸術スタイルやフィルター効果を適用します

W: 医療 / フィットネスの比較

アクション	キー	説明
変化の比較	comparison	医療、フィットネス、変化のビフォー / アフター

X: 自動車

アクション	キー	説明
車の色変更	car_color	車両の色を変更します
カーラッププレビュー	car_wrap	車両へのラップやフィルムを可視化します

---

5. モデル選択ガイド

モデル	キー	速度	品質	最適な用途
NanoPro	nanopro	約25秒	良好	すべてのリクエストのデフォルトです。高速な反復に適しています。
GPT Image 2	gpt	約150秒	最高	ユーザーが明示的に「最高品質」または「ベスト品質」を求めた場合。複雑な編集。

判断ルール:

1. デフォルト: ユーザーが明示的に高品質を要求しない限り、常に nanopro を使用します。
2. gpt を使用する場合: ユーザーが「最高品質」「ベスト品質」「プレミアム」と言った場合、または編集で非常に精密なディテールの保持が必要な場合（例: 複雑なテキストレンダリング、繊細なインペインティング）。
3. nanopro を使用する場合: ユーザーが迅速な結果を求める場合、編集を反復している場合、または編集が単純な場合。

# Default (fast)
result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg")

# High quality (user requested)
result = edit_image(image_path="photo.jpg", prompt="remove background", action="replace_bg", model="gpt")

---

6. 意図認識ガイド

この表を使用して、ユーザーのリクエストを正しいアクションにマッピングします:

一般的な編集

ユーザーの発言	アクション	プロンプトのヒント
「この写真を編集して」「この画像を修正して」	edit	ユーザーの指示をプロンプトとして渡します
「ビーチに置いて」「シーンを変えて」	blend	対象のシーンを記述します
「画像を拡張して」「もっと広くして」「アウトペイントして」	extend	追加する内容を記述します
「シャツの色だけ変えて」「空だけ編集して」	local_edit	領域と変更内容を指定します
「列を減らして」「グリッドをシンプルにして」「レイアウトを並べ替えて」「最大 7 列にして」	restructure	対象の構造を明示的に記載します（行 / 列 / 配置）
「テキストを追加して」「画像に『Hello』と書いて」	text_render	テキストの内容と配置を指定します
「横から見せて」「別の角度で」	multi_angle	希望する角度を記述します
「ビフォーアフター」「違いを見せて」	before_after	変化の内容を記述します

プロフェッショナル編集

ユーザーの発言	アクション	プロンプトのヒント
「背景を削除」「背景を変更」「换背景」	replace_bg	新しい背景を説明してください
「アップスケール」「解像度を上げて」「品質を向上」	upscale	必要に応じて目標品質を指定してください
「古い写真を復元」「この損傷した写真を修正」「修复老照片」	restore	修正する具体的な損傷を説明してください
「カラー化」「白黒写真に色を追加」「上色」	colorize	必要に応じて期待する色を説明してください
「この人物を削除」「P掉某人」	remove_person	削除する人物を説明してください

レタッチ / 美容

ユーザーの発言	アクション	プロンプトのヒント
「レタッチ」「肌をなめらかに」「シミを除去」「磨皮美白」	retouch	レタッチのレベルを指定してください
「痩せさせて」「顔を細く」「瘦脸」	slim	調整する領域を指定してください
「色を強調」「照明を改善」「调色」	enhance	希望する仕上がりを説明してください
「フィルターを適用」「ヴィンテージ風にして」「滤镜」	filter	フィルターのスタイルを説明してください

医療 / フィットネス

ユーザーの発言	アクション	プロンプトのヒント
「手術前後」「フィットネストランスフォーメーション」	comparison	トランスフォーメーションの文脈を説明してください

自動車

ユーザーの発言	アクション	プロンプトのヒント
「車の色を変更」「赤にして」「汽车改色」	car_color	目標の色と仕上げを指定してください
「カーラッピング」「ビニールラップのプレビュー」「贴膜预览」	car_wrap	ラップの素材と色を説明してください

---

7. プロンプトエンジニアリングのベストプラクティス

プロンプトテンプレートシステム

すべてのアクションには、最適な結果を得るためにユーザーの指示をラップする組み込みのプロンプトテンプレートがあります。ユーザーの具体的な意図を渡すだけで、テンプレートが技術的な品質指示を自動的に追加します。

たとえば、ユーザーが「背景を夕日が沈むビーチにして」と言った場合：

result = edit_image(
    image_path="photo.jpg",
    prompt="a beautiful sunset beach with palm trees and golden light",
    action="replace_bg",
)
# The script wraps this into: "Replace the background of this image: a beautiful
# sunset beach with palm trees and golden light. Keep the foreground subject
# perfectly intact with clean edges. Match the lighting direction..."

主要な原則（リファレンススキルより）

1. 変更について具体的に述べる — 曖昧なプロンプトは悪い結果を生みます：

   • ❌ 「もっと良くして」
   • ✅ 「コントラストを上げ、温かみのある黄金色のトーンを加え、ディテールをシャープにする」

2. 保持するものを説明する — 特にローカル編集の場合：

   • ❌ 「シャツを変更して」
   • ✅ 「シャツの色をネイビーブルーに変更し、同じ生地の質感とシワを保つ」

3. 素材と仕上げを指定する — 車や製品の編集の場合：

   • ❌ 「青にして」
   • ✅ 「光沢のあるクリアコート仕上げの深いメタリックブルー」

4. 実世界のスタイルを参照する — フィルターや芸術的効果の場合：

   • ❌ 「芸術的にして」
   • ✅ 「ウェス・アンダーソン作品のような温かみのあるシネマティックなカラーグレーディングを適用する」

5. 復元 / カラー化には時代を説明する：

   • ❌ 「これをカラー化して」
   • ✅ 「この 1940 年代の家族写真を、当時の服装の色でカラー化する」

6. レタッチではレベルを指定する：

   • 軽度：「微妙な肌のなめらか化、自然な質感を保つ」
   • 中度：「プロフェッショナルなレタッチ、シミを除去、肌のトーンを均一にする」
   • 重度：「完全な美容レタッチ、肌をなめらかに、目を明るく、歯を白くする」

---

8. シナリオ別の使用例

背景の置き換え

exec(open('skills/image-edit/edit_image.py').read())

# Simple background swap
result = edit_image(
    image_path="uploads/portrait.jpg",
    prompt="a modern office with floor-to-ceiling windows and city skyline view",
    action="replace_bg",
)

# Studio background
result = edit_image(
    image_path="uploads/product.jpg",
    prompt="clean white studio background with soft shadow",
    action="replace_bg",
)

古い写真の復元

# Repair damaged photo
result = edit_image(
    image_path="uploads/old_family_photo.jpg",
    prompt="repair all scratches, tears, and stains; restore faded colors; enhance clarity",
    action="restore",
)

# Colorize black-and-white photo
result = edit_image(
    image_path="uploads/grandpa_1945.jpg",
    prompt="colorize with historically accurate colors for 1940s era, natural skin tones, period-appropriate clothing",
    action="colorize",
)

ポートレートのレタッチ

# Professional retouching
result = edit_image(
    image_path="uploads/selfie.jpg",
    prompt="professional portrait retouching: smooth skin while keeping natural texture, remove blemishes, subtle teeth whitening, brighten eyes",
    action="retouch",
)

# Slimming
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="subtle facial slimming, slightly more defined jawline, natural proportions",
    action="slim",
)

画像の強化

# Color grading
result = edit_image(
    image_path="uploads/landscape.jpg",
    prompt="cinematic color grading with warm golden tones, enhanced contrast, vibrant but natural colors",
    action="enhance",
)

# Artistic filter
result = edit_image(
    image_path="uploads/photo.jpg",
    prompt="oil painting style with visible brushstrokes, rich warm palette, impressionist feel",
    action="filter",
)

超解像アップスケーリング

result = edit_image(
    image_path="uploads/low_res.jpg",
    prompt="upscale to maximum quality, enhance fine details, reduce noise and compression artifacts",
    action="upscale",
)

人物の削除

result = edit_image(
    image_path="uploads/group_photo.jpg",
    prompt="remove the person on the far right, fill with the park background seamlessly",
    action="remove_person",
)

アウトペインティング（画像の拡張）

result = edit_image(
    image_path="uploads/cropped.jpg",
    prompt="extend the image to the left and right, continuing the mountain landscape naturally",
    action="extend",
    aspect_ratio="16:9",
)

車のカスタマイズ

# Car recolor
result = edit_image(
    image_path="uploads/my_car.jpg",
    prompt="change to a deep cherry red metallic paint with glossy clear coat",
    action="car_color",
)

# Car wrap preview
result = edit_image(
    image_path="uploads/my_car.jpg",
    prompt="matte black vinyl wrap with carbon fiber accents on the hood and mirrors",
    action="car_wrap",
)

ビフォー / アフター比較

# Fitness transformation
result = edit_image(
    image_path="uploads/fitness_photo.jpg",
    prompt="create a fitness transformation comparison showing a more toned and fit version",
    action="comparison",
)

ローカル編集

# Change specific element
result = edit_image(
    image_path="uploads/outfit.jpg",
    prompt="change only the dress color from red to emerald green, keep the same fabric texture",
    action="local_edit",
)

テキストのレンダリング

result = edit_image(
    image_path="uploads/poster_bg.jpg",
    prompt="add the text 'SUMMER SALE' in bold white letters centered at the top, with a subtle drop shadow",
    action="text_render",
)

高品質編集

# Use GPT model for best quality
result = edit_image(
    image_path="uploads/important_photo.jpg",
    prompt="professional color correction and enhancement for print publication",
    action="enhance",
    model="gpt",
)

---

9. 提供されるスクリプト

ファイル	目的
edit_image.py	コアスクリプト：画像を解決 → プロンプトを構築 → 送信 → ポーリング → ダウンロード。ローカルファイル（base64）と URL に対応し、すべてのアクション、2 つのモデルを扱います。
exports.py	他のスキルからプログラムで使用するために edit_image、ACTIONS、ACTION_PROMPTS、MODELS を再エクスポートします。
_cost_track.py	コスト追跡ヘルパー — sc-proxy ヘッダーを介して呼び出しごとのコストを記録します。

---

10. ローカルテスト

FAL_KEY 環境変数を設定すると、fal.ai を直接呼び出します（sc-proxy をバイパスします）：

# Basic edit
FAL_KEY=your-fal-key python3 skills/image-edit/edit_image.py photo.jpg "make it brighter" enhance nanopro

# Args: <image_path_or_url> [prompt] [action] [model]

---

11. トラブルシューティング

問題	解決策
File not found: ...	ワークスペースのパスを確認してください。ファイルが存在している必要があります
Unsupported image format	.jpg、.jpeg、.png、.webp、または .bmp を使用してください
Image too large	アップロード前に 10 MB 未満にリサイズしてください
image_url must be a public HTTP(S) URL	ローカルファイルには image_path を使用するか、有効な https:// URL を指定してください
Unknown action	§4 で有効なアクションを確認してください
HTTP 402 insufficient_credits	残高をチャージしてください。コストは送信時に事前請求されます
HTTP 403 endpoint_not_allowed	sc-proxy は承認済みの fal エンドポイントのみを許可します。管理者に連絡してください
編集が上流で FAILED	プロンプトを簡素化し、ソース画像が鮮明であることを確認して、再試行してください
ジョブが IN_PROGRESS のまま 10 分以上停滞	request_id を保存し、後で再試行してください
編集品質が低い	より高品質にするには model="gpt" を試してください。プロンプトをより具体的にしてください
何度繰り返してもレイアウト/グリッド/列数が変わらない	構造的な変更には action="restructure" を推奨します — そのテンプレートはレイアウト変更を必須とします。通常の edit には優先順位のフォールバックが追加されました（明示的な構造指示が構図の保持より優先されます）が、これは互換性のためのセーフティネットとしてのみ扱い、主要な手段とはしないでください
背景が完全に除去されない	明示的な背景の説明を付けて replace_bg アクションを使用してください
レタッチが不自然に見える	プロンプトに「keep natural texture」または「subtle」を追加してください

---

12. インフラストラクチャ（参考）

• 呼び出し元 → sc-proxy → queue.fal.run/{model} → fal モデルプロバイダー
• すべてのリクエストには Authorization: Key fake-falai-key-12345 を含める必要があります（プロキシが実際の FAL_KEY を注入します）
• 事前請求は送信時に発生します。ポーリング/結果取得の呼び出しは無料です。
• ローカルファイルはデータ URI として base64 エンコードされます — 別途アップロードの手順は不要です。
• 最終的な画像は https://*.fal.media/... に配置されます — パブリック CDN であり、ダウンロードに認証は不要です。
• コスト追跡は _cost_track.py で行います — sc-proxy のレスポンスヘッダーから X-Credits-Used を記録します。

モデルエンドポイント

モデル	編集エンドポイント
nanopro	fal-ai/nano-banana-pro/edit
gpt	openai/gpt-image-2/edit

---