moreminimore-service-system/skills/mm-content-writer/references/image-generation-pitfalls.md

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

# 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:

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:

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)