photo-alchemy

Transform any photo into surrealist AI art via a two-step pipeline:

1. Claude writes a surrealist story + image prompt about your photo
2. Gemini generates a brand-new image from that description in a random visual style

Built by Harold Martin. Installable via uvx — no setup required beyond API keys.

Prerequisites

• Python 3.14+
• Anthropic API key (ANTHROPIC_API_KEY)
• Google Gemini API key (GEMINI_API_KEY)

Installation

One-off (no install)

uvx imagemine path/to/photo.jpg

Permanent install

curl -LsSf uvx.sh/imagemine/install.sh | sh

API Key Setup

Keys are resolved in order: SQLite DB → env vars → interactive prompt (saved to DB on first entry).

# Via environment
export ANTHROPIC_API_KEY=***
export GEMINI_API_KEY=***

# Or via interactive config wizard (saves to ~/.imagemine.db)
imagemine --config

Basic Usage

# Transform a single photo
imagemine photo.jpg

# Pick a random photo from a macOS Photos album
imagemine --input-album "Camera Roll"

# Save output to a specific directory
imagemine photo.jpg --output-dir ~/Desktop/output

# Use a specific visual style instead of random
imagemine photo.jpg --style "Ukiyo-e woodblock print, bold outlines, flat color"

# Tune creativity (default 1.0 for both)
imagemine photo.jpg --desc-temp 1.5 --img-temp 0.8

# Pick style interactively from a numbered table
imagemine photo.jpg --choose-style

# Blend multiple styles (enter comma-separated numbers)
imagemine photo.jpg --choose-style  # then enter: 1,5,12

# JSON output (for scripting)
imagemine photo.jpg --json

# Show recent run history with timing sparklines
imagemine --history

Visual Styles

35+ built-in styles including: Watercolor, 8-Bit Pixel Art, Ukiyo-e Woodblock, Neon Noir, Tarot Card, Vaporwave, Glitch Art, Renaissance Painting, and more.

imagemine --list-styles          # show all styles with usage count
imagemine --add-style            # add a custom style interactively
imagemine --remove-style         # remove styles interactively

Apple Photos Integration

imagemine reads face-detection names from Photos albums and uses them in prompts. Use character mappings to rename people before they reach the AI (e.g. "John" → "Captain America").

# Pick input from album, save generated image back to another album
imagemine --input-album "Camera Roll" --destination-album "AI Art"

# Manage character name mappings
imagemine --add-character-mapping
imagemine --list-character-mappings
imagemine --remove-character-mapping

Apple TV Screensaver (killer feature)

Run photo-alchemy on a schedule to continuously generate new art into a shared Photos album, then set that album as your Apple TV screensaver for a living, ever-changing art display.

Setup

1. Create two macOS Photos albums: one for source photos, one for output (make output a Shared Album so Apple TV can see it)
2. Configure albums:

imagemine --config
# Set INPUT_ALBUM and DESTINATION_ALBUM

3. Schedule via launchd (runs every N minutes):

imagemine --launchd 30
# Writes ~/Library/LaunchAgents/imagemine.plist and prints the launchctl command
launchctl load ~/Library/LaunchAgents/imagemine.plist

4. On Apple TV: Photos app → Shared Albums → select your output album → Set as Screen Saver

Apple TV Pitfalls

• Output album must be a Shared Album for Apple TV to see it
• New images appear in the screensaver automatically once added to the shared album
• Use --config-path if you want a non-default DB location with launchd

Configuration Reference

Pipeline Steps (what happens under the hood)

1. Resize input to max 1024px (preserving aspect ratio), save to disk
2. Send resized image to Claude via Files API → generates surrealist story + image prompt
3. Pick a random visual style from the style library (or use --style)
4. Pass story + style + resized image to Gemini → generates the new image
5. Save run metadata to ~/.imagemine.db (SQLite)
6. Optionally import generated image into a macOS Photos album

Run History & Database

Every run is recorded in ~/.imagemine.db with input path, generated story, style used, model names, per-step timing (ms), and output path.

imagemine --history              # show recent runs with timing sparklines
imagemine --config-path ~/custom.db  # use a different DB location

Notes

• A new Claude description is generated on every run — no caching of stories
• --fresh picks from least-used styles (good for variety over time)
• --session-svg saves a styled SVG of the terminal session alongside the output image
• macOS only for Photos/launchd features; core image generation works on any platform