image-gen
Backend-agnostic image generation: single images, series with anchor-chain consistency, batch pipelines. Two backends: Gemini (API) and Nano Banana (local scripts with post-processing).
Deep References
| Signal | Load | Content |
|---|---|---|
| Gemini backend selected | references/backends/gemini.md | Models, env vars, flag table, examples, error codes |
| Nano Banana needed (post-processing, series, JSON batch, style-match) | references/backends/nano-banana.md | Subcommands, flags, aspect ratios, prompt patterns by asset type |
Phase 1: Detect Backend
bashpython3 skills/content/image-gen/scripts/detect-backend.py
gemini-- loadreferences/backends/gemini.mdask-- no key found; ask the user to setGEMINI_API_KEY
Gate: backend confirmed.
Phase 2: Write Prompt Files
Write all prompts to disk before any API call. Prompt files are the generation record and anchor-chain input for series.
File naming: single prompts/YYYY-MM-DD-{slug}.md, series prompts/{series-name}-01.md through -NN.md.
markdown--- model: gemini-3-pro-image-preview aspect-ratio: 1:1 flags: [] --- Full prompt text. Be explicit about subject, style, background, constraints.
bashmkdir -p prompts
For series: write ALL prompt files before calling any generation script.
Gate: all prompt files written and reviewed.
Phase 3: Select Script
| Use case | Script | Subcommand |
|---|---|---|
| Single image, Gemini | scripts/generate_image.py | --prompt |
| Batch from text file, Gemini | scripts/generate_image.py | --batch |
| Single with post-processing | scripts/nano-banana-generate.py | generate |
| Style match from reference | scripts/nano-banana-generate.py | with-reference |
| Batch from JSON manifest | scripts/nano-banana-generate.py | batch |
| Series (anchor chain) | scripts/nano-banana-generate.py | generate then with-reference |
| Post-processing only | scripts/nano-banana-process.py | crop / remove-bg / pipeline |
Model selection:
| Scenario | Model |
|---|---|
| Draft, testing, batch, cost-sensitive | gemini-2.5-flash-image (2-5s) |
| Final asset, character art, typography | gemini-3-pro-image-preview (~30s) |
Aspect ratio by use case:
| Asset type | Ratio |
|---|---|
| Sprites, characters, icons | 1:1 |
| Card art, landscape | 16:9 |
| Vertical maps, portrait bg | 9:16 |
| Portrait cards | 3:4 |
| Wide banners | 21:9 |
Generate at the target ratio. Generating 1:1 and cropping to 16:9 loses 56% of pixels.
Gate: script and subcommand identified.
Phase 4: Generate
Use absolute paths for output files. Show full script output.
Anchor-Chain Algorithm (Series)
Character drift occurs when images are generated independently. Prevent it by passing the previous output as --reference:
image-01.png (no ref) -> image-02.png (ref=01) -> image-03.png (ref=02) -> ...
- Generate image 1 with no reference.
- Use output of image 1 as
--referencefor image 2. - Continue: each image N references image N-1.
Save originals with --save-original for any batch or expensive generation. Re-processing a saved original is free; re-generating costs quota and may break the chain.
Gate: script exits 0.
Phase 5: Verify and Report
Read the generated image to verify:
- Subject matches prompt
- No unwanted watermarks or artifacts
- Aspect ratio and framing correct
- No excessive padding or dark borders
If inspection fails: regenerate with adjusted prompt. Report the issue before retrying.
Report: output file path (absolute), dimensions, model, post-processing applied, verification result. Report only what was requested.
Error Handling
| Error | Cause | Resolution |
|---|---|---|
GEMINI_API_KEY not set | Missing env var | export GEMINI_API_KEY=your_key |
No image in response | Safety filter or text-only response | Adjust prompt; remove policy-adjacent content |
Missing dependency: google-genai | Package absent | pip install google-genai pillow |
Rate limit exceeded (429) | Too many requests | Increase --delay; script retries automatically |
Content policy violation (400) | Restricted content | Rephrase using neutral language |
| Model not found | Wrong model string | Use exact strings: gemini-2.5-flash-image or gemini-3-pro-image-preview |
