# 1. 设置 API Key（二选一）
export GPT_IMAGE_API_KEY="sk-..."
# 或
export OPENAI_API_KEY="sk-..."

# 2a. 临时加载（开发调试）
pi -e ./image-gen.ts

# 2b. 安装到项目（自动加载）
mkdir -p .pi/extensions && cp image-gen.ts .pi/extensions/

# 2c. 全局安装
cp image-gen.ts ~/.pi/agent/extensions/

首次加载时，扩展会自动检测是否已配置 API Key：

✅ 已配置 → 提示 🎨 Image generation ready (model: ..., endpoint: ...)
⚠️ 未配置 → 提示设置方式

启动 pi 后即可使用：

你: 画一只在水彩风格下坐在书桌上的猫

Pi: 🎨 正在生成图片...
    ✅ 图片已生成！
    📁 文件: /your/project/generated-images/generated_image_1700000000000.png
    📏 尺寸: 1024x1024
    🔧 模型: gpt-image-2
    💾 文件大小: 245.3 KB

配置方式

所有配置均支持 三种来源，优先级从高到低：

优先级	来源	说明
1	工具参数 / 命令 flag	每次调用可不同，最灵活
2	环境变量	启动时设置，全局生效
3	内置默认值	无需任何配置即可使用（需设 API key）

环境变量

变量	默认值	说明
`GPT_IMAGE_API_KEY`	—	API key（优先）
`OPENAI_API_KEY`	—	备选 API key
`GPT_IMAGE_BASE_URL`	`https://api.openai.com/v1`	API 端点地址
`GPT_IMAGE_MODEL`	`gpt-image-2`	模型 ID
`GPT_IMAGE_OUTPUT_DIR`	`generated-images`	图片输出目录（相对于 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 -e ./image-gen.ts

运行时覆盖

每次调用时可以覆盖任意配置，无需修改环境变量：

工具调用（LLM 自动使用）：

generate_image 工具支持以下额外参数：

参数	说明
`apiKey`	本次调用使用的 API key
`baseUrl`	本次调用的 API 端点
`model`	本次使用的模型 ID
`outputDir`	本次输出目录

你: 用 relay 端点的模型画一只猫

Pi: [调用 generate_image，自动附带 baseUrl 和 model 覆盖]

/image 命令：

# 基本用法
/image a watercolor painting of a cat

# 覆盖端点和模型
/image --base-url https://your-relay.example.com/v1 --model your-model-id a cat on a desk

# 覆盖输出目录
/image --output-dir ./my-artwork a sunset over the ocean

# 完整覆盖
/image --api-key sk-... --base-url https://... --model ... --output-dir ... a cat

工具参数

generate_image 工具暴露给 LLM 的全部参数：

参数	必填	默认值	说明
`prompt`	✅	—	图片描述，越详细越好
`size`		`1024x1024`	`1024x1024` · `1536x1024` · `1024x1536`
`quality`		`medium`	`low` · `medium` · `high`
`filename`		`generated_image_<时间戳>.png`	输出文件名
`model`		`gpt-image-2`	模型 ID，覆盖环境变量
`apiKey`		环境变量	API key，覆盖环境变量
`baseUrl`		环境变量	API 端点，覆盖环境变量
`outputDir`		`generated-images`	输出目录，覆盖环境变量

输出

图片默认保存到项目目录下的 generated-images/：

your-project/
├── .pi/extensions/image-gen.ts    ← 扩展文件
└── generated-images/              ← 生成图片
    ├── generated_image_1700000000000.png
    └── my-cat.png

LLM 会自动用 pi 的 read 工具展示图片：

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

开发

# 运行测试（35 项，使用 node:test）
npm test

# 在 pi 中加载测试
GPT_IMAGE_API_KEY=sk-test pi -e ./image-gen.ts

项目结构

pi-image-gen/
├── image-gen.ts          ← 扩展主文件（纯函数 + Extension 工厂）
├── image-gen.test.ts     ← 测试（35 tests）
├── package.json          ← npm test 脚本
├── tsconfig.json         ← TypeScript 严格模式
├── .gitignore
└── README.md

配置优先级流转

调用时传入的参数（最高优先级）
        │
        ▼  未提供的字段 ↓
环境变量（GPT_IMAGE_API_KEY / GPT_IMAGE_BASE_URL / ...）
        │
        ▼  未设置的字段 ↓
内置默认值（gpt-image-2 / https://api.openai.com/v1 / generated-images）

安全

✅ 零硬编码密钥 — API key 仅从环境变量或调用参数读取
✅ 不在日志、返回值、JSON body 中泄露 Authorization header
✅ 文件名自动清理 — 移除 ../、null 字节、shell 元字符
✅ 输出目录限制在项目内 — resolveOutputPath 使用 ctx.cwd + 相对路径

故障排查

错误	原因	解决
`Missing API key`	未设置 key	`export GPT_IMAGE_API_KEY="sk-..."` 或传 `--api-key`
`HTTP 401`	key 无效或过期	检查 key 和余额
`HTTP 400`	参数不合法	检查 prompt 是否违反内容政策
`No image data returned`	API 返回空	重试或检查 endpoint
扩展加载但工具不出现	路径不对	确保在 `.pi/extensions/` 下且为 `.ts`