Image Generation

Generate, edit, and upscale images with standardized quality tiers and embedded best practices.

Quick Start

Need image?
├─ Text/Logo → bun scripts/gen.ts "..." --text [-t tier]
├─ Photo/Art → bun scripts/gen.ts "..." [-t tier]
├─ Edit existing → bun scripts/edit.ts <img> "..." [-t tier]
├─ Upscale → bun scripts/upscale.ts <img> [-t tier]
├─ Vectorize → bun scripts/svg.ts <img> ($0.01/img)
└─ Remove BG → bun scripts/rembg.ts <img> (FREE)

Tier selection:
├─ iterate  → FREE drafts (~96/day via Cloudflare)
├─ default  → Daily driver ($0.008/MP)
├─ premium  → Final assets ($0.03/MP)
└─ max      → Critical work, SOTA ($0.06-0.07/MP)

Entry Points

Script	Purpose
bun scripts/gen.ts	Text → Image
bun scripts/edit.ts	Image + Instruction → Image
bun scripts/upscale.ts	Image → Larger Image
bun scripts/svg.ts	Image → SVG ($0.01/img)
bun scripts/rembg.ts	Remove background (FREE)

---

Prompting Best Practices

CRITICAL: Good prompts are the difference between unusable output and production-ready assets.

The Universal Prompt Structure

[Subject] + [Action/Pose] + [Environment] + [Style/Medium] + [Lighting] + [Camera/Composition]

Example:

"A cybernetic owl perched on a neon sign in a rain-soaked alley. Cinematic lighting with teal and orange highlights. Shot on 35mm film, shallow depth of field, hyper-detailed textures."

DO: Effective Prompting

Technique	Example
Be specific	"middle-aged man with salt-and-pepper hair wearing charcoal turtleneck" NOT "a man"
Describe the result	"person with clear eyes" NOT "remove glasses"
Use camera terms	"Shot on Hasselblad, 85mm lens, f/1.8"
Specify lighting	"golden hour rim lighting with deep shadows"
Include textures	"weathered sandstone", "anodized aluminum", "iridescent silk"

DON'T: Common Mistakes

Mistake	Problem	Fix
Negative phrasing	"no glasses" often adds glasses	Describe what IS there
Vague subjects	AI interprets randomly	Be exhaustively specific
Keyword salad	"4k, trending, masterpiece" is noise	Use descriptive sentences
Short prompts	Under 20 words underperforms	Aim for 40-80 words

Style Keywords That Work

Category	Keywords
Lighting	golden hour, volumetric lighting, Rembrandt lighting, neon rim light, bioluminescent
Camera	35mm anamorphic, macro photography, tilt-shift, fisheye, drone shot
Style	cinematic, photorealistic, concept art, ukiyo-e, baroque, impressionist
Quality	hyper-detailed, sharp focus, 8k resolution, raytraced

---

Text & Logo Generation (--text flag)

Uses Recraft V3 (iterate/default) or Ideogram V3 (premium/max) - specialized for typography.

Text Prompting Rules

CRITICAL: Put text in "Double Quotes" at the START of your prompt.

# Correct - text first, then describe
bun scripts/gen.ts '"QUANTUM" in bold futuristic font, metallic silver, dark space background' --text

# Wrong - text buried in description
bun scripts/gen.ts 'A logo with the word QUANTUM on it' --text

Logo Design Patterns

Style	Prompt Pattern
Minimalist	"BRAND" minimalist vector logo, clean lines, simple geometry, flat design
Vintage	"EST. 1920" vintage badge logo, circular emblem, ribbon banner, ornate border
Negative space	"PEAK" logo where the letter A forms a mountain, negative space design
3D/Modern	"TECHCORP" bold 3D chrome letters, gradient fill, dark background

Font Specification

Use typography terms: modern sans-serif, elegant script, bold blocky, blackletter, neon tubing, retro 70s serif

DO/DON'T for Text

DO	DON'T
"Three cats playing" (exact count)	"cats playing" (random count)
"wooden baseball bat" (specific)	"bat" (ambiguous)
Describe only what you want	"no cake" (will add cake)

---

Image Editing

bun scripts/edit.ts <image> <instruction> [-t TIER] [--mask <mask.png>] [--ref <img>...]

Writing Edit Instructions

Key: Describe the TARGET STATE, not the change.

Bad Instruction	Good Instruction
"change car to blue"	"A sleek blue metallic sports car, reflections of neon lights on wet asphalt"
"add a hat"	"person wearing a vintage red fedora, matching the scene lighting"
"remove background"	Use rembg.ts instead (FREE and better)

Mask Best Practices

Task	Mask Strategy
Object removal	Mask LARGER than object (10-20px margin) for seamless fill
Object addition	Mask exact shape or slightly smaller
Outpainting	Overlap 10-20px INTO original image

Feathering: Apply 12-16px blur to masks. Sharp masks = visible seams.

Multi-Reference Editing (--ref)

Using 2+ reference images auto-selects max tier (flux-2-flex).

# Style transfer: apply reference style to base image
bun scripts/edit.ts base.jpg "in the style of the reference" --ref style.jpg

# Multi-reference blending
bun scripts/edit.ts scene.jpg "forest sofa scene" --ref forest.jpg --ref sofa.jpg

Tip: When blending references, describe their relationship: "A velvet sofa placed in a misty pine forest"

---

Upscaling

bun scripts/upscale.ts <image> [-t TIER] [--scale 2|4]

When to Use 2x vs 4x

Source Quality	Recommendation
High (RAW, clean PNG)	4x safe - AI infers detail accurately
Medium (standard JPEG)	2x preferred - denoise first if possible
Low (compressed, blurry)	2x max - noise gets magnified

Use Case Guidelines

Output	Scale	Notes
Web/UI	2x	Reduces file size, improves perceived sharpness
Print (300 DPI)	4x	Target 300 DPI for print quality
Icons/Logos	2x	Use svg.ts instead for infinite scaling

Common Artifacts & Fixes

Artifact	Cause	Prevention
Haloing (white edges)	Aggressive sharpening	Use iterate/default tier
Plasticky skin	Over-smoothing	Reduce to 2x, use premium tier
Grid patterns	Tile processing	Use higher tier models

Rule of Thumb: If image looks "crunchy" at 100% zoom, don't exceed 2x.

---

Tier Selection Guide

Scenario	Tier	Why
Exploring 10+ variations	iterate	FREE, fast iteration
Daily work, 3-5 variations	default	Best cost/quality balance
Client deliverables	premium	Higher fidelity
Critical assets, multi-ref	max	SOTA quality, advanced features
Text/logos (any)	default	Recraft V3 already excellent
Text/logos (critical)	premium	Ideogram V3 for perfect typography

Cost Optimization

EXPENSIVE WORKFLOW (avoid):
  Generate at max tier → iterate on max → deliver

COST-EFFECTIVE WORKFLOW (recommended):
  Generate at iterate (FREE) → find best concept
  → Regenerate winner at default/premium → deliver

---

Environment

# For FREE iterate generation (Cloudflare)
CLOUDFLARE_ACCOUNT_ID=xxx
CLOUDFLARE_API_TOKEN=xxx

# For paid tiers (Fal.ai)
FAL_API_KEY=xxx

Quota: Cloudflare FREE tier allows ~96 images/day at 1024x1024.

Exit Codes

Code	Meaning	Action
0	Success	Image saved to .ada/data/images/
1	General error	Check error message
2	Config/auth error	Verify API keys in .env
3	Resource limit	Quota exceeded - wait 24h or use paid tier

CRITICAL: Exit code 3 does NOT fall back to paid tier. This prevents accidental charges.

---

Integration

Skill	When to Use Together
ui-animation	Animate generated images for web/mobile
docs-write	Document image assets and parameters used
search	Find prompting resources and style references
code-quality	After modifying skill scripts

References

• references/usage-guide.md - Extended prompting guide, error codes, testing
• README.md - Architecture diagrams, model reference, CLI details
• Fal.ai Docs - Official API documentation

Output

Images saved to .ada/data/images/ with timestamped filenames:

20260118_gen_default_cyberpunk_city.jpg
20260118_svg_default_logo_vector.svg