7b5af16f6d
- 9 mm* skills (orchestrator, article, social, publish, analytics) - 6 dependency skills (content-writer, geo-optimizer, etc.) - 3 analytics scripts (GSC, Google Ads, Meta Ads) - Config template + setup guide - SOUL-MM.md persona extension - OrbitOS integration reference
113 lines
4.9 KiB
Markdown
113 lines
4.9 KiB
Markdown
# 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)
|