GPT Image Playground: a local-first workbench for the gpt-image-2.5 API

What GPT Image Playground is for

The gpt-image-2.5 API is a request-response endpoint. You send a prompt, optionally reference images and a mask, and you get back an image. Everything around that call, such as keeping track of which prompt produced which file, reusing a good result as the next reference image, or masking out one region and regenerating it, is left to you. GPT Image Playground fills that gap with a browser UI. It targets people who generate images by hand and want a workspace rather than a script: designers iterating on a single asset, developers comparing parameter settings, anyone who needs to keep a visual history of prompts and outputs.

The project is a Vite and React 19 single-page application written in TypeScript, licensed MIT. It is not a wrapper library and not a CLI. There is no server component in the repository layout; the deploy directory, vercel.json and wrangler.jsonc exist to ship static files, not to run a backend. That choice decides almost everything else about how the tool behaves.

How the provider layer and the generation flow fit together

The README lists four ways to reach a model: OpenAI itself, an OpenAI-compatible endpoint, sub2api in asynchronous mode, fal.ai, and a custom HTTP provider you import. Each API configuration is stored separately, and the README states that transparency handling is chosen per configuration on the API configuration page. So the provider is not a global setting; it is a profile you select when you generate.

Generation happens in one of two API modes, Images API or Responses API, and the README says both support streaming intermediate step images to work around connection timeouts. The Responses API path is what the Agent mode uses. There, the model can call an image tool across turns, reference earlier images with an @ mention, and call a generate_image_batch tool to produce several related images inside one turn, with continue_generation appending a further turn when outputs depend on each other. Editing an earlier message creates a branch, and the README notes that reference resolution is confined to the current branch path so images from a discarded branch are not pulled in.

State lives in the browser. History, favourites and image bytes go into IndexedDB, with SHA-256 deduplication and compression applied to stored images. Nothing is proxied through a third-party server. The trade-off is that the browser tab is the database: clearing site data removes your history, and the same gallery is not visible from a second machine.

Installing GPT Image Playground and running a first generation

The README excerpt does not carry an install section, but the package.json scripts define the workflow. Clone the repository, install dependencies, and start the Vite dev server. The dev script is plain vite, so the default port is Vite's, and the README does not document overriding it.

npm install
npm run dev

If you want to develop without spending API credits, the repository ships a mock server script. It is listed in package.json and the script file is scripts/mock-image-api.mjs.

npm run mock:api

The repository also contains gpt-image-config.example.json at the top level, which is the shape a configuration file takes if you want to import provider settings rather than type them into the UI. The README does not spell out the import steps, so treat the example file as the reference for field names.

For a production build, the build script runs the TypeScript compiler in build mode and then Vite, and deploy:cf builds and pushes with Wrangler. vercel.json is present, so a Vercel deploy is also part of the intended path.

npm run build
npm run deploy:cf

After the app loads, the first real task is adding a provider on the API configuration page: pick OpenAI or an OpenAI-compatible base URL, paste the key, and choose the transparency mode for that profile. Then generate one image at the 1K preset. The README describes an actual parameters panel that extracts the size, quality, elapsed time and the model's rewritten prompt from the API response and highlights them against what you requested. That panel is the first thing to check, because it tells you whether your provider honoured the request or quietly substituted defaults.

The transparency feature has two modes and neither is free

Transparency is the most interesting design decision in the project and the one most likely to disappoint. The README describes two implementations, selectable per API configuration. In native mode the app asks the model to return an alpha channel, which requires the endpoint and model to support it; the README explicitly notes that fal.ai has no corresponding parameter. In local post-processing mode the app instructs the model to use a pure green or pure magenta background and then removes that colour in the browser, saving the result as PNG or WebP.

The README is candid about where the local path breaks: complex hair edges, semi-transparent materials, strong reflections, or a subject colour close to the background colour can leave fringes or punch holes in the wrong place. That is a chroma-key limitation, not a bug, and it means the feature is suited to icons, stickers and single-subject assets rather than cut-out portraits. When native mode fails, the README says the app prompts you to switch to local post-processing. It does not document an automatic fallback.

Where a browser-only image tool stops being the right choice

The local-first design is a privacy feature and a scaling limit at the same time. Because images and history live in IndexedDB, there is no shared team gallery, no server-side job queue, and no way to resume a batch from another device. A long batch run is tied to the tab that started it.

Cost control is the other gap. The README describes batch generation and Agent-driven concurrent generation through generate_image_batch, but nothing in the documentation describes a spend cap, a per-run token or image budget, or a dry-run mode. Every image the model returns is billed by your provider. The mock server exists for development, which is the right way to test prompts without paying, but it is a development tool rather than a guardrail.

Finally, the non-HTTPS constraint is easy to miss. The README warns that the Vercel-hosted demo is bound to a .dev domain, and because of browser security policy that deployment generally requires the API endpoint to be HTTPS. If your image endpoint is plain HTTP on a LAN address, the README points you at the GitHub Pages build or a self-hosted deployment instead. That is a deployment topology decision, not a setting you can flip.

How it compares with calling the API from code

The obvious alternative is a short script against the OpenAI SDK. That approach gives you exact control over retries, concurrency, storage paths and cost accounting, and it fits a pipeline that runs unattended. What it does not give you is a mask editor, a gallery, branch-aware conversation context, or a side-by-side view of requested versus actual parameters. GPT Image Playground's value is concentrated in interactive iteration: upload reference images, mask a region, generate, promote a result to the next reference, repeat.

A second alternative is a hosted image product with its own model. Those bundle billing, storage and sharing, which is exactly what this project leaves to you and your provider. The difference is architectural: GPT Image Playground keeps the model swappable through the provider layer and keeps your data in the browser, at the cost of operating it yourself. If you want an account, a team workspace and a support contract, this repository is the wrong shape.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and its last push was on 2026-09-09, with v0.7.12 tagged the same day and v0.7.11 and v0.7.10 earlier that day. Three releases in one day suggests a fast patch cadence around a 0.7.x line rather than a settled API. Nothing in the release history describes a migration guide, a changelog beyond the release list, or a deprecation policy, so treat configuration stored in the browser as something you may need to re-enter after a large upgrade.

The dependency list is a real upgrade surface: React 19, Vite 6, Tailwind 3, Zustand 5, the fal.ai client, and a Markdown rendering stack that includes streamdown, react-markdown, remark-gfm and katex. The package.json overrides pin mdast-util-gfm-autolink-literal to 2.0.0 and dompurify to ^3.4.7, which is the kind of pin that usually indicates a transitive conflict worth re-checking on each dependency bump.

The licence is MIT, which permits commercial use and modification. The README also carries sponsor links and affiliate registration links for several API relay services. Those are third-party commercial relationships; the MIT licence covers the code, and the sponsor arrangements do not change what your chosen provider charges you or what it does with your prompts. If you deploy this inside a company, the API keys you paste into the browser are the thing to govern, not the licence.

Editorial conclusion

Adopt GPT Image Playground if you already hold an OpenAI or compatible key and want masks, batch runs and a local gallery without building a UI. Skip it if you need a server-side pipeline, team-shared history, or a provider whose transparency parameters it does not send. Before trusting it with real work, open the API configuration page, add one provider, run a single 1K generation, and confirm that the actual parameters panel echoes back the size and quality you asked for.

Frequently asked questions

Official sources

1. CookSleep/gpt_image_playground on GitHub
2. License: MIT
3. Project website
4. README
5. Releases