visualize_room
visualize_room repaints the walls in a photo of a room, facade or roof in 1 to 12 colors at once and returns one image per color. Give the photo as image_url (a public link) or image_base64. Give each color as brand + name_or_code from the catalog (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 color 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 colors 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 color in
standard, 2 inhd, 3 inultra. Tell the user the cost before calling. - x402 price: $0.25 per color in
standard, $0.50 inhd, $0.75 inultra(USDC on Base). The price is computed from the number of colors andquality. See /x402/.
Parameters
Section titled “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 color objects, 1 to 12 items | yes | Each color 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 color), 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 color. 0 means no shopping list. |
Color 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 |
Color name or code in that brand, e.g. “Hague Blue” or “30”. |
hex |
string, max 7 chars | instead of the pair above | Color as hex, e.g. #3D4E57. |
label |
string, max 60 chars | no | Display name for the color (useful for hex colors). |
Each color needs either brand + name_or_code, or hex. If both are present, brand + name_or_code is used.
Returns
Section titled “Returns”A result with MCP content items and structuredContent.
Content items, in this order:
- For each painted color: a text item
<brand> <name> (<code>) <hex> — color_key "<key>", then an image item (MCPimagecontent: base64dataandmimeType), 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 …), colors that could not be painted, refunded credits,Cost: N credits, M left.(credit payments only), the full-resolution linkhttps://app.usemuro.com/wynik/<project_id>, and a pointer torelight_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 color: 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 catalog color skips its own brand.
Example
Section titled “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 color 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" } } ]}- Job flow. If the result says some colors are still being painted, call /mcp/tools/get-visualization/ with the
job_idandproject_id. The colors already painted are charged up front; the rest will finish. - Validation before spending. Colors are resolved against the catalog first, then the account balance is checked, then the photo is fetched. A bad color, an unknown brand, a hex typo or a balance too low returns an error and costs nothing. Errors for unknown colors include suggestions.
- Duplicates. The same hex twice in one call is rejected, because each color is charged.
- Failures. Colors that fail are reported in the result and refunded. Under x402 the payment is settled only if every color 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_ceilingapplies to interiors only. - Color accuracy. Painted images and hex values approximate real paint. On the wall the color 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_idand acolor_key.