visualize_room

visualize_room repaints the walls in a photo of a room, facade or roof in 1 to 12 colours at once and returns one image per colour. Give the photo as image_url (a public link) or image_base64. Give each colour as brand + name_or_code from the catalogue (e.g. “Farrow & Ball” + “Hague Blue”) or as hex. RAL works as brand “RAL” + “9005” or just “RAL 9005”. Without a photo it paints Muro’s sample room (or facade, or roof). Every colour comes with a shopping list: the closest real paints from several brands, with ΔE and a verdict.

The tool waits up to about 45 seconds. If some colours are still being painted, it returns a job_id and project_id; fetch the rest with /mcp/tools/get-visualization/.

Cost:

Muro credits (API key or OAuth): 1 credit per colour in standard, 2 in hd, 3 in ultra. Tell the user the cost before calling.
x402 price: $0.25 per colour in standard, $0.50 in hd, $0.75 in ultra (USDC on Base). The price is computed from the number of colours and quality. See /x402/.

Parameters

Name	Type	Required	Default	Description
`image_url`	string, max 2048 chars	no	sample photo	Public link to the photo (JPEG, PNG or WebP, up to 12 MB). Leave out both image fields to paint Muro’s sample room.
`image_base64`	string	no		The photo as base64 or a `data:` URL, instead of `image_url`.
`colors`	array of colour objects, 1 to 12 items	yes		Each colour is painted as a separate image. See below.
`surface`	enum: `interior`, `facade`, `roof`	no	`interior`	What is in the photo.
`quality`	enum: `standard`, `hd`, `ultra`	no	`standard`	`standard` is about 1K (1 credit per colour), `hd` about 2K (2), `ultra` about 4K (3, plan permitting).
`paint_ceiling`	boolean	no	`false`	Interiors only: paint the ceiling too.
`country`	string, max 40 chars	no		Where the user buys paint, e.g. “PL”, “DE”, “US”. Brands sold there come first in the shopping list.
`match_brands`	array of strings (max 60 chars each), max 10 items	no	all brands	Only list paints from these brands, e.g. `["Dulux", "Śnieżka"]`.
`matches`	integer, 0 to 10	no	5	Paints to list per colour. `0` means no shopping list.

Colour object:

Name	Type	Required	Description
`brand`	string, max 60 chars	with `name_or_code`	Paint brand, e.g. “Farrow & Ball”.
`name_or_code`	string, max 100 chars	with `brand`	Colour name or code in that brand, e.g. “Hague Blue” or “30”.
`hex`	string, max 7 chars	instead of the pair above	Colour as hex, e.g. `#3D4E57`.
`label`	string, max 60 chars	no	Display name for the colour (useful for hex colours).

Each colour needs either brand + name_or_code, or hex. If both are present, brand + name_or_code is used.

Returns

A result with MCP content items and structuredContent.

Content items, in this order:

For each painted colour: a text item <brand> <name> (<code>) <hex> — color_key "<key>", then an image item (MCP image content: base64 data and mimeType), then a text item with the shopping list (Paints to buy (closest first): …).
A final text item with status lines: whether the sample room was used, progress if the job is not finished (Painted 1 of 3 so far. Call get_visualization with job_id … and project_id …), colours that could not be painted, refunded credits, Cost: N credits, M left. (credit payments only), the full-resolution link https://app.usemuro.com/wynik/<project_id>, and a pointer to relight_room.

Images larger than 1.5 MB are not inlined; the text item says so and links to the full-resolution page instead.

structuredContent:

Field	Description
`project_id`	Muro project. Needed by `get_visualization` and `relight_room`.
`job_id`	Painting job. Needed by `get_visualization`.
`status`	Job status, e.g. `done`, `failed` or still running.
`cost`, `credits_left`	Credits charged and left. Omitted under x402.
`result_url`	`https://app.usemuro.com/wynik/<project_id>`: full resolution, before/after slider, paint codes.
`colors`	One entry per colour: `key` (`c1`, `c2`, … in the order sent), `name`, `brand`, `code`, `hex`, `image` (boolean, whether a result image exists), `error` (if it failed), `shopping_list`.

Shopping list item: brand, brand_id, name, code, hex, delta_e, match (“practically identical”, “very close”, “close” or “similar”), url, local (sold in country; always false without country). Nothing above ΔE 6 is listed; a catalogue colour skips its own brand.

Example

Arguments:

{
  "image_url": "https://example.com/living-room.jpg",
  "colors": [
    { "brand": "Farrow & Ball", "name_or_code": "Hague Blue" },
    { "hex": "#D1CBC1", "label": "Warm greige" }
  ],
  "surface": "interior",
  "quality": "standard",
  "country": "US"
}

Illustrative structuredContent (shape taken from the source; values are made up, because this tool cannot be called without paying):

{
  "project_id": "proj_123",
  "job_id": "job_456",
  "status": "done",
  "cost": 2,
  "credits_left": 18,
  "result_url": "https://app.usemuro.com/wynik/proj_123",
  "colors": [
    {
      "key": "c1",
      "name": "Hague Blue",
      "brand": "Farrow & Ball",
      "code": "30",
      "hex": "#3D4E57",
      "image": true,
      "shopping_list": [
        {
          "brand": "Behr",
          "brand_id": "behr",
          "name": "Orion Gray",
          "code": "N510-6",
          "hex": "#3D4C55",
          "delta_e": 0.98,
          "match": "practically identical",
          "url": "https://usemuro.com/en/colors/behr/orion-gray",
          "local": false
        }
      ]
    }
  ]
}

Without a Muro key and without x402 payment, the call fails with an error that points to key creation. With x402 enabled and no payment attached, it returns the payment requirements (captured response for one colour in standard):

This call costs 0.25 USDC on Base, paid with x402. Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead.

followed by a second text item with the JSON payment requirements, also available in _meta["x402/error"]:

{
  "x402Version": 2,
  "error": "PAYMENT_REQUIRED",
  "resource": { "url": "x402://visualize_room", "description": "Paint a room photo", "mimeType": "application/json" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "250000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x681F7E6B36a7E12d728d2bF2db3aD55FF250F564",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

Notes

Job flow. If the result says some colours are still being painted, call /mcp/tools/get-visualization/ with the job_id and project_id. The colours already painted are charged up front; the rest will finish.
Validation before spending. Colours are resolved against the catalogue first, then the account balance is checked, then the photo is fetched. A bad colour, an unknown brand, a hex typo or a balance too low returns an error and costs nothing. Errors for unknown colours include suggestions.
Duplicates. The same hex twice in one call is rejected, because each colour is charged.
Failures. Colours that fail are reported in the result and refunded. Under x402 the payment is settled only if every colour was delivered; otherwise the result ends with You were not charged: the x402 payment was not settled.
Not enough credits. The error states the cost (colours × credits per colour), the balance, and where to top up (https://app.usemuro.com/plan).
Ceiling. paint_ceiling applies to interiors only.
Colour accuracy. Painted images and hex values approximate real paint. On the wall the colour depends on base, sheen and tinting; test a sample before buying.
Relight. To see an interior at another time of day, use /mcp/tools/relight-room/ with project_id and a color_key.