GPT Image Studio
English · 中文 · 日本語 · 한국어 · Русский
A workbench for OpenAI's gpt-image-2.5 using your own API key. Ask your AI agent for an image in a single sentence, then watch it appear in a local web gallery with its cost and your remaining balance.
Ask your agent, watch it appear:
Features
- Generate from any AI agent. Ask Claude Code, Codex or another agent that can run commands for "a 2K 16:9 image of …". It calls the official API, saves the file locally and tells you what the image cost.
- Live web gallery. While an agent is generating, a "generating…" card with a timer appears on the page, and the result replaces it when it's ready. You can also generate directly from the page.
- All the parameters. gpt-image-2.5 sunburst / flare; 1K / 2K / 4K at any aspect ratio, up to 3840×2160; quality from
low to xhigh / max; up to 16 reference images; mask inpainting.
- Cost tracking. The studio calculates each image's cost from its token usage and shows daily, monthly and lifetime totals. It subtracts subsequent spending from the last balance you synced or entered.
- Gallery tools. Favorites, filters by status (completed / generating / failed), search, one-click reuse of settings, and "use as reference" to keep iterating on a result. Deleted items go to a
.trash folder instead of being erased.
- Use it anywhere. The same page can be hosted on GitHub Pages. On a computer that runs the local service it connects to that service automatically; anywhere else it runs in browser mode, where your key and images stay in that browser.
- Sync your OpenAI balance. Tell your AI “sync my balance” (or “同步余额”). For periodic updates, you can also use the optional browser extension.
- 5 languages. English, 中文, 日本語, 한국어 and Русский. The language follows your browser and can be switched in the page.
- Relay services supported. Works with OpenAI-compatible relays (one-api, new-api …), including image-URL responses, per-image pricing and reading the relay's real balance. See Relay services.
- Zero dependencies. You only need Python 3.9 or later. Nothing to
pip install.
Local outfit and pose libraries
Open Outfits & poses below the prompt box in the local studio. For first-time setup, see Download the libraries.
1. Pick an outfit. Filter for short summer dresses and select SUM-0039 to see the coral dress, woven bag and sandals together. Click Add as reference.
2. Try a different camera angle. These three previews show the same raised-leg pose, P024, from the front, from the side and from above. Add the high-angle view as image 2.
3. Tell the AI how to use each image. The composer numbers references as you add them. Here image 1 supplies the outfit and image 2 supplies the pose and camera angle for a 9:16 street-style photo.
The outfit and pose artwork in these screenshots is credited to @giaaibusi.
Download the libraries
New in v0.5.0. The first time you open the local workbench, a banner offers 1,407 outfits and 288 pose groups with 1,439 angle images. After the download choice has been visible for 20 seconds, the studio starts fetching the missing libraries from their upstream GitHub repositories. Both together take about 820 MB to download. Allow 1.7 GB of free space during setup.
- Choose Skip download to save that choice, or Stop download while it runs. To install later, open Outfits & poses → Download now. Retry keeps completed libraries and fetches the unfinished library again.
- The default folder is
~/Pictures/gpt-image-libraries. Set GPT_IMAGE_LIBRARY_DIR before startup to choose another drive, or GPT_IMAGE_AUTO_DOWNLOAD=0 to skip automatic downloads in advance. A standalone GitHub Pages session uses browser mode. To install libraries, launch the local service.
- In the composer, choose an outfit, or a pose and camera angle, then Add as reference. References are numbered in attachment order, including your own uploads. Browsing uses local files. Generating sends the selected originals to your configured image API.
- Already have classified files? Create
reference-libraries.local.json next to config.json, with outfits.root and/or poses.root. Configured libraries take precedence. Outfits use category/subcategory/ID.webp. Poses use type/category/pose group/angle_ID.png. The optional thumbnails folder mirrors those paths using WebP for outfits and JPG for poses. Configuration example.
Each download comes from a pinned upstream revision, is checked before installation and keeps its source license. The studio's MIT license covers the studio code. The outfit source sets separate terms for repackaging the images. The pose source designates its images and original data for non-commercial use only and credits @giaaibusi. Outfit source and asset terms · Pose source and terms.
Install
As a Claude Code skill (recommended)
git clone https://github.com/konglingbukong/gpt-image-studio ~/.claude/skills/gpt-image
- Run
start.bat (Windows) or sh start.sh (macOS / Linux). Your browser opens http://127.0.0.1:8765.
- Go to Settings → API, enter your OpenAI API key, and click "Test connection" (free).
- Ask Claude Code for an image.
You can also provide the key through the OPENAI_API_KEY environment variable, or in config.json (see config.example.json; config.json is git-ignored).
Just the web page (nothing to install)
Open https://konglingbukong.github.io/gpt-image-studio/ and enter your key in Settings. The page runs in browser mode: your key and images stay in your browser, and the browser talks to OpenAI directly with no third-party server in between.
Other agents (Codex, Cursor, Gemini, Antigravity, WorkBuddy …)
Pick whichever of these your agent supports:
① MCP (supported by most agents). Register scripts/mcp_server.py to enable generate_image, check_connection, get_spending and sync_balance. Replace <path> with the folder you cloned:
- Claude Code:
claude mcp add gpt-image -- python <path>/scripts/mcp_server.py
- Codex (
~/.codex/config.toml):
[mcp_servers.gpt-image]
command = "python"
args = ["<path>/scripts/mcp_server.py"]
- Cursor / Gemini CLI / other JSON-configured clients (
mcpServers):
{ "mcpServers": { "gpt-image": { "command": "python", "args": ["<path>/scripts/mcp_server.py"] } } }
Try it. Set your OpenAI project key in the studio and sign in to the API dashboard in a browser your AI can access, such as Edge or Chrome. Tell the AI “sync my balance”. It reads API credit balance for the selected organization, verifies the organization against your key and reports the USD amount and time. If your browser asks for permission or sign-in, complete that prompt in the browser. Open the official billing page.
The sync runs when you ask. It works with the local workbench closed and appears the next time you open it. Between syncs, the workbench subtracts spending from the last recorded amount. Use an MCP client with access to your signed-in browser for this workflow. After updating an existing installation, reconnect the MCP server once to load the new tool.
② Skill folder. Agents that support the SKILL.md format (Codex, WorkBuddy …) can use this folder as a skill: drop it into their skills directory.
③ Instructions file. Any other agent that can run shell commands can follow AGENTS.md.
Whichever route you choose, images land in the same folder and show up live in the web workbench.
Verified: Claude Code, Codex (including the ChatGPT desktop app), WorkBuddy, Antigravity and DeepSeek Harness (dsh). The full list, per-agent setup notes, interface contracts and the steps for adding a new agent are in docs/INTEGRATIONS.md. If your agent isn't supported yet, open an "Integration request" issue, or wire it up yourself following CONTRIBUTING.md and send a PR.
Relay services (OpenAI-compatible proxies)
Many people reach gpt-image through a relay / proxy service instead of OpenAI directly (one-api, new-api and similar). These work too:
- Setup: put the relay's address in Settings → API → API URL (usually ending in
/v1) and the relay's key in API Key. If the relay names the model differently (e.g. gpt-image-2.5), type that name in the model menu.
- Image URLs: relays that return an image link instead of base64 data are handled; the image is downloaded and saved like any other.
- Strict relays: if a relay rejects official-only parameters (
moderation, output_format, background), turn on Send basic parameters only. The error message suggests this when it happens.
- Per-image pricing: most relays bill per image. Set Pricing → Per-image price and costs are calculated from it instead of tokens.
- Real balance: if the relay supports the one-api / new-api billing endpoints, the actual remaining credit is read from the relay automatically, with no calibration needed.
- Connection test: works with relays that only implement
GET /models.
Command-line equivalents in config.json: "api_url", "api_key", "model", "minimal_params": true, "rates": {"per_image": 0.04}, "balance_source": "auto" | "relay" | "manual".
Command line
python scripts/gen.py --prompt-file prompt.txt --size "2K 16:9" --quality high --name cover
python scripts/gen.py --prompt "an orange cat" --size 1024x1024 --quality low
python scripts/gen.py --prompt-file p.txt --ref face.png --ref outfit.png --size "4K 9:16"
python scripts/gen.py --check # test key + network, free
python scripts/gen.py ... --json # one JSON line, for scripts and integrations
All parameters are documented in SKILL.md. Command-line messages are in English by default; set "lang": "zh" in config.json for Chinese.
Personal preferences
Create rules.local.md in the skill folder and write down your own preferences, such as default specs and prompt habits. Agents read it before generating. It is git-ignored.
Security
- The local service listens on
127.0.0.1 only and checks both Host and Origin. It accepts requests only from the local page and from the sites listed in allowed_origins in config.json, so other web pages can't use it to spend your money.
- Your key is only ever sent to the API URL you configure (OpenAI by default).
Pricing note
Costs are calculated from the rates in config.json, in USD per 1M tokens. The defaults are gpt-image-2.5 prices at the time of writing: text input 5, image input 8, image output 30. If OpenAI changes its prices, update them under Settings → Pricing. The balance shown is an estimate; your OpenAI dashboard is the source of truth.
Credits
The UI layout is inspired by CookSleep/gpt_image_playground (MIT). The code was written independently.
License
The studio code is licensed under MIT. Downloaded images retain their upstream asset terms.
