图像 Playground（中文版）

一个基于 Web 的可视化 Playground，用于调用 OpenAI 的 GPT 图像模型（gpt-image-2、gpt-image-1.5、gpt-image-1 与 gpt-image-1-mini）进行图像生成和编辑。

说明： Playground 默认使用 gpt-image-2（OpenAI 最新的 GPT 图像模型），除了支持原有的固定尺寸外，还支持最高 4K 的任意分辨率（带约束校验）。

---

🙏 致谢与项目来源

本项目 Fork 自 alasano/gpt-image-playground，原作者用 Next.js 搭建了一个非常优秀的 GPT 图像 Playground，几乎覆盖了 OpenAI Images API 的全部参数与历史成本追踪能力。在此向原作者及所有上游贡献者表示诚挚的感谢 🙏。

本仓库主要在原项目基础上做了界面中文化等小幅本地化调整，便于中文用户使用。原项目协议为 MIT License，本仓库同样以 MIT 协议开源。

---

✨ 功能特性

• 🎨 图像生成模式： 通过文本提示词从零创建新图像。

• 🖌️ 图像编辑模式： 基于文本提示词和可选的蒙版（mask）对已有图像进行修改。

• ⚙️ 完整的 API 参数控制： 直接在 UI 中访问并调整 OpenAI Images API 支持的全部相关参数（尺寸、质量、输出格式、压缩、背景、内容审核、生成数量等）。

• 📐 自定义分辨率（gpt-image-2）： 可从 2K/4K 预设中选择，也可输入任意 宽 × 高，并对模型约束进行实时校验（必须为 16 的倍数、单边最大 3840px、宽高比 ≤ 3:1、总像素在 655,360 ~ 8,294,400 之间）。

• 🎭 集成蒙版工具： 在编辑模式中可直接创建或上传蒙版来指定修改区域，也可以直接在图像上绘制以生成蒙版。

  ⚠️ 请注意 gpt-image-1 的蒙版功能目前并不能保证 100% 的精确控制。
  1) 这是模型已知且被官方确认的局限。
  2) OpenAI 表示会在后续更新中改进。

• 📜 详细的历史记录与成本追踪：
  • 查看所有图像生成与编辑的完整历史记录。
  • 查看每次请求所使用的参数。
  • 查看每次操作的 API token 使用量与估算成本（$USD）明细。（提示：点击图像上的 $ 金额查看详情）
  • 查看每条历史记录所使用的完整提示词。
  • 查看历史 API 总成本。
  • 支持从历史记录中删除条目。

• 🖼️ 灵活的图像输出视图： 可以以网格方式查看一批生成的图像，也可以选择单张图像进行细看。
• 🚀 一键发送到编辑： 任何生成的图像或历史图像都可一键发送到编辑表单。
• 📋 粘贴到编辑： 可直接从剪贴板将图像粘贴到编辑模式的源图像区域。
• 💾 存储模式： 通过 NEXT_PUBLIC_IMAGE_STORAGE_MODE 支持两种模式：
  • 文件系统（默认）： 图像保存到服务器的 ./generated-images 目录。
  • IndexedDB： 图像直接保存在浏览器的 IndexedDB 中（适合 Serverless 部署）。
  • 生成历史的元数据始终保存在浏览器的 localStorage 中。

---

▲ 部署到 Vercel

🚨 注意：如果你从 main 或 master 分支部署，你的 Vercel 部署将对所有持有 URL 的人 公开可见。从其他分支部署则需要访问者已登录 Vercel（且属于你的团队）才能查看预览构建。 🚨

你可以使用一键部署按钮把本 Playground 部署到 Vercel：

部署过程中会提示你输入 OPENAI_API_KEY 与 APP_PASSWORD。在 Vercel 上部署时，必须将 NEXT_PUBLIC_IMAGE_STORAGE_MODE 设置为 indexeddb。

说明：如果未设置 NEXT_PUBLIC_IMAGE_STORAGE_MODE，应用会自动检测是否运行在 Vercel（通过 VERCEL 或 NEXT_PUBLIC_VERCEL_ENV 环境变量），并在该情况下默认使用 indexeddb 模式；否则（例如本地运行）默认使用 fs 模式。你也可以手动将该变量设为 fs 或 indexeddb 来覆盖这一自动行为。

---

🚀 快速开始（本地部署）

按以下步骤在本地运行 Playground。

前置条件

• Node.js（需要 20 或更高版本）
• npm、yarn、pnpm 或 bun

1. 配置 API Key 🟢

你需要一个 OpenAI API Key 来使用本应用。

⚠️ 你的 OpenAI 组织需要先通过身份验证才能使用 GPT 图像模型

1. 如果项目中没有 .env.local 文件，请新建一个。

2. 在 .env.local 中添加你的 OpenAI API Key：

   OPENAI_API_KEY=your_openai_api_key_here

   重要： 请妥善保管你的 API Key。.env.local 默认已加入 .gitignore，避免被意外提交。

---

🟡（可选）IndexedDB 模式（适用于 Serverless 主机，例如 Vercel）

对于文件系统只读或临时性的环境（例如 Vercel Serverless Functions），可以将应用配置为使用 Dexie.js 把生成的图像直接存储在浏览器的 IndexedDB 中。

在 .env.local 文件中或托管平台（如 Vercel）的环境变量界面中设置：

NEXT_PUBLIC_IMAGE_STORAGE_MODE=indexeddb

当该变量被设置为 indexeddb 时：

• 服务端 API（/api/images）会以 base64（b64_json）方式返回图像数据，而不是写入磁盘。
• 前端会将 base64 解码后，把图像 blob 存入 IndexedDB。
• 图像通过 Blob URL 直接由浏览器存储中提供。

如果该变量 未设置 或为其他值，应用会回退到默认行为：把图像保存到服务器的 ./generated-images 目录。

说明： 如果未设置 NEXT_PUBLIC_IMAGE_STORAGE_MODE，应用会自动检测是否运行在 Vercel（通过 VERCEL 或 NEXT_PUBLIC_VERCEL_ENV 环境变量），并在该情况下默认使用 indexeddb 模式；否则（例如本地运行）默认使用 fs 模式。你也可以显式将其设为 fs 或 indexeddb 来覆盖该自动行为。

🟡（可选）使用自定义 API 端点

如果你需要使用与 OpenAI 兼容的 API 端点（例如本地模型服务或第三方提供商），可在 .env.local 中通过 OPENAI_API_BASE_URL 指定其 base URL：

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_API_BASE_URL=your_compatible_api_endpoint_here

如果未设置 OPENAI_API_BASE_URL，应用会默认使用 OpenAI 官方 API 端点。

---

🟡（可选）启用密码校验

APP_PASSWORD=your_password_here

当设置了 APP_PASSWORD 后，前端会弹出密码输入框对请求进行身份验证。

---

2. 安装依赖 🟢

进入项目目录并安装依赖：

npm install
# 或
# yarn install
# 或
# pnpm install
# 或
# bun install

3. 启动开发服务器 🟢

启动 Next.js 开发服务器：

npm run dev
# 或
# yarn dev
# 或
# pnpm dev
# 或
# bun dev

4. 打开 Playground 🟢

在浏览器中打开 http://localhost:3000 即可使用图像 Playground！

---

🤝 贡献

欢迎提交 Issue 和 PR。原项目位于 alasano/gpt-image-playground，重要的功能特性建议优先回馈给上游。

📄 License

MIT（与原项目保持一致）