# GPT Image Studio

**English** · [中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Русский](README.ru.md)

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

![GPT Image Studio — gallery](docs/screenshot.png)

*Ask your agent, watch it appear:*

![An AI agent generating an image while the web gallery shows it live](docs/agent-sync.png)

## 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](extension/README.md).
- **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](#relay-services-openai-compatible-proxies).
- **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](#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**.

![Summer dress grid with the coral outfit SUM-0039 selected and its accessories visible in the preview](docs/library-outfits-en.webp)

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

![Three captures of pose P024 with the front, side and high-angle buttons selected in turn](docs/library-pose-angles-en.webp)

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

![Two numbered references in the composer with a prompt combining the coral dress and the high-angle pose](docs/library-composer-en.webp)

*The outfit and pose artwork in these screenshots is credited to [@giaaibusi](https://x.com/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](README.zh-CN.md#本地服装与姿势图库).

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](https://x.com/giaaibusi). [Outfit source and asset terms](https://github.com/paipiange/nvzhuang/blob/f13741ebc09c73a63b92f626a115a1bb74ed779f/docs/LICENSE-DECISION.md) · [Pose source and terms](https://github.com/paipiange/ai-pose-gallery-zh/blob/0596708b11fe7ce874ac519e4f2538c92918b07f/LICENSE).

## Install

### As a Claude Code skill (recommended)

```bash
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` 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`):
  ```toml
  [mcp_servers.gpt-image]
  command = "python"
  args = ["<path>/scripts/mcp_server.py"]
  ```
- **Cursor / Gemini CLI / other JSON-configured clients** (`mcpServers`):
  ```json
  { "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](https://platform.openai.com/settings/organization/billing/overview).

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](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](docs/INTEGRATIONS.md)**. If your agent isn't supported yet, open an "Integration request" issue, or wire it up yourself following [CONTRIBUTING.md](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

```bash
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](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](https://github.com/CookSleep/gpt_image_playground) (MIT). The code was written independently.

## License

The studio code is licensed under [MIT](LICENSE). Downloaded images retain their [upstream asset terms](#local-outfit-and-pose-libraries).