image-portrait

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

image-portrait

肖像图像生成（image-portrait）

Use this skill for all identity-consistent portrait generation requests on Starchild.

Covers: professional headshots, dating/social photos, artistic style transfers, themed/holiday portraits, photo series, digital avatars, children/family photos, ID/passport photos.

Core principle: call the provided script. Do not re-implement proxy/billing plumbing.

使用此技能处理Starchild平台上所有身份一致性肖像生成请求。

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

核心原则： 调用提供的脚本，不要重新实现代理/计费相关逻辑。

1. Quick start — single portrait (most common)

1. 快速入门——单张肖像（最常用）

python

exec(open('skills/image-portrait/generate_portrait.py').read())
result = generate_portrait(
    image_path="path/to/user/photo.jpg",
    style="professional",
)

python

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/..."}], ...}


The script reads the local file, base64-encodes it, and sends it to fal.ai as a data URI — no manual URL publishing needed.


该脚本会读取本地文件，将其base64编码后以数据URI形式发送至fal.ai——无需手动发布URL。

2. Quick start — public URL

2. 快速入门——公共URL

python

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

python

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

3. Quick start — text-to-image (no reference photo)

3. 快速入门——文本生成图像（无参考照片）

python

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",
)

When no

image_path

face_image_url

is provided, the script uses the text-to-image endpoint (no

/edit

suffix).

python

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

后缀）。

Delivering the result to the user — IMPORTANT

向用户交付结果——重要提示

Never hand the user the raw fal.media URL. fal serves files with restrictive CSP headers. The only reliable delivery path is the already-downloaded local file:

Use each image's
```
local_path
```
(e.g.
```
output/images/xxx.png
```
) — the script always downloads on success.
Tell the user the files are saved to
```
output/images/
```
and viewable in the workspace file panel.
On Web channel, embed inline so the user can preview in chat:
markdown
```
![photo](output/images/<filename>.png)
```

On Telegram / WeChat: send via

send_to_telegram(file_path="output/images/...", message_type="image")

send_to_wechat(file_path="output/images/...", message_type="image")

绝对不要直接将原始fal.media URL交给用户。fal提供的文件带有严格的CSP头，唯一可靠的交付方式是已下载的本地文件：

使用每张图片的
```
local_path
```
（例如
```
output/images/xxx.png
```
）——脚本在生成成功后总会自动下载文件。
告知用户文件已保存至
```
output/images/
```
，可在工作区文件面板中查看。
在Web渠道中，将图片嵌入聊天内容以便用户预览：
markdown
```
![photo](output/images/<filename>.png)
```

在Telegram/微信渠道：通过

send_to_telegram(file_path="output/images/...", message_type="image")

或

send_to_wechat(file_path="output/images/...", message_type="image")

发送。

4. Parameters

4. 参数说明

Parameter	Required	Default	Description
`image_path`	no	—	Local workspace file path to the user's face photo
`face_image_url`	no	—	Public HTTPS URL of the user's face photo
`style`	no	`"professional"`	Preset style key (see §5)
`scene`	no	`None`	Custom scene description (appended to style prompt)
`prompt`	no	`None`	Fully custom prompt — overrides style+scene when set
`model`	no	`"nanopro"`	Model: `"nano2"` (fastest ~15s), `"nanopro"` (balanced ~25s, default), or `"gpt"` (best quality ~150s)
`count`	no	`1`	Number of images to generate (1–8)
`aspect_ratio`	no	`"1:1"`	Output ratio: `1:1` , `3:4` , `4:3` , `9:16` , `16:9`

Image input rules:

Provide
```
image_path
```
OR
```
face_image_url
```
for identity-consistent generation (edit mode).
If both are given,
```
image_path
```
takes priority.
Omit both for pure text-to-image generation (generate mode).

Prompt priority:

prompt

style + scene

style

> default (

professional

参数名	是否必填	默认值	描述
`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. Style presets

5. 预设风格

A: Identity-consistent character styles

A: 身份一致性人物风格

Style	Key	Best for
Professional headshot	`professional`	LinkedIn, resume, corporate
Artistic portrait	`artistic`	Creative portfolio, gallery
Anime	`anime`	Social media, fun avatar
Cyberpunk	`cyberpunk`	Gaming profile, sci-fi fan
Oil painting	`oil_painting`	Art gift, classical look
Watercolor	`watercolor`	Soft artistic portrait
Vintage	`vintage`	Retro aesthetic, nostalgia
Casual lifestyle	`casual`	Social media, personal blog

风格	键值	适用场景
专业证件照	`professional`	LinkedIn、简历、企业场景
艺术肖像	`artistic`	创意作品集、画廊展示
动漫风格	`anime`	社交媒体、趣味头像
赛博朋克风格	`cyberpunk`	游戏资料、科幻爱好者
油画风格	`oil_painting`	艺术礼品、古典风格
水彩风格	`watercolor`	柔和艺术肖像
复古风格	`vintage`	复古美学、怀旧场景
休闲生活风格	`casual`	社交媒体、个人博客

B: Personal showcase / dating / social

B: 个人展示/约会/社交场景

Style	Key	Best for
Dating — cafe	`dating_cafe`	Dating app, warm vibe
Dating — beach	`dating_beach`	Dating app, summer vibe
Dating — city	`dating_city`	Dating app, urban vibe
Dating — restaurant	`dating_restaurant`	Dating app, elegant vibe
Travel — Europe	`travel_europe`	Travel blog, social media
Travel — Japan	`travel_japan`	Travel blog, cultural
Travel — tropical	`travel_tropical`	Vacation, resort
Sports — gym	`sports_gym`	Fitness profile
Sports — running	`sports_running`	Athletic profile
Social media	`social_media`	Instagram, TikTok
LinkedIn	`linkedin`	Professional networking
Personal brand	`personal_brand`	Entrepreneur, creator

风格	键值	适用场景
约会——咖啡馆	`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: Themed / scene portraits

D: 主题/场景肖像

Style	Key	Best for
Christmas	`christmas`	Holiday greeting, social
Halloween	`halloween`	Holiday fun
Graduation	`graduation`	Milestone celebration
Wedding	`wedding`	Wedding planning, save-the-date
Business speech	`business_speech`	Speaker profile
Musician	`musician`	Music promotion
Chef	`chef`	Food blog, restaurant
Outdoor adventure	`outdoor_adventure`	Adventure blog
Pet together	`pet_together`	Pet lover profile
Reading	`reading`	Book club, literary
Night city	`night_city`	Urban lifestyle
Hanfu (Chinese traditional)	`hanfu`	Cultural, cosplay

风格	键值	适用场景
圣诞主题	`christmas`	节日问候、社交场景
万圣节主题	`halloween`	节日趣味场景
毕业主题	`graduation`	里程碑纪念
婚礼主题	`wedding`	婚礼筹备、日期预告
商务演讲场景	`business_speech`	演讲者资料
音乐人场景	`musician`	音乐推广
厨师场景	`chef`	美食博客、餐厅宣传
户外探险场景	`outdoor_adventure`	探险博客
与宠物同框	`pet_together`	宠物爱好者资料
阅读场景	`reading`	读书俱乐部、文学场景
都市夜景	`night_city`	都市生活风格
汉服（中国传统服饰）	`hanfu`	文化场景、Cosplay

O: Digital avatar

O: 数字头像

Style	Key	Best for
3D cartoon	`avatar_3d`	Social avatar, Pixar style
Gaming avatar	`avatar_gaming`	Game profile, RPG
VTuber	`avatar_vtuber`	Streaming, VTuber

风格	键值	适用场景
3D卡通头像	`avatar_3d`	社交头像、皮克斯风格
游戏头像	`avatar_gaming`	游戏资料、RPG角色
VTuber头像	`avatar_vtuber`	直播场景、虚拟主播

T: Children & family

T: 儿童与家庭

Style	Key	Best for
Child portrait	`child_portrait`	Family keepsake
Family photo	`family_photo`	Family portrait

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

U: ID / passport photos

U: 身份证件/护照照片

Style	Key	Best for
ID photo (white bg)	`id_photo_white`	Passport, driver's license
ID photo (blue bg)	`id_photo_blue`	Visa, work permit

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

6. Model selection guide

6. 模型选择指南

Model	Key	Speed	Quality	Best for
Nano Banana 2	`nano2`	~15s	Good	Quick drafts, fast iteration, bulk generation.
NanoPro	`nanopro`	~25s	Better	Default for all requests. Balanced speed and quality.
GPT Image 2	`gpt`	~150s	Best	When user explicitly asks for "highest quality" or "best quality". Complex scenes.

Decision rules:

Default: always use
```
nanopro
```
unless the user explicitly requests otherwise.
Use
nano2
when: user wants fastest results, is iterating on styles, generating many images, or says "quick", "draft", "fast".
Use
gpt
when: user says "highest quality", "best quality", "premium", or the scene is very complex with many specific details.

python

undefined

模型	键值	速度	质量	适用场景
Nano Banana 2	`nano2`	~15秒	良好	快速草稿、快速迭代、批量生成
NanoPro	`nanopro`	~25秒	更优	所有请求的默认选项，平衡速度与质量
GPT Image 2	`gpt`	~150秒	最佳	用户明确要求“最高质量”或场景复杂包含大量细节时

决策规则：

默认选择： 除非用户明确要求，否则始终使用
```
nanopro
```
。
使用
nano2
的场景：用户需要最快结果、正在迭代风格、生成多张图像，或提到“快速”“草稿”“加急”等关键词。
使用
gpt
的场景：用户提到“最高质量”“最佳质量”“ premium”，或场景非常复杂且包含大量特定细节。

python

undefined

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")

---

result = generate_portrait(image_path="photo.jpg", style="anime", model="gpt")

---

7. Custom scene examples

7. 自定义场景示例

python

undefined

python

undefined

Style + custom scene

风格+自定义场景

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

result = generate_portrait( image_path="uploads/my_photo.jpg", style="professional", scene="身处现代化办公室，背景为城市天际线", )

Custom scene only (defaults to professional style base)

仅自定义场景（默认基于professional风格）

result = generate_portrait( image_path="uploads/my_photo.jpg", scene="standing on a beach at sunset, golden hour lighting", )

result = generate_portrait( image_path="uploads/my_photo.jpg", scene="站在日落时分的海滩上，金色时刻光线", )

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, )

---

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

---

8. Prompt engineering best practices

8. 提示词工程最佳实践

When the user's request doesn't match any preset style, or when you need to construct a custom

prompt

, follow these guidelines (derived from reference skills: ai-headshot-generation, ai-avatar-generation, style-transfer, portrait-enhancement, character-design-sheet, avatar-portrait, nano-banana-pro, pet-portrait-generation).

当用户的请求与任何预设风格不匹配，或需要构建自定义

prompt

时，请遵循以下准则（参考自ai-headshot-generation、ai-avatar-generation、style-transfer、portrait-enhancement、character-design-sheet、avatar-portrait、nano-banana-pro、pet-portrait-generation等技能）。

Automatic likeness preservation

自动身份保留

When a reference image is provided (edit mode), the script automatically prepends a likeness preservation instruction to every prompt. This ensures the generated portrait preserves the subject's facial identity. You do NOT need to add likeness instructions manually — the script handles it.

Exception: avatar styles (

avatar_3d

avatar_gaming

avatar_vtuber

) skip the likeness prefix because stylization takes priority over photographic likeness.

当提供参考图像时（编辑模式），脚本会自动在每个提示词前添加身份保留指令，确保生成的肖像保留主体的面部特征。你无需手动添加身份保留指令——脚本会自动处理。

例外情况：头像风格（

avatar_3d

、

avatar_gaming

、

avatar_vtuber

）会跳过身份保留前缀，因为风格化优先级高于照片级身份一致性。

The 7-element prompt structure

7要素提示词结构

Every effective portrait prompt should include these elements (from nano-banana-pro skill):

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

每个有效的肖像提示词应包含以下要素（来自nano-banana-pro技能）：

[主体], [服装/着装], [姿势/动作], [表情], [背景/场景], [光线], [风格/质量修饰词]

Key principles

核心原则

Likeness vs. style balance (from avatar-portrait skill):
- Too photorealistic = ignores requested style
- Too stylized = loses resemblance to source person
- For stylized portraits: emphasize "stylized but maintains individual features"
- For photorealistic: emphasize "keep facial features recognizable"
Lighting is critical — always specify lighting type:
- Studio: "soft diffused studio lighting", "Rembrandt chiaroscuro lighting"
- Natural: "golden hour warm light", "dappled sunlight through trees"
- Dramatic: "dramatic rim lighting", "volumetric light beams", "neon glow"
- Flat: "even flat lighting with no shadows" (for ID photos)
Background specificity — vague backgrounds produce poor results:
- ❌ "nice background"
- ✅ "blurred modern office with glass windows and city view"
- ✅ "clean neutral gray gradient studio background"
- ✅ "background style should match the character style" (for avatars)
Lens/camera hints — help the model understand framing:
- "85mm lens look, shallow depth of field" (portrait)
- "head and shoulders framing" (headshot)
- "full body, clean white background" (character design)
- "close-up face, portrait orientation" (expression/avatar)
Quality anchors — add style quality references:
- "professional photography quality", "magazine cover quality"
- "National Geographic photography style" (adventure)
- "League of Legends splash art style" (gaming)
- "Pixar and Disney animation style" (3D avatar)
- "Studio Ghibli inspired" (anime)
- "fine art watercolor painting look" (watercolor)
Texture and material — for artistic styles, specify medium:
- "visible impasto brushstrokes, canvas texture" (oil painting)
- "loose expressive watercolor style, soft edges, beautiful color bleeds and washes" (watercolor)
- "natural film grain, Kodak Portra emulation" (vintage)
- "cel-shaded, clean line art, bold outlines" (anime)
- "visible pixels but NOT a pixelated photo filter" (pixel art)
Expression guidance — be specific about mood:
- ❌ "smiling"
- ✅ "warm genuine smile, confident approachable expression"
- ✅ "neutral calm expression with mouth closed" (ID photo)
- ✅ "passionate expression, energetic" (musician)

身份与风格的平衡（来自avatar-portrait技能）：
- 过于写实 = 忽略用户要求的风格
- 过于风格化 = 失去与源人物的相似度
- 风格化肖像：强调“风格化但保留个人特征”
- 写实肖像：强调“保持面部特征可识别”
光线至关重要——始终指定光线类型：
- 影棚："柔和漫射影棚光线"、"伦勃朗明暗对比光线"
- 自然光："金色时刻暖光"、"透过树叶的斑驳阳光"
- 戏剧性光线："戏剧性轮廓光"、"体积光束"、"霓虹光晕"
- 平光："均匀无阴影平光"（适用于身份证件照）
背景具体化——模糊的背景会导致效果不佳：
- ❌ "好看的背景"
- ✅ "模糊的现代化办公室，带玻璃窗和城市景观"
- ✅ "干净的中性灰色渐变影棚背景"
- ✅ "背景风格应与人物风格匹配"（适用于头像）
镜头/相机提示——帮助模型理解构图：
- "85mm镜头效果，浅景深"（肖像）
- "头肩构图"（证件照）
- "全身，干净白色背景"（角色设计）
- "面部特写，竖版构图"（表情/头像）
质量锚点——添加风格质量参考：
- "专业摄影质量"、"杂志封面质量"
- "国家地理摄影风格"（探险场景）
- "英雄联盟原画风格"（游戏场景）
- "皮克斯和迪士尼动画风格"（3D头像）
- "吉卜力工作室风格"（动漫）
- "精美艺术水彩画效果"（水彩风格）
纹理与材质——艺术风格需指定媒介：
- "明显的厚涂笔触，画布纹理"（油画）
- "松散写意的水彩风格，柔和边缘，色彩自然晕染"（水彩）
- "自然胶片颗粒，柯达Portra胶片模拟"（复古风格）
- "赛璐璐风格，清晰线条，粗轮廓"（动漫）
- "可见像素但非像素化照片滤镜"（像素艺术）
表情引导——明确描述情绪：
- ❌ "微笑"
- ✅ "温暖真诚的微笑，自信亲和的表情"
- ✅ "中性平静的表情，嘴巴闭合"（身份证件照）
- ✅ "充满激情的表情，活力十足"（音乐人）

Example: building a custom prompt

示例：构建自定义提示词

User: "I want a photo of me as a wizard in a magical forest"

python

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"
    ),
)

用户："我想要一张我作为魔法师在魔法森林里的照片"

python

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

注意：因为提供了image_path，身份保留前缀会自动添加

undefined

undefined

Example: pixel art avatar (from avatar-portrait skill)

示例：像素艺术头像（来自avatar-portrait技能）

User: "Make me a retro pixel art avatar"

python

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"
    ),
)

用户："帮我做一个复古像素艺术头像"

python

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. Photo series

9. 照片系列生成

Generate a coordinated set of themed portraits in one call. Pass a custom list of styles/scenes — the agent assembles the list based on the user's request.

python

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"},
    ],
)

一次调用生成一组主题协调的肖像。传入自定义的风格/场景列表——根据用户请求组装列表。

python

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"}


Each item in the list is a dict with optional keys:
- `style` — any style key from §7 (e.g. `"professional"`, `"anime"`, `"cyberpunk"`)
- `scene` — override the scene description (combined with the style template)
- `prompt` — fully custom prompt (ignores style/scene)

---


列表中的每个元素是一个字典，包含可选键：
- `style` — 第7节中的任意风格键（例如`"professional"`、`"anime"`、`"cyberpunk"`）
- `scene` — 覆盖场景描述（与风格模板结合）
- `prompt` — 完全自定义提示词（忽略style/scene）

---

10. Intent recognition guide

10. 请求意图识别指南

Use this table to map user requests to the correct style/parameters:

User says	Style	Notes
"professional photo", "headshot", "LinkedIn photo"	`professional` or `linkedin`
"dating photo", "dating app", "Tinder photo"	`dating_cafe` / `dating_beach` / `dating_city`	Ask which vibe
"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` or `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`	White bg default
"visa photo"	`id_photo_blue`	Blue bg
"photo series", "set of photos"	Use `generate_series()`	Assemble custom list from styles
"highest quality", "best quality"	Any style + `model="gpt"`
Custom scene not in presets	Use `scene=` or `prompt=`

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

用户表述	风格键值	备注
"专业照片"、"证件照"、"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=`

11. Provided scripts

11. 提供的脚本

File	Purpose
`generate_portrait.py`	Core script: submit → poll → download. Handles local files (base64) and URLs, all styles, custom scenes, three models (nano2/nanopro/gpt).
`exports.py`	Re-exports `generate_portrait` , `generate_series` , `STYLE_PROMPTS` for programmatic use by other skills.
`_cost_track.py`	Cost tracking helper — records per-call costs via sc-proxy headers.

文件	用途
`generate_portrait.py`	核心脚本：提交→轮询→下载。支持本地文件（base64）和URL、所有风格、自定义场景、三种模型（nano2/nanopro/gpt）。
`exports.py`	重新导出 `generate_portrait` 、 `generate_series` 、 `STYLE_PROMPTS` ，供其他技能以编程方式调用。
`_cost_track.py`	成本跟踪辅助工具——通过sc-proxy头记录每次调用的成本。

12. Local testing

12. 本地测试

Set

FAL_KEY

env var to call fal.ai directly (bypasses sc-proxy):

bash

undefined

设置

FAL_KEY

环境变量，直接调用fal.ai（绕过sc-proxy）：

bash

undefined

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]

参数：<image_path_or_url> [style] [count] [model]

---

---

13. Troubleshooting

13. 故障排除

Problem	Fix
`File not found: ...`	Check the workspace path; the file must exist
`Unsupported image format`	Use `.jpg` , `.jpeg` , `.png` , `.webp` , or `.bmp`
`Image too large`	Resize to under 10 MB before uploading
`face_image_url must be a public HTTP(S) URL`	Use `image_path` for local files, or provide a valid `https://` URL
`HTTP 402 insufficient_credits`	Top up balance; cost is pre-charged on submit
`HTTP 403 endpoint_not_allowed`	sc-proxy only allows approved fal endpoints; contact admin
Generation `FAILED` upstream	Simplify prompt, ensure face photo is clear and well-lit, retry
Job stuck `IN_PROGRESS` >10 min	Save `request_id` , retry later
Poor face consistency	Use a clear, front-facing photo with good lighting; avoid group photos
`gpt` model too slow	Switch to `nanopro` (default) for faster results

问题	解决方法
`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. Infrastructure (reference)

14. 基础设施参考

Caller →
```
sc-proxy
```
→
```
queue.fal.run/{model}
```
→ fal model providers
All requests must include
```
Authorization: Key fake-falai-key-12345
```
(proxy injects the real
```
FAL_KEY
```
)
Pre-charge happens at submit. Poll/result calls are free.
Local files are base64-encoded as data URIs — no separate upload step needed.
Final images live at
```
https://*.fal.media/...
```
— public CDN, no auth needed for download.
Cost tracking via
```
_cost_track.py
```
— records
```
X-Credits-Used
```
from sc-proxy response headers.

调用流程：调用方 →
```
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
```
。

Model endpoints

模型端点

Model	Edit (with ref image)	Generate (text only)
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`

模型	编辑模式（带参考图像）	生成模式（仅文本）
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`