AI Image Generation

Tap integrates with Google's Gemini API to generate images directly from text prompts. Create custom visuals for your presentations without leaving your workflow.

Setup

Set your Gemini API key as an environment variable:

export GEMINI_API_KEY=your-api-key-here

Get an API key from Google AI Studio.

Environment Files

Add the key to your shell profile (.bashrc, .zshrc) or a project .env file for persistence.

Using the Image Generator

Opening the Generator

While running tap dev, press i to open the image generator.

Workflow

1. Select a slide - Choose which slide to add the image to using arrow keys
2. Choose action - Add a new image or regenerate an existing one
3. Enter prompt - Describe the image you want (up to 2000 characters)
4. Wait for generation - The image generates in a few seconds
5. Done - The image is saved and inserted into your markdown

Keyboard Shortcuts

Key	Action
i	Open image generator
↑ / k	Navigate up
↓ / j	Navigate down
Enter	Select / Submit prompt
Esc	Cancel / Go back
r	Retry on error

From the Command Line

tap image generate and tap image regenerate are the i key's generator as commands, for scripts and CI. They write the same files the i key does.

tap image generate --slide 3 --prompt "a lighthouse at dusk, flat vector"

Generates a new image with Gemini and adds it at the end of slide 3.

tap image regenerate --slide 3 --image images/generated-1a2b3c4d.png

Makes the AI image at that path again, in place, reusing its own prompt. See CLI Commands for the full flag reference.

Markdown Format

Generated images are stored with their prompt as metadata:

<!-- ai-prompt: a minimalist illustration of a rocket launching -->
![](images/generated-a1b2c3d4.png)

The HTML comment preserves the prompt for regeneration. The image file is saved to an images/ directory alongside your markdown file.

Regenerating Images

To regenerate an existing AI image:

1. Press i to open the generator
2. Select the slide containing the image
3. Choose the image to regenerate from the list
4. Edit the prompt if desired, or submit to regenerate with the same prompt
5. The new image replaces the old one (old file is deleted)

Or run tap image regenerate --slide N --image <path> from the command line.

Writing Effective Prompts

Be Specific

Vague prompts produce unpredictable results. Include:

• Subject matter
• Style (illustration, photo, diagram)
• Color scheme
• Composition

Less Effective	More Effective
"a database"	"a minimalist isometric illustration of database servers in blue and white"
"teamwork"	"four diverse professionals collaborating around a whiteboard, modern office, warm lighting"
"security"	"a shield icon with a lock, flat design, corporate blue gradient background"

Matching the Theme

Every built-in theme declares its own illustration style: medium, line weight, shape language, texture, how the palette should be used, mood, and what to avoid. tap theme show <slug> --prompt prints that as a ready-to-paste style brief, with the palette as hex values:

tap theme show blueprint --prompt

Illustration style for the "Blueprint" slide theme: flat vector technical
drawing, white-ink-on-blue blueprint diagram. Use only this palette:
background #0f3a75, foreground #f5f9ff, accent #ffd447, muted #c0d6f3,
surface #174688. Palette use: deep blue background dominant, white/near-white
line work, one yellow accent used only for a callout or highlight. Line: 3 to
4px even strokes, drafting-table precision, dimension lines with tick marks.
Shapes: rectangles, circles, and annotated technical diagrams, grid-aligned,
no organic curves. Texture: faint graph-paper grid in the background. Mood:
precise, engineered, under-construction. Avoid: gradients, photos, rounded
corners, color outside blue/white/yellow, decorative flourish. Type feel, as
a style hint only: Saira Condensed for display, Saira Semi Condensed for
body. No text or lettering in the image unless asked. Canvas 16:9, sitting on
a #0f3a75 background so it blends into the slide.

Put that brief in front of your own subject line:

<the style brief above>

Subject: four app servers behind a load balancer, one of them restarting.

The result sits on the slide instead of fighting it: the palette matches, the background blends, and nothing arrives with a gradient the theme never uses. If you already know the deck, tap theme show slides.md --prompt reads the theme from its frontmatter.

See Theme Tokens for the same values as CSS custom properties.

Keep It Presentation-Ready

Generated images work best when they're:

• Simple and uncluttered
• High contrast for visibility
• Relevant to slide content

File Management

Directory Structure

presentation/
├── slides.md
└── images/
    ├── generated-a1b2c3d4.png
    ├── generated-e5f6g7h8.png
    └── logo.png  (your own images)

Filename Format

Generated images use the format generated-{hash}.{ext} where the hash is derived from the image content. This ensures:

• Unique filenames for different images
• Same content always produces the same filename
• Easy identification of AI-generated vs. manual images

Supported Formats

The API returns images in standard web formats:

• PNG (most common)
• JPEG
• WebP
• GIF

Error Handling

Error	Cause	Solution
Authentication failed	Invalid or missing API key	Check GEMINI_API_KEY is set correctly
Rate limit exceeded	Too many requests	Wait a moment and retry
Content policy	Prompt violated guidelines	Try a different prompt
No image generated	API couldn't produce image	Rephrase your prompt
Network error	Connection issue	Check internet and retry

Press r to retry after an error, or Esc to cancel.

Best Practices

Organize Prompts

For presentations with many AI images, keep a reference of your prompts in a separate file. This makes it easier to maintain visual consistency.

Review Before Presenting

AI-generated images can occasionally contain artifacts or unexpected elements. Always preview your slides before presenting.

Consider Alternatives

AI generation is great for:

• Conceptual illustrations
• Abstract backgrounds
• Quick prototyping

For precise technical diagrams, consider Mermaid diagrams instead.

Quick Reference

Task	How
Generate new image	Press i → Select slide → "Add new image" → Enter prompt
Regenerate image	Press i → Select slide → Choose existing image → Edit/submit prompt
View prompt	Check the <!-- ai-prompt: ... --> comment in markdown
Delete AI image	Remove the comment and image line from markdown, delete file manually

Next Steps

• Learn about Images & Media for sizing and positioning
• Explore Mermaid Diagrams for technical diagrams
• See Layouts for image placement options