# image2
**Repository Path**: z-aong/image2
## Basic Information
- **Project Name**: image2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-14
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🎨 GPT Image Playground
[](https://github.com/CookSleep/gpt_image_playground/stargazers)
[](https://github.com/CookSleep/gpt_image_playground/network/members)
[](https://github.com/CookSleep/gpt_image_playground/blob/main/LICENSE)
[](https://react.dev/)
[](https://www.typescriptlang.org/)
**基于 OpenAI gpt-image-2.5 API 的图片生成与编辑工具**
提供简洁精美的 Web UI，支持 OpenAI / OpenAI 兼容接口、sub2api（异步）、fal.ai 与可导入的自定义 HTTP 供应商。
支持文本生图、参考图、画板标注与遮罩编辑，数据纯本地化存储，带来流畅的历史记录与参数管理体验。
[](https://gpt-image-playground.cooksleep.dev)
[](https://cooksleep.github.io/gpt_image_playground)
> 💡 **提示**：若需调用非 HTTPS 的内网或本地 HTTP API，请使用 GitHub Pages 版本或自行部署，Vercel 部署的体验版绑定的 `.dev` 域名因安全策略通常要求接口必须为 HTTPS。
---
## ❤️ 赞助商
|
摸鱼 AI ，让 AI API 接入更简单。明码标价，充值 1:1，支持 GPT、Claude、Gemini 等主流模型，重新定义「便宜 · 稳定 · 高速」 |
|
JuCodex 为企业级用户打造的高可用、低延迟、极致性价比的中转站，提供 Codex、Claude Code、Grok 等主流大模型中转服务，新用户注册送 3 元（QQ 邮箱），永久承诺 0 水 0 替、模型 100% 保真。生图工作台 |
|
APIMart 是专注 AI 图片/视频生成的低价 API 平台，GPT-Image-2 低至 $0.006/张，1 美元可出图 160+ 张。图片、视频一套异步 API 通吃，提交任务拿 ID、回调取结果，跑批万张不超时、换模型不改代码。按量付费、无月费，通过此注册链接注册即可开用。 |
|
MaruCode 是一家偶尔做做慈善的小破站 API，自营号池，主要提供 OpenAI、Anthropic、GPT Image 等主流模型，支持 Websocket 协议，明码标价(OAI 0.3x, A÷ 1.7x)，透明汇率(1:1)，新用户注册送 1 刀。生图工作台🖼️ |
|
Sublyx 是一家稳定高效的 AI API 聚合网关，支持 OpenAI、Claude、Grok、Codex、gpt-image-2 等主流模型，兼容 OpenAI SDK、Claude Code、Codex、Cherry Studio 等常用工具。通过链接注册并使用优惠码 IMG2，可额外领取 10 刀额度。生图工作台 |
---
## 📸 界面预览
点击展开截图展示
桌面端主界面
任务详情与实际参数
桌面端批量选择
桌面端 Agent 模式
移动端主界面
移动端侧滑多选
---
## ✨ 核心特性
### 🎨 强大的图像生成与编辑
- **参考图与遮罩**：支持上传最多 16 张参考图（支持剪贴板和拖拽）。内置可视化遮罩编辑器，自动预处理以符合官方分辨率限制。
- **画板标注**：可在空白画布或参考图上用画笔、文字、图形和像素橡皮擦标注修改意图，完成后作为参考图使用；画板与遮罩编辑器均支持缩放平移（Alt / Ctrl + 滚轮、Alt + 拖动、双指捏合）。
- **评论标注**：在画板中用评论工具点击图片添加评论，评论以“@图N 评论”胶囊插入提示词，发送时自动附上每条评论在图中的位置（如 `(X=52%, Y=41%)`），复用任务时可恢复评论。
- **批量与迭代**：支持单次多图生成；一键将满意结果转为参考图，无缝开启下一轮修改。
- **多提示词批量提交**：在“设置 - 习惯配置”中开启后，可一次粘贴多条提示词批量生成。提示词之间空两行分隔（评论等单个空行仍属于同一条提示词），参考图和参数对每条提示词都生效；支持排队或并发执行，并发数默认限制为 10，进行中可查看进度并随时停止。
- **流式生成预览**：`Images API` 与 `Responses API` 模式均支持流式接收中间步骤图像，缓解连接超时问题。
- **透明背景（API 原生 / 本地后处理双模式）**：画廊模式下选择 PNG 或 WebP 格式后可开启透明背景功能，每个 API 配置可独立选择实现方式（设置入口在 API 配置页）。API 原生模式会直接请求模型返回透明通道（需当前接口和模型支持；fal.ai 暂无对应参数），本地后处理模式则会要求模型使用纯绿色或纯洋红色背景，并在结果返回后于浏览器中去除背景色，按所选 PNG 或 WebP 格式保存透明结果。
> 本地后处理流程适用于图标、贴纸、单主体素材等场景；若主体边缘存在复杂发丝、半透明材质、强反光或与背景色接近的颜色，可能出现边缘残留或误抠。若使用 API 原生模式时接口返回“不支持透明背景”类错误，应用会提示切换为本地后处理。
### 🤖 Agent 多轮对话模式
- **多轮对话与上下文记忆**：基于 Responses API 的对话式生成，Agent 会理解上下文并按需调用图像工具；支持 `@` 引用参考图或前面轮次生成的图片，并自动识别上下文中的图片。
- **并发批量生成**：内置 `generate_image_batch` 工具，让 Agent 在一次轮次中并发生成多张关联图像，并通过 `continue_generation` 自动追加新一轮以处理依赖关系。
- **分支与重新生成**：编辑某轮消息重新发送或重新生成某轮消息会产生可切换的分支，引用解析严格限定在当前分支路径内，避免误用其他分支的图片。
- **画廊同步与隔离删除**：Agent 生成的图片会同步到画廊；删除对话默认保留画廊记录，删除画廊任务时也会自动清理对话中残留的图片引用。
- **可选 Web 搜索**：可开启 `web_search` 工具，Agent 会在需要时搜索网络信息并附带引用链接。
### ⚙️ 精细化参数追踪
- **智能尺寸控制**：提供 1K/2K/4K 快速预设，自定义宽高时会自动规整至模型安全范围（16 的倍数、总像素校验等）。
- **实际参数对比**：自动提取 API 响应中真实生效的尺寸、质量、耗时以及**模型改写后的提示词**，与你的请求参数高亮对比。支持定制化的参数列表横向平滑滚动体验。
### 📁 高效历史管理 (纯本地)
- **瀑布流与画廊**：历史任务自动保存，支持按状态过滤、全屏大图预览与快捷下载。
- **多收藏夹管理**：支持创建多个命名收藏夹，同一任务可归入多个收藏夹。提供独立的收藏夹概览视图（展示封面缩略图与任务数量），点击进入具体收藏夹后仍可叠加搜索与状态筛选。收藏夹支持拖拽排序、重命名、设置默认收藏夹，以及按收藏夹为单位批量打包下载 ZIP。
- **失败任务重试**：可在“设置 - 习惯配置”的“重试方式”中选择重试时新建任务，或覆盖失败任务及任何任务；覆盖时保留原任务的创建时间和收藏，耗时从本次重试重新计算。
- **快捷批量操作**：桌面端支持鼠标拖拽框选、Ctrl/⌘ 连选，移动端支持顺滑侧滑多选；轻松实现批量收藏与清理。
- **优化的图片查看与下载**：大图预览支持左右滑动切换、移动端长按弹出操作菜单，支持快捷下载与批量下载。
- **极致性能与隐私**：所有记录与图片均存放在浏览器 IndexedDB 中（采用 SHA-256 去重压缩），不经过任何第三方服务器。支持一键打包导出 ZIP 备份。
### 🔌 多配置与供应商增强
- **多配置管理**：支持创建并保存多个 API 配置（包含供应商、API Key、模型等），按需快速切换；支持一键复制当前配置到列表底部，并通过拖拽对配置列表与供应商列表进行自定义排序。
- **多模型切换**：配置的模型 ID 可用逗号分隔填写多个模型（如 `gpt-image-2.5-sunburst, gpt-image-2`），在首页参数栏的“模型”中切换，选择按配置分别记住；预置配置、URL 传参与导入导出均支持这种写法。
- **多供应商接入**：内置 OpenAI 兼容接口（含 `Images API` 和 `Responses API`）、sub2api（异步）、fal.ai（支持队列），并支持通过 JSON 导入自定义 HTTP 供应商配置（兼容同步/异步任务）。
- **Agent 模式独立 API 配置**：支持为 Agent 模式使用原生（Response API）或混合（Response API + Image API）的独立 API 配置，解决部分供应商/模型不支持 `image_generation` 工具的问题。
- **API 代理**：OpenAI 兼容接口与 fal.ai 均可配置自定义代理。其中 OpenAI 兼容接口可开启同源 `/api-proxy/` 代理，交由 Docker 或本地开发环境转发至真实 API，绕开浏览器 CORS 限制。
- **Codex CLI 兼容模式**：对上游为 Codex CLI 的 API，开启后应用 Codex CLI 实际支持的参数，并将多图生成拆分为并发单图。
- **提示词防改写**：Responses API 会始终在请求文本前加入强制指令防止提示词被改写；开启 Codex CLI 模式后，Images API 也会获得同等保护。
- **智能诊断提示**：当检测到接口异常改写行为或缺少常规参数时，自动提示开启相应的兼容模式。
- **习惯配置**：支持设置提交后清空输入、重启后保留历史输入、临时复用历史任务 API 配置、重试方式、关闭提示词防改写等。
---
## 🚀 部署与使用
支持多种部署与开发方式。
### 预置配置说明
所有部署方式都可以通过环境变量提供“预置配置”——部署端预先加入用户配置列表的 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 格式](#preset-config-json) |
**环境变量一览**
部署时可以通过设置环境变量来控制预置配置和客户端行为。有关 Docker 专属的网络与代理配置（如 `ENABLE_API_PROXY` 等），请参考下方的 [Docker 部署](#docker-deployment) 章节。
| 构建时变量 (Vercel/CF/本地) | Docker 运行变量 | 功能说明 |
|------|------|------|
| `VITE_DEFAULT_API_URL` | `DEFAULT_API_URL` | 设定预置配置值（支持 URL 形式或 JSON 格式，详见 [预置配置 JSON 格式](#preset-config-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`](gpt-image-config.example.json) 模板）。详见 [预置配置说明](#preset-config)。
```dotenv
VITE_DEFAULT_API_URL=https://api.openai.com/v1
```
**初始部署**
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FCookSleep%2Fgpt_image_playground&project-name=gpt-image-playground&repository-name=gpt-image-playground)
点击上方按钮导入仓库即可，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`](gpt-image-config.example.json) 模板）。详见 [预置配置说明](#preset-config)。
```dotenv
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`，支持上述三种填写方式，可直接填写 API 地址或指定配置文件路径（如仓库内的 [`gpt-image-config.example.json`](gpt-image-config.example.json) 模板）。Cloudflare Workers 不会在部署后改写静态文件，因此必须在构建前完成设置。详见 [预置配置说明](#preset-config)。
```dotenv
VITE_DEFAULT_API_URL=https://api.openai.com/v1
```
**部署**
**1. 登录 Cloudflare**
```bash
npx wrangler login
```
**2. 部署到 Workers**
```bash
npm run deploy:cf
```
部署脚本会先执行 `npm run build`，再通过 `wrangler deploy` 上传 `dist/` 目录。
🐳 方式四：Docker 部署
支持通过官方发布的 Docker 镜像在服务器或本地容器环境中快速运行。
**环境变量**
| 变量 | 说明 |
|------|------|
| `DEFAULT_API_URL` | 预置配置，支持上述三种填写方式。若值指向 `.json` 文件或容器内路径，容器启动时自动读取并内嵌到页面。宿主机文件需通过 volume 挂载。详见 [预置配置说明](#preset-config) |
| `ENABLE_API_PROXY=true` | 开启 Nginx 同源代理，请求发往 `/api-proxy/{路径}` 再转发到 `API_PROXY_URL` |
| `API_PROXY_URL` | 代理转发的完整 API 基础地址（不自动补 `/v1`） |
| `LOCK_API_PROXY=true` | 强制锁定代理为开启，用户无法关闭 |
| `HOST` / `PORT` | Nginx 监听地址和端口，默认 `0.0.0.0:80` |
> 开启 API 代理后，任何人都能将你的服务器作为代理来请求目标 API。建议仅在有访问控制（如 IP 白名单）或本地网络中开启。
> 旧版 `API_URL` 已拆分为 `DEFAULT_API_URL` 和 `API_PROXY_URL`，容器启动时自动兼容，无需立即修改。
**隐藏真实 API 地址**
配合 `ENABLE_API_PROXY=true` + `LOCK_API_PROXY=true` 可隐藏上游地址：
- OpenAI 兼容接口：`DEFAULT_API_URL` 留空或填占位地址（如 `https://proxy`）。
- 自定义供应商：JSON 中配置的 `baseUrl` 留空并设置 `apiProxy: true`（仅支持同步配置）。
用户只能看到空值或占位地址，真实地址仅存在于 `API_PROXY_URL`。
**Docker CLI 示例**
```bash
docker run -d -p 8080:80 \
-e DEFAULT_API_URL=https://api.openai.com/v1 \
ghcr.io/cooksleep/gpt_image_playground:latest
```
开启代理并隐藏真实地址：
```bash
docker run -d -p 8080:80 \
-e DEFAULT_API_URL= \
-e API_PROXY_URL=https://real-api.example.com/v1 \
-e ENABLE_API_PROXY=true \
-e LOCK_API_PROXY=true \
ghcr.io/cooksleep/gpt_image_playground:latest
```
挂载本地配置文件：
```bash
docker run -d -p 8080:80 \
-v ./gpt-image-config.json:/config/gpt-image-config.json:ro \
-e DEFAULT_API_URL=/config/gpt-image-config.json \
ghcr.io/cooksleep/gpt_image_playground:latest
```
使用 host 网络加 `--network host`，修改端口用 `-e PORT=28080`。
**Docker Compose 示例**
```yaml
services:
gpt-image-playground:
image: ghcr.io/cooksleep/gpt_image_playground:latest
environment:
- DEFAULT_API_URL=https://api.openai.com/v1
ports:
- "8080:80"
restart: unless-stopped
```
**更新说明：**
使用 `latest` 标签时，重新拉取镜像并重启即可更新（如 `docker compose pull && docker compose up -d`）。若需固定版本可使用官方提供的版本号标签（如 `0.2.x`）。
💻 方式五：本地开发与静态构建
支持在本地通过 Node.js 环境运行开发服务器或构建生产静态文件。
**1. 预置配置（可选）**
在项目根目录新建 `.env.local` 文件，设置 `VITE_DEFAULT_API_URL`，支持上述三种填写方式，可直接填写 API 地址或指定配置文件路径（如仓库内的 [`gpt-image-config.example.json`](gpt-image-config.example.json) 模板）。详见 [预置配置说明](#preset-config)。
开发服务器启动或构建时若值指向远程 `.json` 文件或本地路径，内容会自动内嵌到页面。
```dotenv
VITE_DEFAULT_API_URL=https://api.openai.com/v1
```
**2. 安装依赖并启动**
```bash
npm install
npm run dev
```
**3. 本地开发跨域代理 (可选)**
如果在本地开发时遇到浏览器的 CORS 限制，可开启本地代理转发：
```bash
cp dev-proxy.config.example.json dev-proxy.config.json
```
修改 `dev-proxy.config.json`，将 `target` 设置为真实的完整 API 基础地址。代理不会自动补 `/v1`，OpenAI 兼容接口通常必须填写到版本前缀，如 `https://api.example.com/v1`。重启开发服务器后，在页面设置中开启 **API 代理** 即可（请求将被转发如 `http://localhost:5173/api-proxy/... -> target/...`）。此功能仅在 `npm run dev` 阶段生效，不会影响打包产物。
**4. 本地故障模拟 API (可选)**
如果需要复现图片 URL 跨域、接口返回结构异常、原始响应查看等问题，可启动内置模拟服务：
```powershell
npm run mock:api
```
使用方式见 [本地故障模拟 API](docs/mock-image-api.md)。
**5. 构建静态产物**
```bash
npm run build
```
构建输出的文件位于 `dist/` 目录下，可将其部署至任何静态文件服务器（如普通 Nginx、GitHub Pages、Netlify 等）。
---
## 🛠️ URL 传参快速填充
通过 URL 查询参数快速填入 OpenAI 兼容配置，适合创建书签或集成分享。
| 参数 | 说明 | 示例 |
|------|------|------|
| `apiUrl` | API Base URL | `?apiUrl=https://api.example.com/v1` |
| `apiKey` | API Key | `?apiKey=sk-xxxx` |
| `model` | 模型 ID，多个模型以逗号分隔，可在首页切换 | `?model=gpt-image-2.5-sunburst,gpt-image-2` |
| `imageGenerationModel` | Responses API 的图像生成工具模型，留空使用 API 默认值 | `?imageGenerationModel=gpt-image-2.5-sunburst` |
| `apiMode` | `images` 或 `responses`，默认 `images` | `?apiMode=responses` |
| `profileName` | 配置名称，默认“URL 参数配置” | `?profileName=我的配置` |
| `reasoningEffort` | Responses API 推理强度 | `?reasoningEffort=high` |
| `codexCli` | Codex CLI 兼容模式 | `?codexCli=true` |
| `streamImages` | 流式传输 | `?streamImages=true` |
| `streamPartialImages` | 中间步骤图像数（需配合 streamImages） | `?streamPartialImages=2` |
| `profileId` | 目标配置 ID；匹配到同 ID 配置时直接更新 | `?profileId=my-service` |
| `transparentBackgroundMethod` | 透明背景实现方式：`api`（原生）或 `local`（本地后处理） | `?transparentBackgroundMethod=local` |
集成示例（New API 聊天系统）：
```text
https://gpt-image-playground.cooksleep.dev?apiUrl={address}&apiKey={key}&model={model}
```
```text
https://cooksleep.github.io/gpt_image_playground?apiUrl={address}&apiKey={key}&model={model}
```
## 📋 预置配置 JSON 格式
使用 JSON 文件或分享链接提供预置配置时，JSON 对象支持以下顶层字段：
- **`customProviders`**（可选数组）：自定义供应商定义。只使用内置供应商（OpenAI 兼容、sub2api（异步）或 fal.ai）时可省略。
- **`profiles`**（数组）：预置的 API 配置列表。每项对应用户配置页中的一个配置条目。
- **`agent`**（可选对象）：预置 Agent 的独立 API 模式及文本、图像配置选择，示例见下方。
### 配置列表字段说明（`profiles`）
| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | 定向更新时填写 | 用于标识配置条目：若后续链接携带相同 ID（查询参数 `profileId`、`settings` 链接或预置配置 JSON 中的 `id`），将直接更新该条目而非新建。应用内普通分享链接会省略此字段。 |
| `name` | 是 | 配置名称，方便用户识别。 |
| `description` | 否 | 配置说明，支持 Markdown；填写后会以说明卡片显示在“当前配置”下方。文本可选中和复制，其中的链接可点击。 |
| `provider` | 是 | 供应商类型。`"openai"` 为 OpenAI 兼容接口，`"sb2api-async"` 为 sub2api（异步），`"fal"` 为 fal.ai，其他值引用 `customProviders` 中具有相同 ID 的供应商定义。 |
| `baseUrl` | 是 | API 基础地址（Base URL）。未以 `/` 结尾时遵循 OpenAI 规则自动补齐 `/v1` 前缀；以 `/` 结尾时直接基于该地址请求接口，不补 `/v1`；fal.ai 可留空。 |
| `apiKey` | 否 | API Key。建议省略，让用户导入后自行填写。 |
| `model` | 是 | 模型 ID。多个模型以逗号分隔，默认使用第一个，用户可在首页切换。 |
| `imageGenerationModel` | 否 | Responses API 的 `image_generation` 工具模型，默认 `gpt-image-2.5-sunburst`；也可使用 `gpt-image-2.5-flare`。留空时不发送工具模型 ID，保持 API 默认值。 |
| `apiMode` | 否 | `"images"` 或 `"responses"`，默认 `"images"`。 |
| `isDefault` | 否 | 有多个配置时，为默认项设置 `true`（只能有一个）；只有一个配置时不填。默认项决定首次使用时自动选中的配置；允许拖动排序和删除（受保护策略控制）。 |
| `timeout` | 否 | 请求超时秒数，默认 600。 |
| `apiProxy` | 否 | 是否走部署端 API 代理，默认 `false`。 |
| `transparentBackgroundMethod` | 否 | 透明背景实现方式：`"api"`（API 原生）或 `"local"`（本地后处理）。OpenAI 兼容配置默认 `"api"`，fal.ai 默认 `"local"`，自定义服务商若生成和编辑请求都映射了 `$params.background` 模板变量则默认 `"api"`，否则默认 `"local"`。 |
### 示例：仅 OpenAI 兼容
```json
{
"profiles": [
{
"id": "my-openai",
"name": "我的 OpenAI 配置",
"description": "使用前请阅读 [接口说明](https://example.com/docs)。",
"provider": "openai",
"baseUrl": "https://api.openai.com/v1",
"model": "gpt-image-2.5-sunburst"
}
]
}
```
### 示例：OpenAI 兼容 + sub2api + fal.ai 多配置
```json
{
"profiles": [
{
"id": "openai-main",
"name": "OpenAI",
"provider": "openai",
"baseUrl": "https://api.openai.com/v1",
"model": "gpt-image-2.5-sunburst",
"isDefault": true
},
{
"id": "sub2api-profile",
"name": "sub2api 异步",
"provider": "sb2api-async",
"baseUrl": "https://api.example.com/v1",
"model": "gpt-image-2.5-sunburst"
},
{
"id": "fal-profile",
"name": "fal.ai",
"provider": "fal",
"baseUrl": "",
"model": "openai/gpt-image-2"
}
]
}
```
### 示例：预置 Agent 配置
Agent 可以选择是否使用独立的 API 配置：
- **关闭（`off`）**：沿用当前 API 配置。
- **原生（`native`）**：文本模型通过 Responses API 调用 `image_generation` 工具生成图片。
- **混合（`hybrid`）**：文本模型调用自定义工具，再由图像模型生成图片，适用于文本模型不支持原生图像工具的情况。
在预置 JSON 中添加 `agent`，即可指定默认模式，以及文本和图像模型使用的配置：
```json
{
"profiles": [
{
"id": "default-openai",
"name": "图像配置",
"provider": "openai",
"baseUrl": "https://api.example.com/v1",
"model": "image-model",
"apiMode": "images",
"isDefault": true
},
{
"id": "default-openai-agent",
"name": "文本配置",
"provider": "openai",
"baseUrl": "https://api.example.com/v1",
"model": "text-model",
"apiMode": "responses"
}
],
"agent": {
"apiConfigMode": "hybrid",
"textProfileId": "default-openai-agent",
"imageProfileId": "default-openai"
}
}
```
`textProfileId` 和 `imageProfileId` 引用上方 `profiles` 中的 ID。文本配置须使用 OpenAI 兼容的 Responses API；图像配置可使用任意支持的供应商。`agent` 及其三个字段都可省略。部署更新与锁定遵循上文的预置配置规则。
完整示例见 [`gpt-image-config.agent.example.json`](gpt-image-config.agent.example.json)。
### 如何将预置配置提供给环境变量
预置配置 JSON 可以通过以下三种方式填入部署环境变量（`VITE_DEFAULT_API_URL` 或 Docker 的 `DEFAULT_API_URL`）：
**1. 导入链接（单配置导入，最简单）**
在项目的 [Vercel 在线体验](https://gpt-image-playground.cooksleep.dev) 或 [GitHub Pages 在线体验](https://cooksleep.github.io/gpt_image_playground) 中配置好某个条目后，点击“链接”按钮复制含 `?settings=` 参数的 URL（请勿勾选任何“New API 变量配置”选项），直接填入环境变量即可。
> 💡 **提示**：页面中的“复制导入配置 URL”按钮导出的是**当前选中的单个配置**及其关联的自定义供应商。如需一次性预置包含多个服务商的列表，请使用下方的本地/仓库文件或远程 URL 方式。
```dotenv
VITE_DEFAULT_API_URL=https://你的域名?settings=%7B%22profiles%22%3A%5B...%5D%7D
```
**2. 仓库内／本地配置文件（推荐）**
支持直接指定仓库根目录或本地文件相对路径（如 `./gpt-image-config.example.json` 或 `./config/my-presets.json`），构建时会自动读取并内嵌到静态页面中。
```dotenv
VITE_DEFAULT_API_URL=./gpt-image-config.example.json
```
Docker 需要通过 volume 挂载宿主机文件到容器内路径：
```bash
docker run -d -p 8080:80 \
-v ./gpt-image-config.json:/config/gpt-image-config.json:ro \
-e DEFAULT_API_URL=/config/gpt-image-config.json \
ghcr.io/cooksleep/gpt_image_playground:latest
```
> Docker 环境变量名为 `DEFAULT_API_URL`（不含 `VITE_` 前缀）。
**3. HTTP／HTTPS 远程配置文件**
将 JSON 保存到部署服务器能够访问的 URL（可位于内网，不要求用户浏览器能访问）。构建时或容器启动时会自动读取并内嵌到页面。
```dotenv
VITE_DEFAULT_API_URL=https://example.com/gpt-image-config.json
```
---
## 🔌 自定义供应商
当 API 不是标准 OpenAI 格式时，需要在 `customProviders` 中定义请求和响应结构。每个供应商定义必须有唯一的 `id`，然后由 `profiles` 中配置的 `provider` 字段引用。
若自定义供应商的接口不在 `/v1` 路径下，请将配置中的 `baseUrl` 设置为以 `/` 结尾。例如 `baseUrl` 为 `https://api.example.com/` 且 `submit.path` 为 `api/image-tasks` 时，实际请求地址将为 `https://api.example.com/api/image-tasks`；未以 `/` 结尾时则继续按 OpenAI 规范补齐 `/v1`。
**创建方式：**
1. **在线体验中生成**：打开 [Vercel 在线体验](https://gpt-image-playground.cooksleep.dev) 或 [GitHub Pages 在线体验](https://cooksleep.github.io/gpt_image_playground)，进入 **设置 → API 配置 → 供应商类型 → 创建自定义供应商 → AI 一键生成与导入**，粘贴第三方 API 文档让 AI 生成配置。
2. **应用内导出**：生成完成后，在 **API 配置 → 当前配置** 右侧点击“链接按钮”复制含 `?settings=` 参数的分享 URL，可直接用作环境变量值。
也可以参考 [自定义供应商 LLM 提示词](docs/custom-provider-llm-prompt.md)，将提示词和第三方 API 文档直接发给任意 LLM，手动获取完整 JSON。
**完整 JSON 示例（含异步任务供应商定义）：**
```json
{
"customProviders": [
{
"id": "custom-example-task",
"name": "示例异步任务供应商",
"submit": {
"path": "images/generations",
"method": "POST",
"contentType": "json",
"body": {
"model": "$profile.model",
"prompt": "$prompt",
"size": "$params.size",
"quality": "$params.quality",
"output_format": "$params.output_format",
"output_compression": "$params.output_compression",
"n": "$params.n",
"image_urls": "$inputImages.dataUrls"
},
"taskIdPath": "data.0.task_id"
},
"poll": {
"path": "tasks/{task_id}",
"method": "GET",
"intervalSeconds": 5,
"statusPath": "data.status",
"successValues": ["completed"],
"failureValues": ["failed", "cancelled"],
"errorPath": "data.error.message",
"result": {
"imageUrlPaths": ["data.result.images.*.url.*"],
"b64JsonPaths": []
}
}
}
],
"profiles": [
{
"id": "example-profile",
"name": "示例异步任务供应商",
"provider": "custom-example-task",
"baseUrl": "https://api.example.com/v1",
"model": "gpt-image-2.5-sunburst",
"apiMode": "images"
}
]
}
```
示例中的 `example-profile` 是唯一配置，因此自动成为默认预置配置。若添加更多配置，需要为其中一项设置 `isDefault: true`。
---
## 💻 技术栈
## 📄 许可证 & 致谢
本项目基于 [MIT License](LICENSE) 开源。
特别致谢：[LINUX DO](https://linux.do)
## 💜 赞助支持
如果这个项目对你有帮助，欢迎通过爱发电赞助支持，你的每一份鼓励都是持续更新的动力！
