| name | image-gen |
| description | Generate and edit images for ArtStroy articles using the Gemini image generation API. Use when creating cover images, OG images, inline illustrations, or editing existing images for article assets. |
Image Generation for ArtStroy
Generate or edit images using the Gemini image generation API (GEMINI_API_KEY from .paperclip.yaml inputs.env).
Script Usage
The generation script is invoked via uv:
Generate a new image:
uv run scripts/generate_image.py \
--prompt "your image description" \
--filename "output.png" \
--resolution 1K
Edit an existing image:
uv run scripts/generate_image.py \
--prompt "edit instructions" \
--filename "output.png" \
-i "/path/to/input.png" \
--resolution 2K
Multi-image composition (up to 14 source images):
uv run scripts/generate_image.py \
--prompt "combine these into one scene" \
--filename "output.png" \
-i img1.png -i img2.png -i img3.png
With a specific aspect ratio:
uv run scripts/generate_image.py \
--prompt "portrait photo" \
--filename "output.png" \
--aspect-ratio 9:16
Parameters
Resolutions: 1K (default), 2K, 4K
Aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Omit --aspect-ratio to let the model choose freely. Use it when exact dimensions are required (avatars, covers, OG images).
ArtStroy-Specific Output Specs
| Asset | Format | Dimensions | Aspect Ratio | Notes |
|---|
| Cover image | AVIF | 1920×1080 | 16:9 | No text; dark aesthetic preferred |
| OG image | PNG | 1200×630 | ~1.91:1 | Must include article title text |
| Inline illustration | PNG | up to 2K | free | Match article's visual theme |
Generate at the correct aspect ratio, then convert/resize as needed:
- Cover: generate PNG at 16:9 → convert to AVIF and save to
./imgs/cover.avif
- OG: generate PNG at 16:9 close to 1.91:1 → resize to exactly 1200×630 → save to
./imgs/og.png
File Naming
Use timestamps in filenames for intermediate outputs:
2026-05-25-14-30-00-cover-draft.png
Final outputs must match the contract paths exactly:
src/content/articles/{slug}/imgs/cover.avif
src/content/articles/{slug}/imgs/og.png
API Key
Requires GEMINI_API_KEY env var. This is declared in .paperclip.yaml inputs.env and injected by the Paperclip runtime at execution — do not hardcode or print it.
Output
The script prints a MEDIA: line pointing to the saved file. Report the path from that line. Do not read the image back into the conversation — just report where it was saved.
Quality Notes
- Do not produce placeholder images. If generation fails, report the failure with the error — do not commit a blank or generic fallback.
- For covers: dark backgrounds, minimal text (ideally none), strong visual metaphor for the article topic.
- For OG images: the article title must be legible at thumbnail size. Bold, high-contrast type.
- Review generated images visually before committing to
./imgs/. One retry is reasonable; more than two retries should escalate to human review.
