Imported from Rodscaloppe/360spazio (.claude/skills/image-3d/SKILL.md). Install upstream with npx skills add Rodscaloppe/360spazio --skill image-3d. Copyright stays with the author.

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)

⚠️ Execution context — read this first. The code blocks below are Python, not shell commands. Starchild's bash tool runs /bin/bash -c, which cannot parse exec(open(...)) — pasting them directly into a bash command will fail with syntax error near unexpected token 'open'. Also, exec(open(...)) inside python3 -c fails with NameError: __file__ because the script uses __file__ for path resolution.

Use python3 - <<'EOF' with from exports import when calling via the bash tool:

python3 - <<'EOF'
import sys
sys.path.insert(0, "skills/image-3d")
from exports import generate_3d
result = generate_3d(
    prompt="a cute robot assistant with big eyes and antenna",
    category="character",
    style="chibi",
)
print(result)
EOF

The heredoc (<<'EOF') preserves all quotes and newlines — no escaping needed.

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)

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

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:

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

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

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

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

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

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

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

Interior prompt tips:

• Describe the room type (living room, bedroom, kitchen, bathroom, office)
• Mention key furniture and materials
• Specify lighting (natural daylight, warm evening, dramatic)
• Specify color palette if important
• Example: "modern Scandinavian living room with large windows, light wood floors, gray sofa, indoor plants"

L: Architecture (category="architecture")

Architecture prompt tips:

• Describe building type (house, office, tower, museum, school)
• Mention materials (concrete, glass, steel, wood, stone, brick)
• Specify environment (urban, suburban, hillside, waterfront)
• Mention time of day for lighting (golden hour, midday, dusk, night)
• Example: "modern three-story house with flat roof, large glass windows, surrounded by garden, golden hour"

N: 3D Scene (category="scene")

N: Game Asset (category="game_asset")

6. 3D Rendering keyword guide

When crafting custom prompts, use these keywords to control the 3D look:

Materials

Lighting

Camera / Composition

Render Engine Style

7. Model selection guide

Recommendations by category:

• Characters → nanopro for drafts, gpt for final character sheets
• Products → gpt for photorealistic renders, nanopro for quick concepts
• Dioramas → nanopro handles isometric well; gpt for detailed miniatures
• Icons → nanopro is sufficient for most icons
• Text → gpt for better text rendering (still imperfect)
• Interior/Architecture → gpt for photorealistic archviz, nanopro for concepts
• Scenes → gpt for cinematic quality, nanopro for quick mood boards

8. Aspect ratio guide

9. Intent recognition guide

Map user requests to the right category + style:

10. Error handling

11. Advanced examples

3D character sheet (multiple angles)

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="a steampunk inventor character with goggles, leather apron, and mechanical arm, character sheet showing front and side views",
    category="character",
    style="realistic",
    model="gpt",
    aspect_ratio="16:9",
)

Isometric city block

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="a bustling Tokyo street corner with ramen shop, vending machines, and cherry blossom trees, tiny people walking",
    category="diorama",
    style="isometric",
)

Architectural night render

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="a modern art museum with curved glass facade, reflecting pool in front, dramatic uplighting",
    category="architecture",
    style="night",
    model="gpt",
)

Interior design — modern living room

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="spacious living room with floor-to-ceiling windows overlooking city skyline, minimalist furniture, warm wood accents, indoor plants",
    category="interior",
    style="modern",
    model="gpt",
)

Reference image → 3D style

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="transform into a 3D Pixar-style character with exaggerated features",
    reference_path="uploads/photo.jpg",
    category="character",
    style="cartoon",
)

3D game weapon

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="legendary fire sword with glowing runes, ember particles, dark background",
    category="game_asset",
    style="weapon",
)

3D neon text

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="the word 'CYBER' in neon pink and blue letters, wet street reflection",
    category="text",
    style="neon",
)

Multiple images for comparison

exec(open('skills/image-3d/generate_3d.py').read())
result = generate_3d(
    prompt="a cozy coffee shop interior with exposed brick and warm lighting",
    category="interior",
    style="cozy",
    count=3,
    model="nanopro",
)
# Generates 3 variations for the user to choose from