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 cost of every image is calculated from the token usage OpenAI actually returns. Spending is totalled for today, this month and overall. Calibrate your balance once and the remaining amount is tracked for you (OpenAI has no balance API, so this is the most accurate method available).

• 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.

• 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.

Related MCP server: mcp-server-openai-image-generator

Install

As a Claude Code skill (recommended)

git clone https://github.com/konglingbukong/gpt-image-studio ~/.claude/skills/gpt-image

1. Run start.bat (Windows) or sh start.sh (macOS / Linux). Your browser opens http://127.0.0.1:8765.

2. Go to Settings → API, enter your OpenAI API key, and click "Test connection" (free).

3. 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 as an MCP server. Your agent gets three tools: generate_image, check_connection and get_spending. 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"] } } }

② 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

MIT