0 · Local testing
A local-only test backend is included. Follow SETUP.md to add a Vercel AI Gateway key to .env.local, start the server and visit http://127.0.0.1:8000. Never put a key in this page. The local backend keeps photos, jobs and limits in memory only; restarting removes them and resets the allowance. It is not safe for public deployment.
Each day/night pair attempts two paid image edits; retries can also cost money. Image editing and output quality need verification with a real test. The sections below describe a proposed production build, not guarantees of the local test server.
Accuracy limits: this page does not detect rooflines or verify architectural preservation. Generated results must be inspected; exact geometry and lighting coverage cannot be guaranteed by a prompt alone.
1 · What this one file does
Responsive HTML, CSS, and JavaScript; no CDN, fonts, libraries, or build step. Includes validated uploads, metadata removal, original preview, palette selection, anonymous-quota display, event-driven estimated progress, job recovery, two result cards, comparison slider, and downloads. The house artwork is an illustration, not a generated sample.
Real AI and trustworthy limits require a backend. This file deliberately contains no API key, fake quota, invented AI output, or localStorage-based security. Opening it directly previews the interface; host it over HTTPS with the backend to generate.
2 · Deployment and embedding
Serve this page on the same HTTPS origin as /api/govee. Change meta[name="govee-api-base"] if the API path differs. Embed with an iframe where desired:
<iframe src="https://your-site.example/lighting/"
title="House lighting preview"
style="width:100%;height:1250px;border:0"
loading="lazy"></iframe>
For unrelated embedding domains, use a same-site reverse proxy or a tested partitioned-cookie approach; third-party cookies can be blocked. Do not weaken cookie security or replace limits with local storage. Set a restrictive frame-ancestors allowlist for approved sites. For CSP, hash this file’s inline script/style or issue a nonce; allow blob: images. Avoid third-party analytics on uploads.
3 · Backend contract
All responses are JSON except downloads. Every route is scoped to the anonymous cookie owner. Require HTTPS, Cache-Control: no-store, same-origin requests, and an origin check. Session establishment uses GET; all mutations require the returned CSRF token.
GET /api/govee/session
{
"csrfToken": "opaque-session-csrf-token",
"quota": {
"requestLimit": 2, "imageLimit": 4,
"requestsUsed": 0, "requestsReserved": 0,
"imagesUsed": 0, "imagesReserved": 0
},
"jobs": []
}
POST /api/govee/jobs
Cookie: anonymous visitor session
X-CSRF-Token: token from session
Idempotency-Key: client-generated UUID
multipart fields: image, palette
palettes: rainbow | warm | christmas | ocean
response (202): { "job": Job, "quota": Quota }
GET /api/govee/jobs/:id
response: { "job": Job, "quota": Quota }
POST /api/govee/jobs/:id/retry
X-CSRF-Token + Idempotency-Key
Retry only the missing output within the original reservation.
response (202): { "job": Job, "quota": Quota }
GET /api/govee/jobs/:id/download?variant=day|night|both
PNG for one; ZIP for both. Attachment disposition.
Only the cookie owner can download. No public asset bucket.
Job = {
"id": "opaque-job-id",
"status": "queued",
"createdAt": "2026-10-23T12:00:00Z",
"originalUrl": "/api/govee/assets/opaque-original-id",
"outputs": [
{ "variant": "day", "url": "/api/govee/assets/opaque-day-id" }
],
"canRetry": false
}
Statuses: queued, analyzing, generating, validating,
completed, partial, failed
completed requires both day and night outputs.
Asset URLs must be same-origin under the API path.
Quota = quota object shown above.
Errors: { "error": { "code": "...", "message": "..." } }
429: quota/rate limit; 413: upload too large; 403: CSRF/session.
session.jobs contains all retained jobs and active reservations.
4 · Anonymous limit enforcement
- Create a cryptographically random opaque visitor ID in an
HttpOnly; Secure; SameSite=Lax; Path=/ first-party cookie. Match its expiry to the disclosed allowance policy. Store a hashed identifier server-side. - Atomically reserve one request and two image slots; reject concurrent or over-limit jobs. The browser counters are display-only. Bind idempotency keys to owner and operation with a unique database constraint. Reject reuse with a different payload.
- Commit the request when its first image succeeds; commit image counts individually. Keep the missing image reservation on partial completion. On complete failure release all unused reservations. Enforce at most two successful request records and four output records per visitor.
- Recover stale jobs using leases and reconciliation. A lost HTTP response must not trigger duplicate inference. Workers retry only missing variants; persist outputs before updating counters. Bound retries and total spend.
- Add layered IP/network rate limits, request-size limits, global daily spend caps, and optional risk-based anti-bot checks. Do not block whole households solely for sharing an IP.
5 · Accurate image-generation pipeline
- Revalidate bytes, MIME, dimensions, and upload limits on the server; decode and re-encode safely. Client validation is not a security boundary.
- Analyze the original with a separately evaluated vision model. Propose visible eaves, sloping gables, canopy undersides, receiving surfaces, and occlusions. Use one shared installation plan for the pair. Automatic geometry is approximate.
- Call
/v1/images/edits twice, once per variant, always from the same original—not from the other generated output. Use explicit model: gpt-image-1.5, input_fidelity: high, quality: high, n: 1, and output_format: png. Keep OpenAI credentials in server environment secrets. - Choose
1536x1024, 1024x1536, or 1024x1024; pad without stretching/cropping the building, then unpad consistently. Return the original and results with matching framing for comparison. These are not native 4K outputs. - Supply a licensed lighting reference as a secondary image, if available. It guides scallop appearance only, never house geometry. No reference photo is bundled in this file.
- Check architecture, signage, left/right coverage, cone shape, occlusion, and exposure. Automated checks can miss errors. Flag failures and retry only the affected variant within the original job. Do not silently count rejected images as delivered.
- For strict geometry preservation, add a non-generative, original-photo grading and masked lighting-compositing mode. AI masks are guidance, not pixel-perfect locks. An optional roofline-correction editor is a later enhancement, not implemented in this file.
6 · Server-side prompt template
REQUESTED VARIANT: {day or night; selected by the server for this edit}.
Edit the supplied ORIGINAL customer photograph. It is the sole
authority for the building and scene. Any second image is a LIGHTING
STYLE reference only; never copy its architecture, objects, or framing.
Preserve the exact building geometry, proportions, rooflines, windows,
doors, columns, signs, building numbers, clocks, landscaping, palm trees,
flowerbeds, parking areas, vehicles, surroundings, and camera angle.
Do not redesign, repair, add, remove, move, or invent architectural
elements. Do not invent obscured roofline sections or alter text.
Use the shared installation plan to illuminate EVERY eligible visible
eave, gable underside, overhang and canopy, including left and right
sections. Do not light roof ridges, vertical corners, or window frames
unless explicitly specified in the installation plan.
Install realistic Govee Permanent Outdoor Lights Pro-style concealed
fixtures underneath the rooflines. Each fixture casts a distinct,
downward-facing curved scalloped wall-wash cone, overlapping its
neighbors. Even spacing must follow perspective and the building's
surfaces. Scallops, NOT glowing strips, hanging bulbs, isolated
spotlights, visible wiring, or exposed LED strips.
PALETTE: {server-controlled preset}. Rainbow sequence: warm white,
yellow, pink, magenta, purple, blue, cyan, turquoise, green, with
smooth transitions. Keep moderate brightness and restrained saturation.
Respect occlusions; light must not pass through trees, columns or walls.
Use soft surface illumination, gentle shadows and subtle reflections.
Do not add wet pavement, stars, decorations, unrelated lights or objects.
DAY VARIANT: preserve the original daylight atmosphere if present;
if the source is nighttime, use natural daylight without changing
geometry. Fixtures remain on, but their wall-wash is realistically
subtle under ambient daylight, not a neon nighttime glow.
NIGHT VARIANT: use a natural deep-blue nighttime sky and balanced
exposure. Keep architectural details visible. Lighting should look
like a professional nighttime architectural photograph of the SAME
building. No excessive neon glow, oversaturation, harsh halos,
unrealistic shine, added text, or watermarks.
Apply ONLY the requested variant's atmosphere instruction.
7 · Progress, resilience, privacy
The browser measures upload progress (0–10%). Server status advances the estimated ring: queued 12%, analyzing 20%, generating 35% (65% when one output exists), validating 90%, pair complete 100%. There is no timer that fabricates completion. Elapsed time is real. Polling reconnects through the anonymous session; changing tabs or refreshing must not consume a request. Provide a real deletion/expiry task, authenticated asset proxy, bounded ZIP downloads, monitoring, and a published retention policy.
8 · Acceptance checks before launch
- Day/night pairs preserve framing and show scallops, not strips, across representative houses and commercial buildings.
- Two completed pairs block a third on the server, including concurrent tabs and direct API requests.
- Refresh during upload/inference, missing output, timeout, cookie expiry, denied consent, and download errors behave safely.
- No provider key in HTML, network responses, analytics, or logs. No other visitor can read job IDs or assets.
- Mobile, keyboard, screen-reader status updates, reduced motion, download ZIP, and embedding-cookie behavior are tested.
- Benchmark cost and latency before promising delivery times. A pair involves two paid image edits plus any analysis/checks.
References: OpenAI image-generation guide · GPT Image 1.5. This requested model is a previous-generation model; benchmark alternatives before claiming best-in-market quality.