phantom-canvas

Turn the free Gemini web interface into a programmable CLI tool and HTTP API for image and video generation. No API keys, no billing — just your Google account.

Two ways to use it:

• CLI — phantom-canvas generate "prompt" -o output.png for scripts and AI agents
• HTTP API — phantom-canvas serve for applications and pipelines

A persistent Chrome browser runs in the background via CDP, automating Gemini's web UI. Phantom Canvas handles the rest — typing, uploading reference images, waiting for generation, and downloading the full-resolution result (1024px).

Already paying for Gemini Advanced? Turn your subscription into your own private image generation API.

Built with Node.js + Playwright + Hono + Chrome CDP.

Quick start

# Install
bun add -g phantom-canvas    # or: npm install -g phantom-canvas

# Generate (Chrome auto-launches, no setup needed)
phantom-canvas generate "pixel art knight, isometric, green #00FF00 bg"

# Start HTTP API server
phantom-canvas serve

# First time: login to Google in the Chrome window that opens
# After that, everything is automatic — your login persists

Commands

Generate options

API

POST /generate

Submit an image or video generation task. Returns immediately with a task ID.

# Image
curl -X POST localhost:8420/generate \
  -d '{"prompt": "pixel art knight, isometric view, green #00FF00 bg"}'

# With reference image (img2img)
curl -X POST localhost:8420/generate \
  -d '{
    "prompt": "same character from 4 angles in a 2x2 grid",
    "reference_images": ["/path/to/sprite.png"]
  }'

# Video
curl -X POST localhost:8420/generate \
  -d '{"prompt": "knight walking in place, looping", "type": "video", "timeout_secs": 300}'

Parameters:

GET /task/:id

Check task status.

{
  "task_id": "abc123",
  "status": "completed",
  "images": [{"index": 0, "url": "/task/abc123/image/0", "type": "image"}],
  "elapsed_secs": 45.3
}

GET /task/:id/image/:index

Raw file download (image or video).

GET /health

Server status.

POST /session/refresh

Reload Gemini page.

POST /debug/eval

Execute JS in the browser (debugging).

GET /debug/screenshot

Capture browser page as PNG.

How it works

1. Chrome launches via CDP with a persistent profile (~/.phantom-canvas/chrome-profile)
2. Navigates to Gemini and reuses your logged-in session
3. Types your prompt into Gemini's input area
4. Waits for generation by monitoring for new <img> elements
5. Extracts full-res image via canvas.drawImage() → toDataURL() (bypasses blob URL restrictions)
6. Returns the result as a local PNG file

Game asset pipeline

Built for AI game asset generation — creating pixel art sprites without paid API keys.

# Anchor sprite
curl -X POST localhost:8420/generate \
  -d '{"prompt": "SE-facing isometric pixel art knight, FFT style, #00FF00 bg"}'

# Cardinal facings (with reference)
curl -X POST localhost:8420/generate \
  -d '{"prompt": "2x2 grid: N, E, S, SE views of same character", "reference_images": ["anchor.png"]}'

# Walk animation
curl -X POST localhost:8420/generate \
  -d '{"prompt": "looping walk cycle", "reference_images": ["anchor.png"], "type": "video"}'

Tip: Use #00FF00 green background instead of "transparent" — Gemini interprets transparency as checkerboard pattern. Green screen is easy to chroma-key in post-processing.

Limitations

• Gemini has daily generation quotas (especially video)
• One request at a time (serial queue)
• Session cookies expire periodically — re-login with phantom-canvas chrome
• Image resolution determined by Gemini (typically 1024px)
• Headless mode works but generation may be slower

License

MIT