# Image Generation Pitfalls

Real session learnings from batch article + image generation on moreminimore.com.

## The 60-Image Problem (Session: June 30, 2026)

14 articles needed 1 featured + ~3 inline images each = ~56 images total.
- **46 images saved to disk** → 14 featured + 32 inline attachments
- **~20 images lost** → generated successfully by FAL.ai but subagents timed out before saving URLs

## Root Cause

### 1. Subagent timeout on image_generate

Each `image_generate` call takes 15-30 seconds. A subagent trying to generate 3+ images hits the 600s timeout limit.

**Symptoms:**
- Subagent returns with partial results: "I generated 2/3 images but the subagent timed out"
- Some URLs are returned in the subagent's summary but not downloaded
- No way to replay the lost URLs — FAL.ai doesn't keep a history

**Fix:** Generate ALL images from the main agent, never delegate. Each call is a single tool invocation; batch by running up to 3-4 sequential calls per turn.

### 1b. Lost URLs CAN be recovered via FAL API history (CRITICAL)

If a subagent times out after calling `image_generate`, the returned image URLs **can be recovered** — FAL.ai exposes a REST endpoint for request history with image URLs. Here's how:

**Recovery technique (proven in session June 30–31, 2026 — 62 URLs recovered):**

```bash
# 1. List ALL requests by endpoint (latest first):
curl --request GET \
  --url 'https://api.fal.ai/v1/models/requests/by-endpoint?limit=100&sort_by=ended_at' \
  --header 'Authorization: Key <FAL_KEY>'

# 2. Get detailed info INCLUDING image URLs (CRITICAL: expand=payloads):
curl --request GET \
  --url 'https://api.fal.ai/v1/models/requests/by-endpoint?limit=100&sort_by=ended_at&expand=payloads' \
  --header 'Authorization: Key <FAL_KEY>'
```

The `expand=payloads` parameter is critical — without it, the response only contains metadata (request_id, model_id, status, timestamps, token count). With `expand=payloads`, each request includes `request.payload.json_output` which contains output fields including `images[].url`.

**Download workflow after recovery:**
```bash
curl -sL "<image_url>" -o attachments/<name>.png
file attachments/<name>.png    # verify it's a real image
ls -la attachments/<name>.png  # verify non-empty
```

Full example from a real recovery session — see `moreminimore-orchestrator/references/fal-api-recovery.md`.

**When NOT to use this:**
- If the FAL key has changed since the images were generated (history is per-key)
- If the requests are older than FAL's retention window (unknown; 30+ days confirmed working)

**Net result proven in real session:** 62 previously-generated-but-lost image URLs recovered and downloaded from FAL history, avoiding re-generation at ~62 FAL.ai credits.

### 2. Placeholder vs real image mismatch

Initial articles had `<!-- PLACEHOLDER: image — description -->` comments.
These were written by subagents that don't have access to image generation.

**Fix:** Every brief must specify exact image filenames. Every article.md must reference real paths. After all images are saved, grep for `PLACEHOLDER` to catch any missed replacements.

### 3. FAL.ai balance exhaustion (intermittent)

Balance runs out mid-session after ~30-40 images. Subsequent calls return:
```
User is locked. Reason: Exhausted balance. Top up your balance at fal.ai/dashboard/billing.
```

**Detection:** The error is `FalClientHTTPError` with `Exhausted balance`. This is NOT a transient failure — retrying won't help. Stop immediately and tell the user.

**Recovery:** After top-up, resume from where you left off. Don't regenerate already-saved images. Use `find . -name "*.png"` to enumerate existing images per article, then only generate missing ones.

### 4. Inline images for batch mode — separate pass

Batch mode is optimized for speed. The skill says "featured images only" for batch, but:
- User will likely want inline images later
- When they ask, it's a separate pass (same process, different priority)
- Each inline image pass costs 3× article count in FAL.ai credits

**Warn the user before starting an inline-image pass on a batch:** "This will generate ~42 images and consume significant FAL.ai credits. Are you sure?"

## Verification Checklist

After any image generation session, run this:

```bash
cd ~/vault/60_Articles

# 1. Count all images
find . -name "*.png" | wc -l

# 2. Find any remaining placeholders
grep -rn "PLACEHOLDER\|TODO_IMAGE\|<!-- IMAGE" . --include="*.md" | grep -v "brief.md"

# 3. Count per article
for dir in */; do
  featured=$(ls "$dir/images/" 2>/dev/null | wc -l)
  attach=$(ls "$dir/attachments/" 2>/dev/null | wc -l)
  echo "$dir → featured: $featured | inline: $attach"
done
```

## Cost Reference

- FAL Nano Banana Pro (Gemini 3 Pro Image): ~1 credit per image
- 14 articles batch: ~14 credits (featured only)
- 14 articles + inline: ~56 credits
- 14 articles + all replacements: ~80+ credits (if regenerating replacements)