image-gen

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.