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

What GPT Image Playground actually is

The README describes the project as an image generation and editing tool built on the OpenAI gpt-image-2.5 API, and the repository confirms the shape of it: a Vite and React 19 single-page application written in TypeScript, with Tailwind for styling and Zustand for state. There is no server component in package.json. The scripts are dev, build, preview, test, and deploy:cf, and the only backend-ish dependency is wrangler for Cloudflare deployment.

That matters for who this is for. If you want a hosted image service you sign into, this is not it. If you want a browser tab that talks directly to an image API with your own key, keeps a searchable history, and gives you a mask editor without writing one, the project targets exactly that. The homepage at gpt-image-playground.cooksleep.dev and a GitHub Pages build are both offered as demos, and the README is explicit that the Vercel-hosted demo is bound to a .dev domain, which normally requires HTTPS for any endpoint it calls.

The provider list is broader than the OpenAI-only framing suggests. The README names OpenAI and OpenAI-compatible endpoints, sub2api in asynchronous mode, fal.ai, and custom HTTP providers that can be imported. So the tool is really an API-agnostic front end whose default assumptions come from the OpenAI image API.

How requests, images and history move through the app

The data flow is browser to provider, with the browser as the only store. According to the README, all records and images live in IndexedDB, deduplicated with SHA-256 compression, and never pass through a third-party server. That is a real architectural commitment, not a marketing line: it means the app has no account system, no sync, and no server-side copy of your generations.

Generation has two modes. The Images API mode and the Responses API mode both support streaming intermediate step images, which the README frames as a way to reduce connection timeouts on long jobs. The Agent mode sits on the Responses API and is conversational: it keeps context across turns, can call image tools, and accepts @ references to earlier reference images or previously generated images. There is a generate_image_batch tool for concurrent generation within one turn, and a continue_generation mechanism that appends a new turn to handle dependencies between images. Edits and regenerations produce switchable branches, and reference resolution is scoped to the current branch path so an image from a sibling branch is not silently picked up.

Parameter handling is more careful than most thin API wrappers. The README says the app extracts the dimensions, quality, latency and the model-rewritten prompt from the API response and highlights them against what you requested. That comparison is the most useful thing here for anyone tuning prompts, because the prompt the model actually used is usually not the prompt you typed.

Transparency has two implementations, chosen per API configuration. The API-native path asks the model for an alpha channel and depends on the endpoint and model supporting it; the README notes fal.ai has no corresponding parameter. The local post-processing path instead instructs the model to use a solid green or magenta background and removes that colour in the browser before saving as PNG or WebP.

Installing GPT Image Playground and generating your first image

The repository has no published install instructions beyond the standard npm scripts, so a local run follows the usual Vite flow. Install dependencies, then start the dev server:

npm install
npm run dev

Vite prints a local URL, typically on port 5173. Open it, then go to the API configuration page and enter your key and base URL. The repository ships gpt-image-config.example.json at the top level as a template, and dev-proxy.config.example.json for proxy setups, so if you plan to point the app at a non-OpenAI endpoint, start from those files rather than guessing at the schema.

For a production build and a Cloudflare deploy, the package defines two scripts:

npm run build
npm run deploy:cf

The build runs tsc -b before vite build, so a type error fails the build rather than shipping. If you only want to check the built output locally, npm run preview serves it.

There is also a mock API for working without spending credits:

npm run mock:api

That runs scripts/mock-image-api.mjs. Point the app's base URL at the mock server to exercise the UI, history and gallery without a real key. It is the fastest way to confirm the app works on your machine before you debug a provider problem. Tests run through vitest with npm test.

Where GPT Image Playground stops being the right tool

The local-only storage model is the biggest constraint. Because everything lives in IndexedDB, clearing site data, switching browsers, or moving to another machine means starting over. There is no export of the whole library described in the README, though favourites can be batch-downloaded as ZIP. If your team needs shared history or an audit trail, this design is working against you.

Long-running jobs are another weak point. Streaming previews exist specifically to mitigate connection timeouts, which tells you the app holds the request open in the browser. Close the tab and the generation is gone; there is no server-side queue to resume it. For batch work measured in hundreds of images, an asynchronous API with job IDs and callbacks is a better fit than a browser client, and the README's own mention of sub2api in asynchronous mode suggests the author knows this boundary.

The local transparency post-processing has a documented failure mode worth reading twice. The README states that subjects with complex hair edges, semi-transparent materials, strong reflections, or colours close to the background can leave edge residue or be cut incorrectly. That rules it out for anything needing clean alpha on fine detail. The native mode avoids the problem but depends on your endpoint supporting it, and the README says the app will prompt you to switch to local processing if the API returns an unsupported-transparency error.

Finally, the HTTPS constraint is easy to trip over. The README warns that the Vercel demo's .dev domain generally requires HTTPS endpoints, so internal or local HTTP APIs need the GitHub Pages build or your own deployment.

How it differs from calling the API directly or using fal.ai's client

The obvious alternative is writing a script against the OpenAI images endpoint yourself. You would get full control and no UI to maintain, and for a fixed pipeline that is the right call. What you give up is the mask editor, which the README says preprocesses uploads to satisfy the official resolution limits, and the reference-image workflow that lets you promote a result into the next round with one click. Those are the parts that are tedious to rebuild.

A second comparison is the fal.ai client. The repository depends on @fal-ai/client directly, so fal.ai is not an alternative here so much as another provider the same UI can drive. The meaningful difference is that fal.ai has no transparency parameter in this integration, per the README, so if alpha output matters, the provider choice changes what the app can do.

Against a general-purpose playground product, the distinction is where state lives. A hosted playground keeps your generations on its servers and gives you an account, sharing, and cross-device access. GPT Image Playground keeps them in your browser and gives you nothing to sign into. Pick based on whether you want the data to outlive the browser profile.

Licence, maintenance and the cost of upgrading

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication from the repository; anything about your provider's terms of service for generated images is a separate question the project does not address.

Maintenance looks current rather than dormant. The last push was on 2026-09-09, and v0.7.12 was released the same day, following v0.7.11 and v0.7.10 within hours of each other. Three releases in one day suggests active iteration, and the version numbers sit in the 0.7.x range, so breaking changes between minor versions are plausible.

Upgrade cost is mostly the usual front-end kind. There is no migration system for IndexedDB, and the README does not document rollback or schema versioning, so a release that changes the stored record shape is a risk you carry without a stated recovery path. The dependency set includes React 19, Vite 6, Zustand 5 and Tailwind 3, plus an overrides block pinning dompurify and mdast-util-gfm-autolink-literal, which hints at transitive dependency friction the maintainer has already had to manage. Budget for reading release notes before pulling a new minor version, and export anything you cannot afford to lose.

Editorial conclusion

Adopt it if you already hold an OpenAI or OpenAI-compatible key, want mask and reference-image editing in a browser, and are comfortable with history living in IndexedDB on one machine. Skip it if you need server-side job queues, multi-user accounts, or a hosted backend that survives a cleared browser profile. Before committing, verify three things against your own provider: that it accepts the base URL you plan to use, that it supports transparency if you want the API-native mode, and whether your deployment domain is HTTPS, because a Vercel .dev host will reject plain HTTP endpoints.

Frequently asked questions

Official sources

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