ikea-room

name	ikea-room
description	Take a photo of a room and fill it with real IKEA furniture — searches the live IKEA catalog, fits items to the room's dimensions and budget, composites the actual products into the photo, and outputs a shopping list with article numbers, prices, and direct links. Use when the user wants an IKEA room redesign, says "fill my room with IKEA", or wants a shoppable room makeover.

IKEA Room — photo in, furnished room + shopping list out

The contract: every item in the final render is a real, currently-sold IKEA product. The render sells the vibe; the article numbers carry the truth. Never invent furniture.

Inputs (ask for whatever is missing)

1. Room photo — the wider the angle, the better.
2. Country code — for catalog region and prices (au, de, us, ...). Default au.
3. Budget — total cap in local currency.
4. Room dimensions — at least approximate width × depth in meters. Don't guess from the photo alone; ask.
5. Constraints — what stays, what goes, style preference (optional).
6. Fixed features, incl. off-camera — ask: "Anything that must stay clear — built-in wardrobe/closet, a door, a radiator, outlets — especially on walls not shown in the photo?" The photo only reveals one angle; this question covers the blind spots so the plan doesn't furnish into occupied space or sell storage the room already has built in.

Step 1 — Analyze the photo → build the zone map

Read the photo and note: room type, light direction, floor/wall colors, existing furniture (staying vs replaceable), and the empty zones to fill.

Then build a zone map — the single artifact the plan and the render both obey. It splits the room into two kinds of space:

• Fixed features (no-go): things furniture must NOT overlap, block, or replace — built-in wardrobe/closet (it's architecture, not furniture), doors (keep the swing clear), windows, radiators, outlets. For each, note its wall, whether it's in the frame or only known from the user's off-camera answer, and roughly where it sits. A built-in wardrobe is the classic trap: the model treats the emptied room as a blank canvas and furnishes right over it unless you mark it.
• Fillable zones: the free space where new furniture may go, with approximate span, e.g. "left wall: storage, ~1.6m available; window corner: reading chair; center: rug."

Off-camera fixed features (from input #6) go in the map too — they don't appear in the render, but they keep the cart honest (no buying a wardrobe the room already has).

Step 2 — Plan the furniture list

Turn the fillable zones (never the fixed features) into a concrete item list (category + max dimensions + target price per item) that sums under budget with ~10% headroom. 4–7 items is the sweet spot; more than that and the composite degrades.

Plan around the no-go zones: don't place an item where a fixed feature sits, and don't add a category the room already has built in (e.g. no wardrobe if one is built in).

Step 3 — Search the catalog

For each planned item:

python3 scripts/ikea_search.py "bookcase" --country au --max-price 150

Each result line has name, type, dims (W×D×H cm), itemNo (article number), price, url, image. Selection criteria, in order:

1. Fits the zone — check dims against the zone plan. Hard requirement. Some categories (e.g. armchairs) return empty dims — fetch the product's url and read the measurements from the page before accepting the item.
2. Render-friendly — prefer iconic, simple-shaped items (BILLY, KALLAX, MALM, POÄNG, LACK, PAX) and plain finishes (white, oak) over patterned or intricate ones. Image models reproduce these faithfully; ornate items hallucinate.
3. Budget — keep a running total; stay under cap.

Verify each chosen url resolves (HTTP 200) before putting it in the final list.

Step 4 — Get media into Higgsfield

• Room photo (local file): media_upload → PUT the bytes to the returned upload_url via curl → media_confirm. Gives a media_id.
• Product images (HTTPS URLs from the search results): media_import_url per image — no download needed. Each returns a media_id.

These studio shots are the reference inputs that keep the generation honest.

Step 5 — Composite, one item at a time

Use generate_image with a multi-reference edit model — default nano_banana_pro (check models_explore get for its medias[].roles and pass the room and product images with the right roles). Preflight credits once with get_cost: true.

Never generate all items in one pass — identity degrades. Loop, largest item first, and chain the edits: the first call references the room media_id + product 1's media_id; every later call passes the previous generation's job_id as the room input + the next product's media_id. No re-uploading between steps.

Prompt template per edit:

Edit image 1 (the room). Place the furniture item shown in image 2 into the [zone, e.g. "left wall"] exactly as it appears in image 2 — same proportions, colors, materials, shelf count. Match the room's perspective and lighting. Do not modify, move, or invent any other furniture. Keep walls, floor, windows, and lighting unchanged. Treat the edges of the image as the hard boundaries of the room: never place, imply, or extend furniture beyond the visible frame. [Per in-frame fixed feature, append a no-go clause: "Do not place, overlap, or obscure the built-in wardrobe on the right wall — it is a fixed part of the room."]

Step 6 — Verify each edit

After every generation, compare the render against the product photo and answer: does the item in the render match the article — proportions, finish, shelf/drawer count? Also check the zone map was respected: no furniture overlaps a fixed feature (built-in wardrobe, door, window, radiator), and nothing sits outside the visible frame. If either fails, regenerate with the specific correction appended to the prompt (e.g. "the bookcase must have 5 shelves, not 4", or "move the chair left — it is covering the built-in wardrobe"). Max 3 attempts per item, then swap to a more render-friendly product and note the substitution.

Step 7 — Deliverables

1. Final render (plus the original for the before/after).
2. Shopping list in markdown:

# Your room, in IKEA — total $XXX (budget $YYY)

| Item | Article no. | Price | Link |
|---|---|---|---|
| BILLY bookcase, white, 80x28x202 cm | 106.165.64 | $129 | [ikea.com](url) |
...

Article numbers work in any country's IKEA search if a link doesn't.

State the real total. If over budget, fix it before delivering — never fudge prices, article numbers, or links: they are the verifiable part of the promise.