| name | gemini-image-executor |
| type | executor |
| description | Generate production-quality raster PNG graphics via Gemini native image generation. For atmospheric visuals, social media, event posters, and marketing hero images. |
| version | 0.1.0 |
Gemini Image Executor Skill
Generate production-quality raster PNG assets via Google's Gemini image generation API. Claude orchestrates — constructing the prompt, mapping aspect ratios, gating on text fidelity — while Gemini renders the image.
Use When
- Planner spec has
Recommended executor: gemini-image-executor
- Task needs atmospheric visual quality: organic gradients, flowing shapes, visual depth
- Output is a social media graphic, event poster, hero image, or marketing visual
- Platform-ready PNG is the desired deliverable
Do Not Use When
- Task requires data accuracy, proportional integrity, or source citations → use
infographic-executor
- Task requires precision, verifiable values, or editability → use
graphic-design-executor
- Task requires accessible text (screen readers) → use
graphic-design-executor
- Task requires vector scalability → use
graphic-design-executor
- No
GOOGLE_API_KEY environment variable is available
Paired With
graphic-design-planner: Upstream — produces the spec with ## Executor Routinggraphic-design-critic: Downstream — reviews the output (format-aware)
Execution Protocol
Phase 1: Input Validation & API Readiness
- Detect input: planner spec (has
## Executor Routing) or direct request
- Extract parameters: asset type, brand tokens, content inventory, visual direction, format/dimensions
- API Gate: Check for
GOOGLE_API_KEY:
[ -n "$GOOGLE_API_KEY" ] && echo "API key present" || echo "MISSING"
If missing: STOP. Surface: "GOOGLE_API_KEY not found. Set it or fall back to graphic-design-executor (SVG-in-HTML). The output format changes from atmospheric raster to precision vector."
- Verify API connectivity:
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GOOGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gemini-3.1-flash-image-preview","input":"test","response_format":{"type":"image","image_size":"512"}}' \
| jq '.error // "OK"'
Phase 2: Prompt Construction
Convert the planner spec into a narrative prompt. Gemini requires descriptive prose, not structured specs.
Rules:
- All text content in quotes. Every string that must appear in the image gets double-quoted in the prompt. This is the single most important text fidelity measure.
- Typography as prose: "large, bold, white sans-serif headline" not "font-size: 48px; font-weight: bold"
- Colors as descriptions with hex: "deep navy background (#0F172A)" not "background-color: var(--color-bg)"
- Layout as spatial narrative: "the headline dominates the upper third, with three feature columns evenly spaced below"
- Visual direction as atmosphere: describe the feeling, lighting, depth — use photographic/cinematic terminology
- No keyword lists. Full sentences describing what the viewer should see.
Phase 3: Aspect Ratio & Resolution Mapping
Map the spec's format requirements to Gemini API parameters:
| Format | API aspect_ratio | API image_size |
|---|
| Instagram post (1080×1080) | 1:1 | 2K |
| Instagram story (1080×1920) | 9:16 | 2K |
| LinkedIn post (1200×628) | 16:9 | 2K |
| Twitter/X post (1600×900) | 16:9 | 2K |
| Facebook OG (1200×630) | 16:9 | 2K |
| Event poster portrait | 9:16 or 3:4 | 2K |
| Hero banner (1920×1080) | 16:9 | 2K |
| Presentation slide | 16:9 | 2K |
| Square card | 1:1 | 2K |
| Tall infographic | 2:3 | 2K |
Supported aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
If the spec requests a non-standard ratio, pick the closest supported ratio and document the deviation.
Phase 4: API Invocation
Single call to the Interactions API:
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GOOGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"input": "<NARRATIVE_PROMPT>",
"response_format": {
"type": "image",
"aspect_ratio": "<RATIO>",
"image_size": "2K"
}
}' > /tmp/gemini-response.json
Extract and save:
jq -r '.outputs[] | select(.type == "image") | .data' /tmp/gemini-response.json \
| base64 -d > <OUTPUT_PATH>/output.png
Record metadata:
jq '{model: .model, usage: .usage}' /tmp/gemini-response.json
Error handling:
- HTTP errors or
.error in response → surface exact error, offer retry or fallback
- Empty
.outputs → check for safety/recitation filter, log and report
- For multi-asset campaigns, make one API call per asset (each aspect ratio is a separate generation)
Phase 5: Text Fidelity Risk Assessment
Gemini has a ~20% text garbling rate on text-heavy designs. After generation:
- List every text string from the planner spec's content inventory
- Rate risk level:
- LOW: 3 or fewer distinct text strings
- MEDIUM: 4–5 distinct text strings
- HIGH: 6+ distinct text strings
- Flag HIGH risk outputs for mandatory visual verification before critic handoff
- Note: text accuracy cannot be machine-verified in raster output — visual inspection is required
Phase 6: Quality Self-Check & Critic Handoff
- Were all spec hex colors included in the narrative prompt?
- Was the style vocabulary translated into atmospheric description?
- Does the output match the requested aspect ratio?
- Write Deviation Log for any spec requirements that could not be expressed in narrative form
- Propose DESIGN_MEMORY.md entry if applicable
- Provide critic handoff command
Hard Gates
- No generation without
GOOGLE_API_KEY present — never silently fall back
- No generation without narrative prompt containing all text content in quotes
- No generation without aspect ratio mapping from the spec's format requirements
- No delivery without Text Fidelity Risk assessment
- No delivery without Reference Inventory and Source/Provenance Notes
- No public reference copying
Required Output Contract
Use these top-level headings exactly:
## Parameter Extraction## Prompt Construction## API Response## Generated Files## Text Fidelity Risk## Verification Notes## Design Memory Notes## Deviation Log## Execution Summary
