@bytetrue/pi-image-gen

Forked from @amaster.ai/pi-image-gen, Apache-2.0. See NOTICE.

Image generation for Pi with two deliberately separate surfaces:

• /image-gen — complete TUI setup for people: provider, model, endpoint, credential, headers, output directory.
• pi-image-gen Skill + bundled CLI — loaded only when the agent actually needs to generate or edit an image. The package does not register a permanent Agent tool.

Supported image API protocols: OpenAI, Google Gemini, Alibaba DashScope, Volcengine Ark, and OpenRouter.

Install

pi install npm:@bytetrue/pi-image-gen

Restart Pi, run /image-gen, choose a built-in or custom provider, and finish the wizard. No manual JSON editing is required.

For local development, build first because the package entry and Skill CLI use dist:

npm --workspace @bytetrue/pi-image-gen run build
pi install /absolute/path/to/pi-package-mono/packages/pi-image-gen

Configure in Pi

Run /image-gen and choose:

• Configure a built-in provider and model — OpenAI, Gemini, DashScope, Ark, or OpenRouter.
• Configure a custom provider and model — choose one of the five wire protocols, then set the endpoint and model id.
• Set output directory.
• Show effective configuration — reports the route without printing credentials.

Credential choices are:

• the provider's standard environment variable;
• another $ENV_VAR reference;
• a literal key entered through a masked TUI field;
• no key for a local/keyless endpoint.

The wizard can write either the active global settings or, when Pi trusts the project, <cwd>/.pi/settings.json. Writes are atomic and 0600; malformed files are never overwritten.

All configuration remains under the pi-image-gen key in Pi settings.json:

1. ~/.pi/agent/settings.json;
2. $PI_CODING_AGENT_DIR/settings.json or $PI_AGENT_HOME/settings.json when set;
3. trusted <cwd>/.pi/settings.json.

Project settings are ignored by the normal Skill CLI path unless the running Pi session explicitly trusts that exact working directory. This prevents an untrusted repository from replacing an endpoint while reusing a global or environment credential during normal package use; it is not a sandbox against an actively modified shell invocation.

Generate from Pi

Ask normally, for example:

Generate a cinematic 16:9 image of a lunar research station.

Pi loads the bundled Skill, which invokes the CLI and returns generated files as inline markdown. To edit or preserve a character/style, attach a local image path or refer to a previous generated path.

The active model is fixed by /image-gen; the CLI has no model override. This keeps routing intentional and reproducible.

Providers and built-in models

Provider	Built-in models / addressing	Standard env var
OpenAI	gpt-image-2	OPENAI_API_KEY
Gemini	gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-2.5-flash-image and Nano Banana aliases	GEMINI_API_KEY
DashScope	qwen-image-2.0-pro, qwen-image-2.0	DASHSCOPE_API_KEY
Ark	Seedream 4/4.5/5 model ids and aliases	ARK_API_KEY
OpenRouter	openrouter/<vendor>/<model>	OPENROUTER_API_KEY

Custom providers use one of those wire protocols but may supply any endpoint and model id.

Advanced settings shape

The TUI writes this shape and preserves unrelated Pi settings:

{
  "pi-image-gen": {
    "defaultModel": "my-sd/sd-3-large",
    "outputDir": ".pi/images",
    "providers": {
      "openai": {
        "baseUrl": "https://proxy.example.com/v1",
        "apiKey": "$OPENAI_API_KEY",
        "headers": { "x-tenant": "team-a" }
      }
    },
    "customProviders": {
      "my-sd": {
        "api": "openai",
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "$SD_KEY",
        "headers": { "x-tenant": "team-a" },
        "models": [{ "id": "sd-3-large", "alias": "sd3" }]
      }
    }
  }
}

apiKey, baseUrl, and header values support $VAR, ${VAR}, and ${VAR:-fallback} interpolation.

When the TUI explicitly selects No API key or No extra headers, it writes apiKey: "" or headers: {}. These are intentional tombstones: they suppress credentials and headers inherited from lower settings layers, and an empty built-in apiKey also suppresses the provider's standard environment-variable fallback.

Relative output directories resolve against the Pi session cwd. The default is .pi/images.

Bundled CLI contract

The Skill calls skills/pi-image-gen/scripts/image-gen.mjs. It reads one JSON object from stdin:

{
  "prompt": "A watercolor lighthouse in a winter storm",
  "image": ["/optional/reference.png"],
  "n": 1,
  "size": "1024x1024",
  "filename": "winter-lighthouse"
}

• prompt is required.
• image is an optional array of local paths or http(s) URLs.
• n is 1–8.
• size is provider-specific.
• filename and outputDir are optional.

Use /image-gen rather than invoking the CLI manually for setup. The CLI never prints credentials.

Development checks

npm --workspace @bytetrue/pi-image-gen test
npm --workspace @bytetrue/pi-image-gen run typecheck
node packages/pi-image-gen/scripts/pack-smoke.mjs