gpt_image_playground README

The project's README from github.com/CookSleep/gpt_image_playground. As one markdown file: README.md.

🎨 GPT Image Playground

GitHub Repo stars GitHub forks License React TypeScript

基于 OpenAI gpt-image-2.5 API 的图片生成与编辑工具

提供简洁精美的 Web UI,支持 OpenAI / OpenAI 兼容接口、sub2api(异步)、fal.ai 与可导入的自定义 HTTP 供应商。
支持文本生图、参考图与遮罩编辑,数据纯本地化存储,带来流畅的历史记录与参数管理体验。


Vercel 在线体验     GitHub Pages 在线体验


💡 提示:若需调用非 HTTPS 的内网或本地 HTTP API,请使用 GitHub Pages 版本或自行部署,Vercel 部署的体验版绑定的 .dev 域名因安全策略通常要求接口必须为 HTTPS。


❤️ 赞助商

摸鱼 AI 摸鱼 AI ,让 AI API 接入更简单。明码标价,充值 1:1,支持 GPT、Claude、Gemini 等主流模型,重新定义「便宜 · 稳定 · 高速」
JuCodex JuCodex 为企业级用户打造的高可用、低延迟、极致性价比的中转站,提供 Codex、Claude Code、Grok 等主流大模型中转服务,新用户注册送 3 元(QQ 邮箱),永久承诺 0 水 0 替、模型 100% 保真。生图工作台
MaruCode MaruCode 是一家偶尔做做慈善的小破站 API,自营号池,主要提供 Codex、Claude Code、GPT Image 等主流模型,支持 Websocket 协议,明码标价(Codex 0.25x, CC 1.5x),透明汇率(1:1),新用户注册送 2 刀。生图工作台🖼️
APIMart APIMart 是专注 AI 图片/视频生成的低价 API 平台,GPT-Image-2 低至 $0.006/张,1 美元可出图 160+ 张。图片、视频一套异步 API 通吃,提交任务拿 ID、回调取结果,跑批万张不超时、换模型不改代码。按量付费、无月费,通过此注册链接注册即可开用。
9527 CODE 9527 CODE 是企业级满血 AI 中转服务平台,专注提供 Claude Code、Codex 等主流模型的高稳定中转能力,为企业级 AI 使用提供稳定、合规、高效的一站式解决方案。
Sublyx Sublyx 是一家稳定高效的 AI API 聚合网关,支持 OpenAI、Claude、Grok、Codex、gpt-image-2 等主流模型,兼容 OpenAI SDK、Claude Code、Codex、Cherry Studio 等常用工具。通过链接注册并使用优惠码 IMG2,可额外领取 10 刀额度。生图工作台

📸 界面预览

点击展开截图展示
桌面端主界面
桌面端主界面

任务详情与实际参数
任务详情与实际参数

桌面端批量选择
桌面端批量选择

桌面端 Agent 模式
桌面端 Agent 模式

移动端主界面
移动端主界面

移动端侧滑多选
移动端侧滑多选

✨ 核心特性

🎨 强大的图像生成与编辑

🤖 Agent 多轮对话模式

⚙️ 精细化参数追踪

📁 高效历史管理 (纯本地)

🔌 多配置与供应商增强


🚀 部署与使用

支持多种部署与开发方式。

预置配置说明

所有部署方式都可以通过环境变量提供“预置配置”——部署端预先加入用户配置列表的 API 配置。用户打开页面时会自动看到这些配置,无需手动创建,格式和用户自己创建的配置完全一致。

环境变量的值支持三种填写方式:

填写方式 说明 示例
直接填写 API 地址 自动创建一个 OpenAI 兼容的默认预置配置(ID 为 default-openai)并注入 API URL,其余参数(模型、超时等)使用应用默认值,用户只需补充 API Key。末尾带 / 时直接拼接接口,不补 /v1 前缀。适合只提供一个配置的部署。后续如需通过 JSON 或链接更新此配置,指定 id 为 default-openai 即可。 https://api.openai.com/v1
API 地址 + 查询参数 在地址后追加参数,可同时预填 Key、模型等字段。 https://api.openai.com/v1?model=gpt-image-2.5-sunburst&apiMode=images
JSON 配置文件 / 导入链接 通过仓库内或本地的 JSON 文件路径(如 ./config.json)、远程 URL 或含 ?settings= 参数的导入链接提供完整预置配置,支持预置多个配置(OpenAI 兼容、sub2api(异步)、fal.ai 或自定义供应商)。 详见 预置配置 JSON 格式

环境变量一览

部署时可以通过设置环境变量来控制预置配置和客户端行为。有关 Docker 专属的网络与代理配置(如 ENABLE_API_PROXY 等),请参考下方的 Docker 部署 章节。

构建时变量 (Vercel/CF/本地) Docker 运行变量 功能说明
VITE_DEFAULT_API_URL DEFAULT_API_URL 设定预置配置值(支持 URL 形式或 JSON 格式,详见 预置配置 JSON 格式)
VITE_LOCK_PRESET_CONFIG_PARAMS=true LOCK_PRESET_CONFIG_PARAMS=true 锁定预置配置中除 API Key 外的参数,并禁止编辑预置供应商定义;当前锁定配置引用的供应商不可删除,解除引用后可删除
VITE_PREVENT_PRESET_CONFIG_DELETION=true PREVENT_PRESET_CONFIG_DELETION=true 禁止删除预置配置和预置供应商,不锁定参数;普通项不受影响
VITE_SHOW_PRESET_CONFIG_ONLY=true SHOW_PRESET_CONFIG_ONLY=true 只允许使用当前预置配置,禁止创建、复制、删除、拖动、切换供应商和管理自定义供应商;未同时开启锁定时参数仍可编辑,API Key 始终可编辑

未开启上述限制时的默认行为:

  • 参数更新:API 地址、模型、超时等参数会与上一次部署快照比较;部署值发生变化时覆盖一次本地值,之后保留用户的本地修改,直到部署值再次变更。
  • API Key:始终由用户在本地管理,重新部署不覆盖。
  • 排序与删除:预置配置可拖动;预置配置和预置供应商均允许删除,删除状态保存在浏览器中,重新部署不会恢复。
  • 下线预置清理:部署端移除某个预置后,若用户从未修改过该配置且没有历史生成任务引用,会自动从本地删除;若已被修改或仍被历史任务引用,则保留并转为普通配置。
  • 失效供应商清理:随预置引入的自定义供应商在不再被任何配置使用、且从未被用户修改时,也会自动清理。

兼容提示:旧变量 VITE_SHOW_DEFAULT_CONFIG_ONLY/SHOW_DEFAULT_CONFIG_ONLY 仍可使用,等同于对应的 SHOW_PRESET_CONFIG_ONLY。

部署方式

▲ 方式一:Vercel 一键部署 (推荐)

支持通过 Vercel 一键导入 GitHub 仓库并自动完成构建部署。

预置配置

在 Vercel 项目的 Settings → Environment Variables 中设置 VITE_DEFAULT_API_URL,支持上述三种填写方式,可直接填写 API 地址或指定配置文件路径(如仓库内的 gpt-image-config.example.json 模板)。详见 预置配置说明。

VITE_DEFAULT_API_URL=https://api.openai.com/v1

初始部署

Deploy with Vercel

点击上方按钮导入仓库即可,Vercel 会自动执行构建并部署静态文件。添加或修改环境变量后需要重新部署。

绑定自定义域名 (国内直连):Vercel 默认分配的 .vercel.app 域名在国内通常无法直接访问。如果你希望在国内直连访问,请在 Vercel 项目的 Settings → Domains 中绑定你自己的域名。

更新方式

本项目已在 vercel.json 中关闭了默认的自动部署。若你 Fork 了本仓库,建议配置 Deploy Hook 以实现新版本自动构建:

  1. 在 Vercel 项目的 Settings → Git → Deploy Hooks 中创建一个名为 Release 的 Hook(Branch 填 main)并复制生成的 URL。
  2. 在你 Fork 的 GitHub 仓库 Settings → Secrets and variables → Actions 中,新建 Secret VERCEL_DEPLOY_HOOK,填入刚才的 URL。

配置完成后:

  • 自动更新:只有在本仓库发布了正式版本(即包含新 Release / 版本号变动)时,在你的 Fork 页面点击 Sync fork 才会自动触发 Vercel 构建部署;日常的普通代码提交不会触发部署。
  • 手动触发:若需立即部署最新代码(包括未发布正式版本的日常提交),可进入仓库顶部的 Actions 标签页,在左侧选择 Deploy to Vercel,点击右侧的 Run workflow 下拉按钮(分支选择 main),点击绿色的 Run workflow 按钮即可手动部署。
🌐 方式二:GitHub Pages 部署

支持通过 GitHub Actions 工作流将静态页面发布至 GitHub Pages。

预置配置

在仓库 Settings → Secrets and variables → Actions 中添加 Secret VITE_DEFAULT_API_URL,支持上述三种填写方式,可直接填写 API 地址或指定配置文件路径(如仓库内的 gpt-image-config.example.json 模板)。详见 预置配置说明。

VITE_DEFAULT_API_URL=https://api.openai.com/v1

初始部署

  1. 在 GitHub 仓库的 Settings → Pages 中,将 Build and deployment → Source 设置为 GitHub Actions。
  2. 进入仓库顶部的 Actions 标签页,在左侧选择 Deploy to GitHub Pages,点击右侧的 Run workflow 下拉按钮(分支选择 main),点击绿色的 Run workflow 按钮完成首次构建部署。

更新方式

  • 自动更新:只有在本仓库发布了正式版本(即包含新 Release / 版本号变动)时,在你的 Fork 页面点击 Sync fork 才会自动触发构建并部署至 GitHub Pages;日常的普通代码提交不会触发部署。
  • 手动触发:若需立即部署最新代码(包括未发布正式版本的日常提交),可进入仓库顶部的 Actions 标签页,在左侧选择 Deploy to GitHub Pages,点击右侧的 Run workflow 下拉按钮(分支选择 main),点击绿色的 Run workflow 按钮即可手动部署。
☁️ 方式三:Cloudflare Workers 部署

支持通过内置的 Wrangler 配置将构建产物作为静态资源部署至 Cloudflare Workers。

预置配置

在执行构建前设置环境变量 VITE_DEFAULT_API_URL,支持上述三种填写方

gpt_image_playground (CookSleep/gpt_image_playground)

Searching Database…

What is this?GPT Image Playground is a web UI for generating and editing images through the OpenAI gpt-image-2.5 API, with support for OpenAI-compatible endpoints, sub2api, fal.ai, and custom HTTP providers.
Is this a ready-to-use web app or a library I plug into my own project?It is a standalone web app built with React/Vite/Tailwind that you deploy (or run locally) and use directly in the browser, not a library to embed in code.
How do I get it running?Deploy it with one click on Vercel, publish it to GitHub Pages via the included GitHub Actions workflow, or deploy static assets to Cloudflare Workers with Wrangler; a Docker setup is also provided.
Do I need an OpenAI API key to use it?You need an API key from OpenAI or a compatible provider (or fal.ai/sub2api) to generate images; the app itself only requires Node/npm if you build it yourself.
Can I point it at a local or intranet API without HTTPS?The Vercel demo's bound domain enforces HTTPS for API calls due to security policy, so non-HTTPS local/intranet APIs won't work there — use the GitHub Pages build or self-host instead.
What does Agent mode do?Agent mode is a multi-turn conversational generation flow built on the Responses API: it keeps context, can reference images from earlier turns with @, batch-generates multiple related images in one turn, and lets you branch by editing or regenerating a message.
How does transparent background generation work?In gallery mode with PNG/WebP output you can enable transparency either natively (asking the model to return an alpha channel, if supported) or via local post-processing, where the model renders on a solid green/magenta backdrop that the browser then removes.
How many reference images can I use when editing?You can upload up to 16 reference images via clipboard or drag-and-drop, plus use a built-in mask editor for targeted edits.
Can I connect providers other than OpenAI?Yes — besides OpenAI-compatible endpoints, it supports sub2api (async), fal.ai (queue-based), and any custom HTTP provider you import via a JSON configuration.
Creator
CookSleep
Size
43.6 MB
Stars
3.9K
Age
5mo
Commits · 90 Days