pi-image-gen

pi install @ssweens/pi-image-gen

Image generation extension for pi. Adds a generate_image tool and /image-model selector. Supports OpenAI, Google, and OpenRouter providers, with runtime discovery of new models from OpenRouter.

Features

• 🎨 20+ built-in models — OpenAI, Google Gemini, OpenRouter (FLUX, Seedream, Riverflow, and more)
• 🔄 Runtime discovery — Automatically finds new OpenRouter image models on startup
• ⚙️ Custom providers — Point at any compatible API via settings files
• 🖼️ Aspect ratios & quality — 1:1, 16:9, 9:16, 4:3, etc. with quality controls
• 💾 Flexible save modes — Project-local, global, or custom directory
• 🎯 /image-model command — Interactive fuzzy-search model picker with session persistence

Install

pi install npm:@ssweens/pi-image-gen
# or from local path
pi install /path/to/pi-image-gen

Usage

Just ask the agent to generate an image:

> Generate an image of a sunset over mountains

> Create a 16:9 wallpaper of a cyberpunk city using dall-e-3

> Make me a logo for a coffee shop, save it to the project

Choosing a Model

Use /image-model — works in both Pi terminal and Minapi:

/image-model                                 # Interactive picker (fuzzy search)
/image-model openai/gpt-image-1              # Direct selection
/image-model openrouter/openai/gpt-5-image   # OpenRouter model

Selection persists in the session and shows in the status bar as 🎨 provider/model.

Built-in Providers & Models

Models are auto-generated from OpenRouter's API and static catalogs. Run npm run generate-models to refresh.

| Provider | Models | API Key | API Type | |----------|--------|---------|----------| | openai | gpt-image-1, dall-e-3, dall-e-2 | OPENAI_API_KEY | /v1/images/generations | | google | gemini-2.0-flash-preview-image-generation, imagen-3.0-generate-002 | GEMINI_API_KEY | Gemini generateContent | | openrouter | openai/gpt-5-image, openai/gpt-5-image-mini, google/gemini-2.5-flash-image, google/gemini-3-pro-image-preview, FLUX.2 variants, Seedream, Riverflow, and more | OPENROUTER_API_KEY | Chat completions |

Resolution Order

When generating an image, the model is resolved in this order:

1. Session selection — /image-model command
2. Settings file — defaultProvider / defaultModel in pi-image-gen.json
3. Default — first available OpenRouter model, then OpenAI

Configuration

Custom Models via Settings

Define image providers in ~/.pi/agent/settings/pi-image-gen.json (global) or <project>/.pi/settings/pi-image-gen.json (project-local, overrides global):

{
  "defaultProvider": "local-llm",
  "defaultModel": "my-local-image-model",
  "providers": {
    "local-llm": {
      "baseUrl": "http://192.168.1.51:9999/v1",
      "apiKey": "MY_API_KEY",
      "api": "openai-images",
      "models": [
        {
          "id": "my-local-image-model",
          "name": "My Local Image Model",
          "cost": 0
        }
      ]
    }
  }
}

Supported API Types

| Type | Used By | Endpoint | |------|---------|----------| | openai-images | OpenAI direct | POST /v1/images/generations | | openai-chat-image | OpenRouter | POST /v1/chat/completions with modalities: ["image"] | | google-generative-ai-image | Google Gemini | POST /models/{id}:generateContent |

Model-level api overrides provider-level api.

Legacy: models.json

pi-image-gen also reads providers.<name>.models[] entries in ~/.pi/agent/models.json that are tagged with output: ["image"]. This is lower priority than the settings file.

Save Modes

| Mode | Location | |------|----------| | none | Don't save (default) | | project | <repo>/.pi/generated-images/ | | global | ~/.pi/agent/generated-images/ | | custom | saveDir param or PI_IMAGE_SAVE_DIR |

Tool Parameters

The generate_image tool accepts:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | prompt | string | required | Description of the image to generate | | aspectRatio | string | 1:1 | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 | | imageSize | string | 1K | 1K, 2K, 4K (OpenRouter models only) | | quality | string | auto | auto, low, medium, high (OpenAI direct only) | | save | string | none | none, project, global, custom | | saveDir | string | — | Directory for save=custom | | timeout | number | 600 | Generation timeout in seconds |

Pi Integration

• API keys — Resolved via ctx.modelRegistry.getApiKeyForProvider() (env vars, auth.json, OAuth)
• Base URLs — From model data, settings providers, or Pi's registry
• Custom providers — Define in ~/.pi/agent/settings/pi-image-gen.json

Architecture

Mirrors Pi's text model pipeline:

| Layer | Pi (text) | pi-image-gen | |-------|-----------|--------------| | Build-time discovery | generate-models.ts → models.generated.ts | generate-image-models.ts → image-models.generated.ts | | Runtime discovery | None | OpenRouter /v1/models on startup (24h cache) | | Sources | models.dev, OpenRouter, AI Gateway | OpenRouter (output_modalities: ["image"]), static catalog | | Custom models | models.json providers | settings/pi-image-gen.json (preferred) + legacy models.json | | API key resolution | ModelRegistry.getApiKeyForProvider() | Same | | Model selection | Ctrl+P / model selector | /image-model command |

Model Priority (lowest → highest)

1. Built-in generated — image-models.generated.ts (baked into package)
2. Runtime discovered — OpenRouter API fetch, cached at ~/.pi/agent/cache/pi-image-gen-discovered.json (24h TTL)
3. Legacy models.json — providers.<name>.models[] entries with output: ["image"]
4. Settings providers — providers in pi-image-gen.json settings file
5. Session selection — /image-model command or tool params

Adding Providers

1. Add static models to scripts/generate-image-models.ts
2. Or add a new dynamic fetch function (like fetchOpenRouterImageModels)
3. Run npm run generate-models
4. Add generation logic in extensions/image-gen.ts if a new API type is needed

License

MIT