@leing2021/pi-image-gen

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