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

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

DON'T: Common Mistakes

Style Keywords That Work

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

Font Specification

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

DO/DON'T for Text

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.

Mask Best Practices

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

Use Case Guidelines

Common Artifacts & Fixes

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

Tier Selection Guide

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

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

Integration

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