image-portrait

image-portrait

このスキルは、Starchild におけるすべての一貫した人物同一性でのポートレート生成リクエストに使用します。

対象: プロフェッショナルなヘッドショット、デート・SNS 用写真、アートスタイルの変換、テーマ別・季節行事のポートレート、写真シリーズ、デジタルアバター、子ども・家族写真、ID・パスポート用写真。

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

---

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-portrait")
from exports import generate_portrait
result = generate_portrait(
    image_path="path/to/user/photo.jpg",
    style="professional",
)
print(result)
EOF

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

exec(open('skills/image-portrait/generate_portrait.py').read())
result = generate_portrait(
    image_path="path/to/user/photo.jpg",
    style="professional",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}

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

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

exec(open('skills/image-portrait/generate_portrait.py').read())
result = generate_portrait(
    face_image_url="https://example.com/photo.jpg",
    style="anime",
)

3. クイックスタート — テキストから画像生成（参照写真なし）

exec(open('skills/image-portrait/generate_portrait.py').read())
result = generate_portrait(
    prompt="a young woman in cyberpunk armor, neon city background, rain",
    model="nanopro",
)

image_path も face_image_url も指定されていない場合、スクリプトはテキストから画像生成のエンドポイントを使用します（/edit サフィックスなし）。

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

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

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

   ![photo](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") で送信してください。

---

4. パラメーター

パラメーター	必須	デフォルト	説明
image_path	いいえ	—	ユーザーの顔写真へのローカルワークスペースファイルパス
face_image_url	いいえ	—	ユーザーの顔写真の公開 HTTPS URL
style	いいえ	"professional"	プリセットスタイルキー（§5 を参照）
scene	いいえ	None	カスタムシーン記述（スタイルプロンプトに追加されます）
prompt	いいえ	None	完全なカスタムプロンプト — 設定すると style+scene を上書きします
model	いいえ	"nanopro"	モデル: "nano2"（最速 約15秒）、"nanopro"（バランス型 約25秒、デフォルト）、または "gpt"（最高品質 約150秒）
count	いいえ	1	生成する画像の数（1〜8）
aspect_ratio	いいえ	"1:1"	出力比率: 1:1、3:4、4:3、9:16、16:9

画像入力のルール:

• 一貫した人物同一性での生成（編集モード）には、image_path または face_image_url のいずれかを指定してください。
• 両方を指定した場合、image_path が優先されます。
• 純粋なテキストから画像生成（生成モード）には、両方とも省略してください。

プロンプトの優先順位: prompt > style + scene > style > デフォルト（professional）。

---

5. スタイルプリセット

A: 一貫性のある人物スタイル

スタイル	キー	最適な用途
プロフェッショナル証明写真	professional	LinkedIn、履歴書、企業向け
芸術的ポートレート	artistic	クリエイティブなポートフォリオ、ギャラリー
アニメ	anime	SNS、楽しいアバター
サイバーパンク	cyberpunk	ゲームプロフィール、SFファン
油絵	oil_painting	アートギフト、クラシックな雰囲気
水彩画	watercolor	柔らかな芸術的ポートレート
ヴィンテージ	vintage	レトロな美学、ノスタルジー
カジュアルライフスタイル	casual	SNS、個人ブログ

B: パーソナルショーケース / デート / ソーシャル

スタイル	キー	最適な用途
デート — カフェ	dating_cafe	デートアプリ、温かい雰囲気
デート — ビーチ	dating_beach	デートアプリ、夏の雰囲気
デート — 街	dating_city	デートアプリ、都会的な雰囲気
デート — レストラン	dating_restaurant	デートアプリ、エレガントな雰囲気
旅行 — ヨーロッパ	travel_europe	旅行ブログ、SNS
旅行 — 日本	travel_japan	旅行ブログ、文化的
旅行 — トロピカル	travel_tropical	休暇、リゾート
スポーツ — ジム	sports_gym	フィットネスプロフィール
スポーツ — ランニング	sports_running	アスリートプロフィール
SNS	social_media	Instagram、TikTok
LinkedIn	linkedin	プロフェッショナルなネットワーキング
パーソナルブランド	personal_brand	起業家、クリエイター

D: テーマ別 / シーンポートレート

スタイル	キー	最適な用途
クリスマス	christmas	ホリデーグリーティング、SNS
ハロウィン	halloween	ホリデーの楽しみ
卒業	graduation	節目のお祝い
結婚式	wedding	結婚式の計画、セーブ・ザ・デート
ビジネススピーチ	business_speech	スピーカープロフィール
ミュージシャン	musician	音楽プロモーション
シェフ	chef	フードブログ、レストラン
アウトドアアドベンチャー	outdoor_adventure	アドベンチャーブログ
ペットと一緒	pet_together	ペット好きのプロフィール
読書	reading	読書会、文学
夜の街	night_city	アーバンライフスタイル
漢服（中国の伝統衣装）	hanfu	文化的、コスプレ

O: デジタルアバター

スタイル	キー	最適な用途
3D カートゥーン	avatar_3d	SNS アバター、ピクサー風
ゲーミングアバター	avatar_gaming	ゲームプロフィール、RPG
VTuber	avatar_vtuber	配信、VTuber

T: 子供と家族

スタイル	キー	最適な用途
子供のポートレート	child_portrait	家族の記念品
家族写真	family_photo	家族のポートレート

U: ID / パスポート写真

スタイル	キー	最適な用途
ID 写真（白背景）	id_photo_white	パスポート、運転免許証
ID 写真（青背景）	id_photo_blue	ビザ、就労許可証

---

6. モデル選択ガイド

モデル	キー	速度	品質	最適な用途
Nano Banana 2	nano2	約15秒	良好	簡単なドラフト、素早い反復、大量生成。
NanoPro	nanopro	約25秒	より良好	すべてのリクエストのデフォルト。速度と品質のバランス。
GPT Image 2	gpt	約150秒	最高	ユーザーが「最高品質」または「ベスト品質」を明示的に求めた場合。複雑なシーン。

判断ルール:

1. デフォルト: ユーザーが明示的に別のものを要求しない限り、常に nanopro を使用します。
2. nano2 を使用する場合: ユーザーが最速の結果を求める、スタイルを反復している、多数の画像を生成している、または「クイック」「ドラフト」「高速」と言った場合。
3. gpt を使用する場合: ユーザーが「最高品質」「ベスト品質」「プレミアム」と言った場合、またはシーンが非常に複雑で多くの具体的な詳細を含む場合。

# Default (fast)
result = generate_portrait(image_path="photo.jpg", style="anime")

# High quality (user requested)
result = generate_portrait(image_path="photo.jpg", style="anime", model="gpt")

---

7. カスタムシーンの例

# Style + custom scene
result = generate_portrait(
    image_path="uploads/my_photo.jpg",
    style="professional",
    scene="in a modern office with city skyline view",
)

# Custom scene only (defaults to professional style base)
result = generate_portrait(
    image_path="uploads/my_photo.jpg",
    scene="standing on a beach at sunset, golden hour lighting",
)

# Fully custom prompt (overrides everything)
result = generate_portrait(
    image_path="uploads/my_photo.jpg",
    prompt="portrait of a person as a medieval knight, full plate armor, castle background, dramatic lighting, oil painting style",
)

# Different aspect ratio
result = generate_portrait(
    image_path="uploads/my_photo.jpg",
    style="cyberpunk",
    aspect_ratio="9:16",
)

# Multiple images
result = generate_portrait(
    image_path="uploads/my_photo.jpg",
    style="dating_cafe",
    count=4,
)

---

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

ユーザーのリクエストがどのプリセットスタイルにも一致しない場合、またはカスタムの prompt を構築する必要がある場合は、以下のガイドラインに従ってください（参照スキルから導出: ai-headshot-generation、ai-avatar-generation、style-transfer、portrait-enhancement、character-design-sheet、avatar-portrait、nano-banana-pro、pet-portrait-generation）。

自動的な類似性の保持

参照画像が提供された場合（編集モード）、スクリプトはすべてのプロンプトの先頭に類似性保持の指示を自動的に追加します。これにより、生成されるポートレートが被写体の顔のアイデンティティを保持することが保証されます。類似性の指示を手動で追加する必要はありません。スクリプトが処理します。

例外: アバタースタイル（avatar_3d、avatar_gaming、avatar_vtuber）は、写真のような類似性よりも様式化が優先されるため、類似性のプレフィックスをスキップします。

7 要素のプロンプト構造

効果的なポートレートプロンプトには、これらの要素を含める必要があります（nano-banana-pro スキルより）:

[subject], [outfit/attire], [pose/action], [expression], [background/setting], [lighting], [style/quality modifiers]

主要な原則

1. 類似性とスタイルのバランス（avatar-portrait スキルより）:

   • 写実的すぎる = 要求されたスタイルを無視する
   • 様式化しすぎる = 元の人物との類似性を失う
   • 様式化されたポートレートの場合: 「様式化されているが個々の特徴を維持する」ことを強調する
   • 写実的な場合: 「顔の特徴を認識可能に保つ」ことを強調する

2. ライティングは重要 — 常にライティングの種類を指定してください:

   • スタジオ: 「柔らかく拡散したスタジオライティング」、「レンブラントのキアロスクーロライティング」
   • 自然: 「ゴールデンアワーの暖かい光」、「木々を通る木漏れ日」
   • ドラマチック: 「ドラマチックなリムライト」、「ボリュメトリックライトビーム」、「ネオングロー」
   • フラット: 「影のない均一なフラットライティング」（証明写真用）

3. 背景の具体性 — 曖昧な背景は悪い結果を生みます:

   • ❌ 「素敵な背景」
   • ✅ 「ガラス窓と街の景色があるぼかされたモダンなオフィス」
   • ✅ 「クリーンでニュートラルなグレーのグラデーションスタジオ背景」
   • ✅ 「背景スタイルはキャラクタースタイルに合わせるべき」（アバター用）

4. レンズ/カメラのヒント — モデルがフレーミングを理解する助けになります:

   • 「85mm レンズの見え方、浅い被写界深度」（ポートレート）
   • 「頭と肩のフレーミング」（ヘッドショット）
   • 「全身、クリーンな白い背景」（キャラクターデザイン）
   • 「顔のクローズアップ、縦向き」（表情/アバター）

5. 品質アンカー — スタイルの品質参照を追加します:

   • 「プロフェッショナルな写真品質」、「雑誌の表紙品質」
   • 「ナショナル ジオグラフィックの写真スタイル」（アドベンチャー）
   • 「リーグ・オブ・レジェンドのスプラッシュアートスタイル」（ゲーミング）
   • 「ピクサーとディズニーのアニメーションスタイル」（3D アバター）
   • 「スタジオジブリにインスパイアされた」（アニメ）
   • 「ファインアートの水彩画の見え方」（水彩）

6. テクスチャと素材 — 芸術的なスタイルの場合、媒体を指定します:

   • 「目に見えるインパストの筆致、キャンバスのテクスチャ」（油絵）
   • 「自由で表現力豊かな水彩スタイル、柔らかいエッジ、美しい色のにじみとウォッシュ」（水彩）
   • 「自然なフィルムグレイン、Kodak Portra エミュレーション」（ヴィンテージ）
   • 「セルシェーディング、クリーンな線画、太い輪郭線」（アニメ）
   • 「目に見えるピクセルだが、ピクセル化された写真フィルターではない」（ピクセルアート）

7. 表情のガイダンス — ムードについて具体的に:

   • ❌ 「笑顔」
   • ✅ 「温かく本心からの笑顔、自信に満ちた親しみやすい表情」
   • ✅ 「口を閉じたニュートラルで穏やかな表情」（証明写真）
   • ✅ 「情熱的な表情、エネルギッシュ」（ミュージシャン）

例: カスタムプロンプトの構築

ユーザー: 「魔法の森で魔法使いになった自分の写真が欲しい」

result = generate_portrait(
    image_path="uploads/photo.jpg",
    prompt=(
        "fantasy wizard portrait, wearing mystical purple robes with glowing runes, "
        "ancient wooden staff with crystal orb, wise powerful expression, "
        "enchanted forest background with bioluminescent plants and floating particles, "
        "dramatic magical lighting with ethereal glow, "
        "high fantasy art style, detailed digital painting quality"
    ),
)
# Note: likeness prefix is auto-added because image_path is provided

例: ピクセルアートアバター（avatar-portrait スキルより）

ユーザー: 「レトロなピクセルアートのアバターを作って」

result = generate_portrait(
    image_path="uploads/photo.jpg",
    prompt=(
        "retro 16-bit pixel art portrait, visible pixels with clean lines, "
        "rich colors, consistent shading, stylized but maintains individual features, "
        "warm sunset cityscape background in matching pixel art style, "
        "head and shoulders, square format"
    ),
)

---

9. 写真シリーズ

1 回の呼び出しで、テーマに沿ったポートレートの調整されたセットを生成します。スタイル/シーンのカスタムリストを渡してください。エージェントはユーザーのリクエストに基づいてリストを組み立てます。

exec(open('skills/image-portrait/generate_portrait.py').read())
result = generate_series(
    image_path="uploads/my_photo.jpg",
    series=[
        {"style": "professional"},
        {"style": "casual", "scene": "at a rooftop bar, sunset"},
        {"style": "anime"},
        {"prompt": "portrait as a superhero, cape flowing, city skyline"},
    ],
)
# result -> {"success": True, "images": [...4 images...], "series": "custom"}

リスト内の各項目は、オプションのキーを持つ dict です:

• style — §7 の任意のスタイルキー（例: "professional"、"anime"、"cyberpunk"）
• scene — シーンの説明を上書きします（スタイルテンプレートと組み合わせて）
• prompt — 完全にカスタムなプロンプト（style/scene を無視します）

---

10. インテント認識ガイド

この表を使用して、ユーザーのリクエストを正しいスタイル/パラメータにマッピングしてください:

ユーザーの発言	スタイル	備考
"professional photo", "headshot", "LinkedIn photo"	professional または linkedin
"dating photo", "dating app", "Tinder photo"	dating_cafe / dating_beach / dating_city	どの雰囲気かを確認する
"anime me", "anime version", "cartoon me"	anime
"cyberpunk", "sci-fi portrait"	cyberpunk
"oil painting", "classical portrait"	oil_painting
"watercolor portrait"	watercolor
"vintage photo", "retro"	vintage
"casual photo", "lifestyle"	casual
"travel photo in Paris/Europe"	travel_europe
"travel photo in Japan/Tokyo/Kyoto"	travel_japan
"beach photo", "tropical"	travel_tropical または dating_beach
"gym photo", "fitness"	sports_gym
"Christmas photo"	christmas
"Halloween photo"	halloween
"graduation photo"	graduation
"wedding photo"	wedding
"chef photo", "cooking"	chef
"musician", "on stage"	musician
"with my dog/pet"	pet_together
"reading", "bookish"	reading
"night city", "urban night"	night_city
"hanfu", "Chinese traditional"	hanfu
"3D avatar", "Pixar style"	avatar_3d
"gaming avatar", "RPG character"	avatar_gaming
"VTuber avatar"	avatar_vtuber
"kid photo", "children's portrait"	child_portrait
"family photo"	family_photo
"passport photo", "ID photo"	id_photo_white	デフォルトは白背景
"visa photo"	id_photo_blue	青背景
"photo series", "set of photos"	generate_series() を使用	スタイルからカスタムリストを組み立てる
"highest quality", "best quality"	任意のスタイル + model="gpt"
プリセットにないカスタムシーン	scene= または prompt= を使用

このスキルを使用すべきでない場合（ルーティング）

このスキルの中核となる契約は本人同一性の保持です。参照写真が提供された場合、すべてのプロンプト（3 つの avatar_* スタイルを除く）の先頭に類似性プレフィックス（「被写体の正確な顔の特徴を保持する…」）が付加されます。つまり:

• ユーザーが顔/本人性を大幅に変更したい、または人物を完全に再想像したい場合（例:「別人のように見せて」、「キャラクターの大幅な再デザイン」）→ image-create（テキストから画像）にルーティングしてください。類似性プレフィックスがスタイル化と競合し、イテレーションが収束しません。
• ユーザーが強いスタイル化を望むが、認識可能であり続ける場合 → ここにとどまり、anime / avatar_3d などを使用してください。
• ユーザーが人物以外の写真を編集したい場合 → image-edit。

2 回以上のイテレーション後も参照写真の見た目から離れられないリクエストは、類似性契約が設計どおりに機能している証拠です。再プロンプトするのではなく、スキルを切り替えてください。

---

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

ファイル	目的
generate_portrait.py	コアスクリプト: 送信 → ポーリング → ダウンロード。ローカルファイル（base64）と URL、すべてのスタイル、カスタムシーン、3 つのモデル（nano2/nanopro/gpt）を処理します。
exports.py	他のスキルによるプログラム的な使用のために generate_portrait、generate_series、STYLE_PROMPTS を再エクスポートします。
_cost_track.py	コスト追跡ヘルパー — sc-proxy ヘッダーを介して呼び出しごとのコストを記録します。

---

12. ローカルテスト

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

# Single portrait
FAL_KEY=your-fal-key python3 skills/image-portrait/generate_portrait.py photo.jpg anime 1 nanopro

# Args: <image_path_or_url> [style] [count] [model]

---

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

問題	対処法
File not found: ...	ワークスペースのパスを確認してください。ファイルが存在している必要があります
Unsupported image format	.jpg、.jpeg、.png、.webp、または .bmp を使用してください
Image too large	アップロード前に 10 MB 未満にリサイズしてください
face_image_url must be a public HTTP(S) URL	ローカルファイルには image_path を使用するか、有効な https:// URL を指定してください
HTTP 402 insufficient_credits	残高をチャージしてください。コストは送信時に事前課金されます
HTTP 403 endpoint_not_allowed	sc-proxy は承認された fal エンドポイントのみを許可します。管理者に問い合わせてください
上流で生成が FAILED	プロンプトを簡素化し、顔写真が鮮明で十分な明るさであることを確認して、再試行してください
ジョブが IN_PROGRESS のまま 10 分以上停滞	request_id を保存し、後で再試行してください
顔の一貫性が低い	明るい照明の下で、正面を向いた鮮明な写真を使用してください。集合写真は避けてください
gpt モデルが遅すぎる	より高速な結果を得るには nanopro（デフォルト）に切り替えてください

---

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

• 呼び出し元 → 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 を記録します。

モデルエンドポイント

モデル	編集（参照画像あり）	生成（テキストのみ）
nano2	fal-ai/nano-banana-2/edit	fal-ai/nano-banana-2
nanopro	fal-ai/nano-banana-pro/edit	fal-ai/nano-banana-pro
gpt	openai/gpt-image-2/edit	openai/gpt-image-2

---