Phantom Canvas

CLI + HTTP API for image and video generation through Gemini Web. No API keys — uses Chrome's persistent Google login.

Install

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

Session

Chrome stores login in ~/.phantom-canvas/chrome-profile/. First time use:

# Open Chrome, login to Google in the window that opens
phantom-canvas chrome

# Or just run generate — Chrome auto-launches
phantom-canvas generate "test" --headed

Login persists across sessions. No export/import needed.

When you see "Session expired", tell the user to run phantom-canvas chrome and re-login. Do NOT automate login — it requires human interaction with Google auth.

CLI Generate (for agents and scripts)

Output is JSON on stdout. Logs go to stderr. Images downloaded at full resolution (1024px).

Text-to-Image

phantom-canvas generate "pixel art knight, isometric, green #00FF00 bg" -o knight.png

{"status":"completed","path":"knight.png","type":"image","conversation_id":"abc123"}

Image-to-Image (reference upload)

phantom-canvas generate "4 directions of this character in a 2x2 grid" --ref ./knight.png -o sheet.png

Multi-Turn (iterative design)

# Round 1
RESULT=$(phantom-canvas generate "pixel art knight, green bg")
CONV=$(echo $RESULT | jq -r .conversation_id)

# Round 2 — Gemini remembers the character
phantom-canvas generate "make the sword bigger" --conversation $CONV -o v2.png

# Round 3
phantom-canvas generate "show 4 directions" --conversation $CONV -o sheet.png

Video

phantom-canvas generate "walk cycle animation" --video --ref knight.png -o walk.mp4

Video takes 1-2 min. Gemini has daily video quotas.

CLI Options

HTTP API (server mode)

phantom-canvas serve [--port 8420]

# Generate
curl -X POST localhost:8420/generate \
  -d '{"prompt":"...", "reference_images":["/path/to/ref.png"], "type":"image"}'

# Check status
curl localhost:8420/task/{id}

# Download
curl localhost:8420/task/{id}/image/0 -o result.png

Tips

• Use #00FF00 green background instead of "transparent" — Gemini draws checkerboard patterns for transparent
• Green screen is easy to chroma-key in post-processing
• For game sprites, generate single characters first, then use --ref for multi-angle sheets
• Headless mode works but may be slower — use --headed for faster/more reliable generation

Error Handling