image-portrait

What this skill does

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

---

## 1. Quick start — single portrait (most common)

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

## 2. Quick start — public URL

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

```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` or `face_image_url` is provided, the script uses the text-to-image endpoint (no `/edit` suffix).

### 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**:

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

| 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`).

---

## 5. Style presets

### A: Identity-consistent character styles

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

### B: Personal showcase / dating / social

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

### D: Themed / scene portraits

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

### O: Digital avatar

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

### T: Children & family

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

### U: ID / passport photos

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

---

## 6. Model selection guide

| 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:**
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.

```python
# 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

```python
# 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 enginee