pi-image-gen

简体中文

A Pi Coding Agent extension that adds image generation via gpt-image-2 (or any OpenAI-compatible endpoint).

Speak naturally — "draw a cat" — and the LLM calls generate_image automatically. Or use /image <prompt> directly.

You: draw a watercolor cat sitting on a desk

Pi: 🎨 Generating image...
    ✅ Image generated!
    📁 File: /your/project/generated-images/generated_image_1700000000000.png
    📏 Size: 1024x1024   🎨 Quality: medium   🔧 Model: gpt-image-2
    💾 245.3 KB

Install

# Option 1: Copy to project extensions (auto-loaded)
mkdir -p .pi/extensions
curl -o .pi/extensions/image-gen.ts https://unpkg.com/@leing2021/pi-image-gen/image-gen.ts

# Option 2: Global extensions
mkdir -p ~/.pi/agent/extensions
curl -o ~/.pi/agent/extensions/image-gen.ts https://unpkg.com/@leing2021/pi-image-gen/image-gen.ts

# Option 3: Quick test (no install)
pi -e ./image-gen.ts

On first launch the extension checks for an API key and guides you if missing.

Configure

Three levels of configuration, highest priority first:

| Priority | Source | Use case | |:--------:|--------|----------| | 1 | Tool params / command flags | Per-request override | | 2 | Environment variables | Global defaults | | 3 | Built-in defaults | Zero config for OpenAI users |

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | GPT_IMAGE_API_KEY | — | API key (preferred) | | OPENAI_API_KEY | — | Fallback key | | GPT_IMAGE_BASE_URL | https://api.openai.com/v1 | API endpoint | | GPT_IMAGE_MODEL | gpt-image-2 | Model ID | | GPT_IMAGE_OUTPUT_DIR | generated-images | Output directory (relative to cwd) |

export GPT_IMAGE_API_KEY="sk-..."
export GPT_IMAGE_BASE_URL="https://your-relay.example.com/v1"
export GPT_IMAGE_MODEL="your-model-id"
pi

Per-request override

Override any setting for a single call — no need to change env vars.

/image command flags:

/image a watercolor cat
/image --model your-model-id --base-url https://your-relay.example.com/v1 a cat
/image --output-dir ./my-artwork a sunset over the ocean

generate_image tool params (the LLM passes these automatically):

| Param | Type | Description | |-------|------|-------------| | prompt | string | Required. Image description. | | size | string | 1024x1024 · 1536x1024 · 1024x1536 | | quality | string | low · medium · high | | filename | string | Output filename (auto-sanitized) | | model | string | Model ID override | | apiKey | string | API key override | | baseUrl | string | API endpoint override | | outputDir | string | Output directory override |

Output

Images are saved to generated-images/ relative to the project root:

your-project/
└── generated-images/
    ├── generated_image_1700000000000.png
    └── my-cat.png

Pi's read tool can display the generated image:

read("generated-images/my-cat.png")

Security

• No hardcoded keys — API keys come from env vars or per-call params only.
• Authorization header is never logged or returned to the LLM.
• Filenames are sanitized: ../, null bytes, and shell metacharacters are stripped.
• Output is scoped to the project directory via ctx.cwd.

Troubleshooting

| Error | Cause | Fix | |-------|-------|-----| | Missing API key | No key configured | export GPT_IMAGE_API_KEY="sk-..." or pass --api-key | | HTTP 401 | Invalid or expired key | Check key and account balance | | HTTP 400 | Invalid parameters | Check prompt for content policy violations | | No image data returned | Empty API response | Retry or verify endpoint | | Tool not appearing | Wrong file path | Must be in .pi/extensions/*.ts |

Develop

npm test        # 35 tests, zero npm test dependencies (uses node:test)
npm run typecheck

Project structure

pi-image-gen/
├── image-gen.ts          # Extension (pure functions + factory)
├── image-gen.test.ts     # Tests (35 tests)
├── package.json
├── tsconfig.json
└── LICENSE               # MIT

License

MIT