image-3d

What this skill does

# image-3d

Use this skill for **all 3D-style image generation requests** on Starchild.

Covers: 3D character design (chibi, realistic, cartoon, fantasy), 3D product renders (floating, exploded, turntable), isometric dioramas & miniature scenes, 3D app icons (iOS, Material, game), 3D text effects (chrome, neon, wood, candy), interior design visualization (modern, luxury, cozy, industrial), architectural rendering (modern, traditional, futuristic, aerial, night), 3D scenes (fantasy, sci-fi, nature, urban), and game asset renders (weapons, environments, props, vehicles).

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

**⚠️ Important distinction — 3D-style images vs 3D model files:**
- **This skill** generates **3D-style 2D images** (PNG/JPG) — rendered pictures that *look* 3D
- This skill does **NOT** produce 3D model files (.glb, .obj, .fbx, .usdz)
- For actual 3D model files, users need dedicated 3D modeling services (Meshy, etc.)

**When to use image-3d vs other image skills:**
- **image-3d** → user wants a 3D-rendered look: 3D characters, isometric scenes, 3D icons, architectural renders, interior design renders, 3D text effects
- **image-create** → user wants general creative images (logos, posters, illustrations, memes) — image-create has a basic `3d` category, but image-3d offers far more granular control
- **image-ecommerce** → user wants product photos for e-commerce listings (white background, lifestyle shots)
- **image-edit** → user wants to edit/transform an existing image
- **image-portrait** → user wants a portrait with face/identity preserved

---

## 1. Quick start — text-to-3D image (most common)

```python
exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="a cute robot assistant with big eyes and antenna",
    category="character",
    style="chibi",
)
# result -> {"success": True, "images": [{"local_path": "output/images/..."}], ...}
```

## 2. Quick start — category + style only (no custom prompt)

```python
exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    category="diorama",
    style="isometric",
)
# Uses the built-in style template as the full prompt
```

## 3. Quick start — reference image → 3D style

```python
exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="transform into a 3D rendered character",
    reference_path="uploads/sketch.jpg",
    category="character",
    style="cartoon",
)
```

### 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
   ![3d-render](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 |
|-----------|----------|---------|-------------|
| `prompt` | yes* | — | Text description of the desired 3D image |
| `reference_path` | no | — | Local file path to a reference image (for 3D stylization) |
| `reference_url` | no | — | Public HTTPS URL of a reference image |
| `category` | no | `"character"` | 3D category preset (see §5) |
| `style` | no | `"default"` | Sub-style within the category (see §5) |
| `model` | no | `"nanopro"` | Model: `"nanopro"` (fast ~25s) or `"gpt"` (best quality ~150s) |
| `count` | no | `1` | Number of images to generate (1–4) |
| `aspect_ratio` | no | auto | Output ratio: `1:1`, `3:4`, `4:3`, `9:16`, `16:9`. Auto-selected by category if not set. |

*A `prompt` is required for text-to-image mode unless a non-default `style` is specified (which provides a built-in template).

**Prompt priority:** `prompt + category/style` (enhanced) > `prompt` only > `category + style` template > `category` default.

**Aspect ratio auto-selection:** When not explicitly set, the script picks the best ratio for the category:
- `3:4` for characters (portrait orientation)
- `1:1` for products, dioramas, icons, game assets (square showcase)
- `16:9` for text, interiors, architecture, scenes (wide cinematic)

---

## 5. Categories and style presets

### N: 3D Character (`category="character"`)

| Style | Key | Best for |
|-------|-----|----------|
| Chibi / Pixar | `chibi` | Cute stylized characters, mascots, avatars |
| Realistic | `realistic` | Game-ready characters, detailed anatomy |
| Cartoon | `cartoon` | Disney/Pixar style, family-friendly |
| Fantasy | `fantasy` | RPG characters, warriors, mages |
| General | `default` | Any 3D character |

**Character prompt tips:**
- Describe pose, outfit, expression, and accessories
- Specify "white background" or "clean background" for character sheets
- For game characters, mention "T-pose" or "action pose"
- Example: `"a female elf ranger with green cloak, holding a bow, forest background"`

### N: 3D Product Render (`category="product"`)

| Style | Key | Best for |
|-------|-----|----------|
| Floating 3/4 angle | `floating` | Hero product shots, marketing |
| Exploded view | `exploded` | Technical illustration, internal structure |
| Turntable / 360° | `turntable` | Multi-angle showcase |
| General | `default` | Any product render |

**Product prompt tips:**
- Describe material (matte, glossy, metallic, wood, glass)
- Specify lighting (studio, dramatic, soft, rim light)
- Mention the product type and key features
- Example: `"wireless earbuds in charging case, matte white, floating angle"`

### N: 3D Diorama / Isometric (`category="diorama"`)

| Style | Key | Best for |
|-------|-----|----------|
| Isometric | `isometric` | Miniature worlds, city blocks, game maps |
| Low-poly | `lowpoly` | Stylized scenes, indie game aesthetic |
| Realistic | `realistic` | Architectural models, detailed miniatures |
| General | `default` | Any diorama scene |

**Diorama prompt tips:**
- Describe the scene contents (buildings, trees, characters, vehicles)
- Mention scale ("miniature", "tiny", "dollhouse")
- Specify mood (warm, cozy, dramatic, whimsical)
- Example: `"a cozy Japanese ramen shop at night, tiny customers inside, warm glow"`

### N: 3D Icon (`category="icon"`)

| Style | Key | Best for |
|-------|-----|----------|
| iOS style | `ios` | Apple App Store icons, glossy glass |
| Material Design | `material` | Google Play icons, flat with depth |
| Game icon | `game` | RPG items, fantasy game UI |
| General | `default` | Any 3D icon |

**Icon prompt tips:**
- Describe the icon subject simply (one main element)
- Specify the shape context ("rounded square", "circular")
- Keep it simple — icons should be recognizable at small sizes
- Example: `"a camera icon with rainbow lens flare"`

### N: 3D Text (`category="text"`)

| Style | Key | Best for |
|-------|-----|----------|
| Chrome / Metallic | `chrome` | Bold titles, movie-style text |
| Neon glow | `neon` | Cyberpunk, nightlife, signs |
| Wood | `wood` | Rustic, craft, natural brands |
| Candy | `candy` | Playful, kids, sweet themes |
| General | `default` | Any 3D text effect |

**Text prompt tips:**
- ⚠️ AI text rendering is unreliable — keep text SHORT (1-3 words max)
- Describe the text content in quotes: `"the word 'HELLO'"`
- Specify material and environment
- Example: `"the word 'GAME OVER' in chrome metallic letters, dark background"`

### L: Interior Design (`category="interior"`)

| Style | Key | Best for |
|-------|-----|----------|
| Modern minimalist | `modern` | Scandinavian, clean lines, natural light |
| Luxury | `luxury` | High-end, marble, gold accents |
| Cozy / Hygge | `cozy` | War