image-portrait

1. Quick start — single portrait (most common)

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

2. Quick start — public URL

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)

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

1. Use each image's

   local_path

   (e.g.

   output/images/xxx.png

   ) — the script always downloads on success.
2. Tell the user the files are saved to

   output/images/

   and viewable in the workspace file panel.
3. On Web channel, embed inline so the user can preview in chat:
   markdown

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

4. On Telegram / WeChat: send via

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

   or

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

   .

4. Parameters

image_path

face_image_url

style

"professional"

scene

None

prompt

None

model

"nanopro"

"nano2"

"nanopro"

"gpt"

count

1

aspect_ratio

"1:1"

1:1

3:4

4:3

9:16

16:9

• 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

style + scene

style

professional

5. Style presets

A: Identity-consistent character styles

professional

artistic

anime

cyberpunk

oil_painting

watercolor

vintage

casual

B: Personal showcase / dating / social

dating_cafe

dating_beach

dating_city

dating_restaurant

travel_europe

travel_japan

travel_tropical

sports_gym

sports_running

social_media

linkedin

personal_brand

D: Themed / scene portraits

christmas

halloween

graduation

wedding

business_speech

musician

chef

outdoor_adventure

pet_together

reading

night_city

hanfu

O: Digital avatar

avatar_3d

avatar_gaming

avatar_vtuber

T: Children & family

child_portrait

family_photo

U: ID / passport photos

id_photo_white

id_photo_blue

6. Model selection guide

nano2

nanopro

gpt

1. Default: always use

   nanopro

   unless the user explicitly requests otherwise.
2. Use

   nano2

   when: user wants fastest results, is iterating on styles, generating many images, or says "quick", "draft", "fast".
3. Use

   gpt

   when: user says "highest quality", "best quality", "premium", or the scene is very complex with many specific details.

# 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. Custom scene examples

# 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 engineering best practices

prompt

Automatic likeness preservation

avatar_3d

avatar_gaming

avatar_vtuber

The 7-element prompt structure

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

Key principles

1. 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"
2. 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)
3. 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)
4. 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)
5. 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)
6. 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)
7. 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)

Example: building a custom prompt

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

Example: pixel art avatar (from 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. Photo series

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

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

10. Intent recognition guide

professional

linkedin

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

avatar_3d

avatar_gaming

avatar_vtuber

child_portrait

family_photo

id_photo_white

id_photo_blue

generate_series()

model="gpt"

scene=

prompt=

11. Provided scripts

generate_portrait.py

exports.py

generate_portrait

generate_series

STYLE_PROMPTS

_cost_track.py

12. Local testing

FAL_KEY

# 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. Troubleshooting

File not found: ...

Unsupported image format

.jpg

.jpeg

.png

.webp

.bmp

Image too large

face_image_url must be a public HTTP(S) URL

image_path

https://

HTTP 402 insufficient_credits

HTTP 403 endpoint_not_allowed

FAILED

IN_PROGRESS

request_id

gpt

nanopro

14. Infrastructure (reference)

• 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.

Model endpoints

fal-ai/nano-banana-2/edit

fal-ai/nano-banana-2

fal-ai/nano-banana-pro/edit

fal-ai/nano-banana-pro

openai/gpt-image-2/edit

openai/gpt-image-2