feat: support reference images via /images/edits

AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Bun + TypeScript single-file server that exposes an OpenAI-compatible image
+generation endpoint and serves a small vanilla HTML/JS playground.
+
+## Runtime
+
+- Bun, not Node. See `CLAUDE.md` for the full Bun-vs-Node cheatsheet
+  (prefer `Bun.serve`, `Bun.file`, `bun:test`, `Bun.sql`, etc.). Do not add
+  `dotenv` — Bun loads `.env` automatically.
+- Bun version baseline: `1.3.13` (per `README.md`).
+
+## Commands
+
+- Install: `bun install`
+- Dev (HMR): `bun run dev` → `bun --hot ./index.ts`
+- Start: `bun run start` → `bun ./index.ts`
+- Typecheck: no script defined. Use `bunx tsc --noEmit` (tsconfig already sets
+  `noEmit: true`, so plain `bunx tsc` works too).
+- Tests / lint / formatter: none configured. If adding tests, use `bun test`.
+
+The server binds `0.0.0.0` (see `index.ts:6`), so it is reachable from other
+hosts on the network when running locally — be mindful when entering API keys.
+
+## Architecture
+
+- `index.ts` — the entire backend. One `Bun.serve` instance with:
+  - `/` serves `index.html` via Bun's HTML import (`import index from "./index.html"`).
+  - `POST /api/generate` accepts `{ baseURL, apiKey, model, prompt, size }`,
+    builds an OpenAI-compatible provider with `@ai-sdk/openai-compatible`, and
+    calls `generateImage` from `ai`. Images come back as base64 and are
+    returned as `data:` URLs in `{ images: string[] }`.
+- `index.html` — self-contained UI: inline CSS, plain DOM JS, no build step.
+  Settings (baseURL, apiKey, model, size, prompt) persist in `localStorage`
+  under the `aip:<field>` prefix. There is no React code despite
+  `react` / `react-dom` / `@types/react*` being in `package.json` — treat
+  those deps as latent. Do not invent a React frontend unless asked.
+- No router, no DB, no auth. API key is supplied per-request by the browser
+  and never stored server-side.
+
+## TypeScript conventions
+
+`tsconfig.json` is strict with bundler-mode resolution:
+- `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`,
+  `noFallthroughCasesInSwitch` are on — array/object index access is
+  `T | undefined` and must be narrowed.
+- `verbatimModuleSyntax` + `moduleDetection: "force"` — use `import type` for
+  type-only imports; every file is a module.
+- `allowImportingTsExtensions` is on; `.ts` extensions in imports are fine.
+- `jsx: "react-jsx"` is set but unused (see frontend note above).
+
+## When extending the API
+
+- Add new routes inside the `routes` object in `index.ts`; keep the
+  `{ POST: async (req) => … }` shape used by `/api/generate`.
+- Return JSON with `Response.json(...)`. Validate the request body shape
+  explicitly — the existing handler asserts required fields and returns 400
+  before calling the model.
+- The AI SDK image type is loose; the current handler casts to
+  `{ mediaType?: string; base64?: string }`. Mirror that pattern rather than
+  trusting field presence.

index.html

@@ -113,6 +113,59 @@
 			.status.error {
 				color: var(--danger);
 			}
+			.ref-preview {
+				display: flex;
+				flex-wrap: wrap;
+				gap: 8px;
+				margin-top: 8px;
+			}
+			.ref-preview:empty {
+				display: none;
+			}
+			.ref-preview .thumb {
+				position: relative;
+				width: 64px;
+				height: 64px;
+				border-radius: 8px;
+				overflow: hidden;
+				border: 1px solid var(--border);
+			}
+			.ref-preview .thumb img {
+				width: 100%;
+				height: 100%;
+				object-fit: cover;
+				display: block;
+			}
+			.ref-preview .thumb .remove {
+				position: absolute;
+				top: 2px;
+				right: 2px;
+				width: 18px;
+				height: 18px;
+				padding: 0;
+				border: 0;
+				border-radius: 50%;
+				background: rgba(0, 0, 0, 0.7);
+				color: white;
+				font-size: 12px;
+				line-height: 18px;
+				cursor: pointer;
+				font-weight: bold;
+			}
+			.hint {
+				display: block;
+				margin-top: 6px;
+				color: var(--muted);
+				font-size: 12px;
+			}
+			.hint code {
+				background: rgba(255, 255, 255, 0.06);
+				padding: 1px 4px;
+				border-radius: 4px;
+			}
+			input[type="file"] {
+				padding: 8px;
+			}
 			.result {
 				margin-top: 24px;
 				display: grid;
@@ -158,16 +211,14 @@
 					</div>
 					<div class="row">
 						<label for="model">Model</label>
-						<input id="model" type="text" placeholder="dall-e-3 / gpt-image-1 / flux-..." />
+						<input id="model" type="text" placeholder="gpt-image-2" />
 					</div>
 					<div class="row">
 						<label for="size">Size</label>
 						<select id="size">
-							<option value="1024x1024">1024x1024</option>
+							<option value="1024x1024">1024x1024 (square)</option>
-							<option value="512x512">512x512</option>
+							<option value="1536x1024">1536x1024 (landscape)</option>
-							<option value="768x768">768x768</option>
+							<option value="1024x1536">1024x1536 (portrait)</option>
-							<option value="1024x1792">1024x1792 (portrait)</option>
-							<option value="1792x1024">1792x1024 (landscape)</option>
 						</select>
 					</div>
 				</div>
@@ -178,6 +229,15 @@
 						placeholder="A futuristic cityscape at sunset, cinematic lighting"
 					></textarea>
 				</div>
+				<div class="row">
+					<label for="refImages">Reference images (optional)</label>
+					<input id="refImages" type="file" accept="image/*" multiple />
+					<div id="refPreview" class="ref-preview"></div>
+					<small class="hint">
+						Provide one or more references to keep style consistent. When set,
+						the request is sent to <code>/v1/images/edits</code> (gpt-image series only).
+					</small>
+				</div>
 				<div class="actions">
 					<button id="generate">Generate</button>
 					<span id="status" class="status"></span>
@@ -207,6 +267,49 @@
 				});
 			}
 
+			const refImages = [];
+
+			function renderRefPreview() {
+				const c = $("refPreview");
+				c.innerHTML = "";
+				refImages.forEach((src, i) => {
+					const thumb = document.createElement("div");
+					thumb.className = "thumb";
+					const img = document.createElement("img");
+					img.src = src;
+					img.alt = "reference " + (i + 1);
+					const btn = document.createElement("button");
+					btn.type = "button";
+					btn.className = "remove";
+					btn.textContent = "\u00d7";
+					btn.title = "Remove";
+					btn.onclick = () => {
+						refImages.splice(i, 1);
+						renderRefPreview();
+					};
+					thumb.appendChild(img);
+					thumb.appendChild(btn);
+					c.appendChild(thumb);
+				});
+			}
+
+			$("refImages").addEventListener("change", async (e) => {
+				const input = e.target;
+				const files = Array.from(input.files || []);
+				for (const file of files) {
+					if (!file.type.startsWith("image/")) continue;
+					const dataUrl = await new Promise((resolve, reject) => {
+						const r = new FileReader();
+						r.onload = () => resolve(r.result);
+						r.onerror = () => reject(r.error);
+						r.readAsDataURL(file);
+					});
+					refImages.push(dataUrl);
+				}
+				renderRefPreview();
+				input.value = "";
+			});
+
 			$("generate").addEventListener("click", async () => {
 				const btn = $("generate");
 				const status = $("status");
@@ -218,6 +321,7 @@
 					model: $("model").value.trim(),
 					size: $("size").value,
 					prompt: $("prompt").value.trim(),
+					referenceImages: refImages,
 				};
 
 				if (!body.baseURL || !body.apiKey || !body.model || !body.prompt) {

index.ts

@@ -2,6 +2,61 @@ import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { generateImage } from "ai";
 import index from "./index.html";
 
+type Size = `${number}x${number}`;
+
+async function generateWithReference({
+	baseURL,
+	apiKey,
+	model,
+	prompt,
+	size,
+	referenceImages,
+}: {
+	baseURL: string;
+	apiKey: string;
+	model: string;
+	prompt: string;
+	size: Size;
+	referenceImages: string[];
+}): Promise<string[]> {
+	const form = new FormData();
+	form.append("model", model);
+	form.append("prompt", prompt);
+	form.append("size", size);
+
+	for (let i = 0; i < referenceImages.length; i++) {
+		const dataUrl = referenceImages[i];
+		if (!dataUrl) continue;
+		const match = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
+		if (!match) continue;
+		const mime = match[1]!;
+		const b64 = match[2]!;
+		const bytes = Buffer.from(b64, "base64");
+		const ext = mime.split("/")[1] ?? "png";
+		form.append("image", new Blob([bytes], { type: mime }), `ref-${i}.${ext}`);
+	}
+
+	const url = `${baseURL.replace(/\/+$/, "")}/images/edits`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${apiKey}` },
+		body: form,
+	});
+
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`Upstream ${res.status}: ${text || res.statusText}`);
+	}
+
+	const data = (await res.json()) as {
+		data?: Array<{ b64_json?: string }>;
+	};
+
+	return (data.data ?? [])
+		.map((item) => (item.b64_json ? `data:image/png;base64,${item.b64_json}` : null))
+		.filter((s): s is string => s !== null);
+}
+
 const server = Bun.serve({
 	hostname: "0.0.0.0",
 	routes: {
@@ -9,13 +64,15 @@ const server = Bun.serve({
 		"/api/generate": {
 			POST: async (req) => {
 				try {
-					const { baseURL, apiKey, model, prompt, size } = (await req.json()) as {
+					const { baseURL, apiKey, model, prompt, size, referenceImages } =
-						baseURL?: string;
+						(await req.json()) as {
-						apiKey?: string;
+							baseURL?: string;
-						model?: string;
+							apiKey?: string;
-						prompt?: string;
+							model?: string;
-						size?: `${number}x${number}`;
+							prompt?: string;
-					};
+							size?: Size;
+							referenceImages?: string[];
+						};
 
 					if (!baseURL || !apiKey || !model || !prompt) {
 						return Response.json(
@@ -24,6 +81,18 @@ const server = Bun.serve({
 						);
 					}
 
+					if (Array.isArray(referenceImages) && referenceImages.length > 0) {
+						const images = await generateWithReference({
+							baseURL,
+							apiKey,
+							model,
+							prompt,
+							size: size ?? "1024x1024",
+							referenceImages,
+						});
+						return Response.json({ images });
+					}
+
 					const provider = createOpenAICompatible({
 						name: "custom",
 						apiKey,