image-portrait

image-portrait

在 Starchild 上处理所有身份一致的人像生成请求时，请使用此技能。

涵盖：职业头像、约会／社交照片、艺术风格迁移、主题／节日人像、照片系列、数字头像、儿童／家庭照片、身份证／护照照片。

**核心原则：**调用提供的脚本。不要重新实现代理／计费相关流程。

---

1. 快速开始 — 单张人像（最常见）

⚠️ 执行上下文 — 请先阅读。 下面的代码块是 Python，不是 shell 命令。Starchild 的 bash 工具 运行 /bin/bash -c，无法解析 exec(open(...)) — 直接将它们粘贴到 bash 命令中 会导致 syntax error near unexpected token 'open'。 此外，在 python3 -c 中使用 exec(open(...)) 会因脚本使用 __file__ 解析路径而 报错 NameError: __file__。

通过 bash 工具调用时，请使用 python3 - <<'EOF' 和 from exports import：

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

此处的 heredoc（<<'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，并以 data 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	社交媒体、有趣的头像
赛博朋克	cyberpunk	游戏个人资料、科幻爱好者
油画	oil_painting	艺术礼物、古典风格
水彩	watercolor	柔和的艺术肖像
复古	vintage	复古美学、怀旧风格
休闲生活风	casual	社交媒体、个人博客

B：个人展示／约会／社交

风格	键	适用场景
约会 — 咖啡馆	dating_cafe	约会应用、温馨氛围
约会 — 海滩	dating_beach	约会应用、夏日氛围
约会 — 城市	dating_city	约会应用、都市氛围
约会 — 餐厅	dating_restaurant	约会应用、优雅氛围
旅行 — 欧洲	travel_europe	旅行博客、社交媒体
旅行 — 日本	travel_japan	旅行博客、文化主题
旅行 — 热带	travel_tropical	度假、度假村
运动 — 健身房	sports_gym	健身个人资料
运动 — 跑步	sports_running	运动风个人资料
社交媒体	social_media	Instagram、TikTok
LinkedIn	linkedin	职业社交
个人品牌	personal_brand	创业者、创作者

D：主题／场景肖像

风格	键	适用场景
圣诞节	christmas	节日问候、社交媒体
万圣节	halloween	节日趣味主题
毕业	graduation	里程碑庆祝
婚礼	wedding	婚礼筹备、预留日期通知
商务演讲	business_speech	演讲者个人资料
音乐人	musician	音乐宣传
厨师	chef	美食博客、餐厅
户外探险	outdoor_adventure	探险博客
与宠物合影	pet_together	宠物爱好者个人资料
阅读	reading	读书俱乐部、文学主题
夜间城市	night_city	都市生活方式
汉服（中国传统服饰）	hanfu	文化主题、角色扮演

O：数字头像

风格	键	适用场景
3D 卡通	avatar_3d	社交头像、Pixar 风格
游戏头像	avatar_gaming	游戏个人资料、RPG
VTuber	avatar_vtuber	直播、VTuber

T：儿童与家庭

风格	键	适用场景
儿童肖像	child_portrait	家庭纪念
家庭照片	family_photo	家庭肖像

U：身份证／护照照片

风格	键	适用场景
身份证照片（白底）	id_photo_white	护照、驾驶证
身份证照片（蓝底）	id_photo_blue	签证、工作许可

---

6. 模型选择指南

模型	键	速度	质量	适用场景
Nano Banana 2	nano2	~15s	良好	快速草稿、快速迭代、批量生成。
NanoPro	nanopro	~25s	更好	所有请求的默认选择。速度和质量均衡。
GPT Image 2	gpt	~150s	最佳	用户明确要求“最高质量”或“最佳质量”时。复杂场景。

决策规则：

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 skill）：

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

核心原则

1. 相似度与风格的平衡（来自 avatar-portrait skill）：

   • 过于逼真 = 忽略所需风格
   • 过于风格化 = 失去与原人物的相似度
   • 对于风格化肖像：强调“风格化，但保留个人特征”
   • 对于照片级写实肖像：强调“保留可识别的面部特征”

2. 光线至关重要——务必指定光线类型：

   • 影棚： “柔和的漫射影棚光线”、“伦勃朗式明暗对照光线”
   • 自然： “黄金时段的暖光”、“穿过树木的斑驳阳光”
   • 戏剧性： “戏剧性的轮廓光”、“体积光束”、“霓虹光晕”
   • 平光： “均匀的平光，无阴影”（用于证件照）

3. 明确指定背景——模糊的背景描述会导致效果不佳：

   • ❌“漂亮的背景”
   • ✅“带玻璃窗和城市景观的现代办公室虚化背景”
   • ✅“干净的中性灰渐变影棚背景”
   • ✅“背景风格应与角色风格相匹配”（用于头像）

4. 镜头／相机提示——帮助模型理解构图：

   • “85mm 镜头效果，浅景深”（肖像）
   • “头部和肩部构图”（头像照）
   • “全身像，干净的白色背景”（角色设计）
   • “面部特写，纵向构图”（表情／头像）

5. 质量基准——添加风格质量参考：

   • “专业摄影品质”、“杂志封面品质”
   • “《国家地理》摄影风格”（冒险主题）
   • “《英雄联盟》宣传图风格”（游戏）
   • “Pixar 和 Disney 动画风格”（3D 头像）
   • “受 Studio Ghibli 启发”（动漫）
   • “精美艺术水彩画效果”（水彩）

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 skill）

用户：“给我做一个复古像素艺术头像”

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. 肖像系列

一次调用即可生成一组主题统一的肖像。传入自定义风格／场景列表——Agent 会根据用户的请求整理列表。

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 — 完全自定义的提示词（忽略风格／场景）

---

10. 意图识别指南

使用此表将用户请求映射到正确的风格/参数：

用户说	风格	备注
“专业照片”、“头像照”、“LinkedIn 照片”	professional 或 linkedin
“约会照片”、“交友应用照片”、“Tinder 照片”	dating_cafe / dating_beach / dating_city	询问用户想要哪种氛围
“把我变成动漫风”、“动漫版”、“把我变成卡通风”	anime
“赛博朋克”、“科幻肖像”	cyberpunk
“油画”、“古典肖像”	oil_painting
“水彩肖像”	watercolor
“复古照片”、“怀旧风”	vintage
“休闲照片”、“生活方式照”	casual
“在巴黎/欧洲拍的旅行照”	travel_europe
“在日本/东京/京都拍的旅行照”	travel_japan
“海滩照片”、“热带风”	travel_tropical 或 dating_beach
“健身房照片”、“健身照”	sports_gym
“圣诞照片”	christmas
“万圣节照片”	halloween
“毕业照”	graduation
“婚礼照片”	wedding
“厨师照片”、“烹饪照”	chef
“音乐家”、“在舞台上”	musician
“和我的狗/宠物一起”	pet_together
“阅读照”、“书卷气”	reading
“夜晚城市”、“都市夜景”	night_city
“汉服”、“中国传统服饰”	hanfu
“3D 头像”、“皮克斯风格”	avatar_3d
“游戏头像”、“RPG 角色”	avatar_gaming
“VTuber 头像”	avatar_vtuber
“儿童照片”、“儿童肖像”	child_portrait
“家庭照片”	family_photo
“护照照片”、“证件照”	id_photo_white	默认白色背景
“签证照片”	id_photo_blue	蓝色背景
“照片系列”、“一组照片”	使用 generate_series()	根据风格组合自定义列表
“最高品质”、“最佳品质”	任意风格 + 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）
• 提交时会预扣费用。轮询和获取结果的调用免费。
• 本地文件会编码为 base64 数据 URI — 无需单独上传。
• 最终图片位于 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

---