AI Replace

1 tokenTools

Replace specific furniture using a mask

Overview

AI Replace (Magic Wand) lets you selectively replace specific objects in a room. Draw a mask over the item you want to change — a sofa, table, lamp, or any element — and describe what you want in its place. You can also provide a reference material image or choose to simply remove the object. The AI blends the replacement seamlessly with the surrounding scene.

Image + mask input

Endpoint

POST /api/v1/generate

bash

curl -X POST https://roomai.com/api/v1/generate \
  -H "Authorization: Bearer rai_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "magicwand", ...}'

Parameters

Parameter	Type	Required	Description
`model`	string	Required	Must be "magicwand". magicwand
`image`	string	Required	URL of the room photo.
`mask_image`	string	Required	URL of the mask image. White areas indicate what to replace; black areas are preserved.
`prompt`	string	Optional	Describe the replacement (e.g. "a mid-century modern walnut coffee table"). Required when not using material_image or remove.
`material_image`	string	Optional	URL of a reference material/texture image. The AI will apply this material to the masked area.
`remove`	string	Optional	Set to "true" to remove the masked object entirely instead of replacing it. truefalse
`controlnet`	string	Optional	Set to "true" for structure-guided replacement that preserves the shape and perspective of the original object. Default: `"false"` truefalse
`luwmodel`	string	Optional	AI model variant. Default: `"symphony-3"` symphony-3aria
`format`	string	Optional	Output format. Default: `"png"` png

Request Example

json

{
  "model": "magicwand",
  "image": "https://example.com/living-room.jpg",
  "mask_image": "https://example.com/sofa-mask.png",
  "prompt": "a teal velvet mid-century modern sofa",
  "controlnet": "true"
}

Response

Success (200)

json

{
  "status": "success",
  "result": {
    "image_url": "https://storage.googleapis.com/...",
    "model": "magicwand",
    "tokens_used": 1,
    "processing_time_ms": 4500
  }
}

Error

json

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_TOKENS",
    "message": "Not enough tokens",
    "required": 1,
    "balance": 0
  }
}

Code Examples

cURL

bash

curl -X POST https://roomai.com/api/v1/generate \
  -H "Authorization: Bearer rai_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "magicwand",
  "image": "https://example.com/living-room.jpg",
  "mask_image": "https://example.com/sofa-mask.png",
  "prompt": "a teal velvet mid-century modern sofa",
  "controlnet": "true"
}'

JavaScript / Node.js

javascript

const response = await fetch("https://roomai.com/api/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rai_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "magicwand",
  "image": "https://example.com/living-room.jpg",
  "mask_image": "https://example.com/sofa-mask.png",
  "prompt": "a teal velvet mid-century modern sofa",
  "controlnet": "true"
}),
});

const data = await response.json();

if (data.status === "success") {
  console.log("Image URL:", data.result.image_url);
  console.log("Tokens used:", data.result.tokens_used);
} else {
  console.error("Error:", data.error.message);
}

Python

python

import requests

response = requests.post(
    "https://roomai.com/api/v1/generate",
    headers={
        "Authorization": "Bearer rai_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
  "model": "magicwand",
  "image": "https://example.com/living-room.jpg",
  "mask_image": "https://example.com/sofa-mask.png",
  "prompt": "a teal velvet mid-century modern sofa",
  "controlnet": "true"
},
)

data = response.json()

if data["status"] == "success":
    print("Image URL:", data["result"]["image_url"])
    print("Tokens used:", data["result"]["tokens_used"])
else:
    print("Error:", data["error"]["message"])

Tips

1Use "controlnet" to preserve the shape and perspective of the original object — great for swapping materials on the same furniture.
2For object removal, set "remove" to "true" and the AI will fill the area naturally.
3Provide a "material_image" URL to apply a specific texture (e.g. marble, wood grain) to the masked area.
4Make the mask slightly larger than the object for cleaner edges in the result.