API Documentation

Upload a room photo, describe the desired style or provide furniture references, and receive a photorealistic result. Each generate call costs 10 credits (auto-refunded on failure).

Furniture placement is the flagship. Send reference product photos and the API stages them into the room with correct scale, perspective and shadows. The same /v1/generate endpoint also powers a full suite of design tools (interior restyling, exteriors and gardens, surface and fixture swaps, photo-to-render), and dedicated endpoints add video walkthroughs, floorplan-to-3D, furniture-to-3D models and walkable 3D worlds. See AI Tools for a recipe per tool.

API access requires an active subscription (any paid plan). After you subscribe, you can generate your API key in account settings.

Input room

Reference furniture

Modular Sofa

Upholstered Bed

Dining Table

Oak Chair

↓

API result

Take the result and restyle it with a single prompt:

"Design this room as Italian contemporary"

"Design this room as Japanese"

Tutorial

Before you start

You need an active subscription (any paid plan) to use the API. Once subscribed, go to your account settings and click API Key under Profile:

Then click Generate API Key. The key is shown only once, copy it immediately.

• Auth: Send Authorization: Bearer mf_sk_... in every request header.
• Content-Type: application/json
• Credits: Each generation costs 10 credits, deducted before processing. Failed generations are refunded automatically.
• Timeout: Requests have a 2-minute timeout. Large images may take 30–90 seconds to process.

Basic usage: Restyle a room

The simplest call takes a room image and a text prompt. The API returns a base64-encoded PNG of the transformed room.

export MELTFLEX_API_KEY="mf_sk_..."

curl -X POST "https://www.meltflexai.com/api/v1/generate" \
  -H "Authorization: Bearer $MELTFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://your-cdn.com/empty-room.jpg",
    "prompt": "Transform this empty room during sunset with warm golden light"
  }'

The response contains a data:image/png;base64,... string. Decode it and save to a file, display in your UI, or upload to your CDN.

Furniture placement

To place specific furniture in a room, send reference images alongside the main room photo. The AI will match each item's appearance (colors, materials, textures) and position them naturally.

• referenceImageUrls array of public URLs pointing to furniture/decor photos (up to 10)
• referenceProducts optional metadata for each image: name for accurate placement

import requests

API_KEY = "mf_sk_..."
URL = "https://www.meltflexai.com/api/v1/generate"

response = requests.post(URL, json={
    "imageUrl": "https://your-cdn.com/empty-room.jpg",
    "prompt": "Place these furniture items naturally in this room during sunset",
    "referenceImageUrls": [
        "https://your-cdn.com/modular-sofa.jpg",
        "https://your-cdn.com/upholstered-bed.jpg",
        "https://your-cdn.com/dining-table.jpg",
        "https://your-cdn.com/oak-chair.jpg"
    ]
}, headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
})

data = response.json()
if data.get("success"):
    print(f"Room furnished with 4 items during sunset")

Production tips

• Use image URLs over base64 when possible. It avoids hitting the 15 MB body limit and is faster.
• Retry on 429: Implement exponential backoff (e.g. 1s, 2s, 4s, up to 30s).
• Timeouts: Set a client-side timeout of ~2 minutes. If the request times out, credits are refunded server-side.
• Image quality: Input images of at least 1024px on the longest side produce the best results.
• Prompt specificity: Be specific. "Scandinavian style with warm oak flooring and linen curtains" works better than "make it nice".
• Security: Never expose your API key in client-side code. Make API calls from your backend.

AI Tools

Overview

MeltFlex exposes a small number of endpoints that cover a large number of jobs. Most of the tools below are the same POST /v1/generate call, where you change the prompt and optionally attach reference images. Four jobs have dedicated endpoints: POST /v1/video, POST /v1/floorplan-to-3d, POST /v1/furniture-3d and POST /v1/world.

Interior & layout

Restyle a whole room, or re-plan the furniture that is already in it. Attach reference product photos to stage specific pieces. This is the same furniture-placement flow from the tutorial.

AI Interior Design

Restyle any room into a new interior style, fully furnished and photorealistic.

PromptRedesign this room in Scandinavian style with warm oak floors, linen textiles and soft natural light. Keep the room's architecture (walls, windows and layout) unchanged.Copy

Reference images: Optional. Attach product photos to stage specific furniture.

AI Layout Boost

Rearrange the furniture already in a room into a better, more functional layout.

PromptRearrange the existing furniture in this room into a more open, functional layout with clear walking paths and better flow. Keep the same furniture pieces, walls, windows and flooring.Copy

Reference images: Optional. Attach items to swap pieces in while re-planning.

Exterior & garden

The endpoint works on any photo, not just interiors. Feed a facade or an outdoor plot and describe the transformation.

AI Exterior Design

Reimagine a facade (cladding, front door, entry) while keeping the building intact.

PromptRedesign the exterior of this house in modern farmhouse style: update the facade cladding, front door and entry lighting. Keep the building's structure, roofline and proportions unchanged.Copy

Reference images: Optional. Attach a material or cladding reference.

AI Garden Design

Landscape an outdoor space with planting, paths and seating.

PromptDesign this outdoor space as a low-maintenance Mediterranean garden with gravel paths, olive trees, drought-tolerant planting and a seating area. Keep the plot boundaries and the house unchanged.Copy

Reference images: Optional. Attach reference plants or hardscape materials.

Surfaces & fixtures

Change one element at a time (flooring, walls, stairs, doors or windows) while everything else stays put. Ideal for “see it before you buy” previews. Each recipe names exactly what to change and what to keep.

AI Walls Texture

Swap the wall finish only: paint, plaster, micro-cement, panelling or wallpaper.

PromptChange the wall finish to warm greige micro-cement. Only change the walls and keep the flooring, ceiling, furniture and fixtures exactly as they are.Copy

Reference images: Optional. Attach a material swatch to match exactly.

AI Floor Restyle

Replace the flooring to preview a material before you buy it.

PromptReplace the flooring with wide-plank European oak in a natural matte finish. Only change the floor and keep the walls, furniture and lighting unchanged.Copy

Reference images: Optional. Attach a flooring sample photo.

AI Stairs Design

Restyle a staircase, treads, risers and railing, in place.

PromptRedesign this staircase with open oak treads and a slim black steel railing. Only change the staircase and keep the surrounding walls, floor and its position unchanged.Copy

Reference images: Optional. Attach a railing or tread reference.

AI Doors Design

Preview new interior doors without touching the rest of the room.

PromptReplace the interior doors with black-framed steel-and-glass doors. Only change the doors and keep the walls, flooring and everything else unchanged.Copy

Reference images: Optional. Attach a door style reference.

AI Windows Design

Change window frames and glazing while keeping the wall openings.

PromptChange the windows to slim black aluminium frames with clear glazing. Only change the windows and keep the wall openings, layout and interior unchanged.Copy

Reference images: Optional. Attach a frame or glazing reference.

Kitchen & bathroom

Whole-room redesigns that respect the existing footprint and plumbing, so the result stays buildable, not just pretty.

AI Kitchen Design

Redesign a whole kitchen: cabinetry, island, worktops and finishes.

PromptRedesign this kitchen in handleless matte-white Scandinavian style with oak open shelving and a quartz island. Keep the room's footprint, windows and plumbing positions unchanged.Copy

Reference images: Optional. Attach appliance or cabinet references.

AI Bathroom Design

Reimagine a bathroom: tiling, vanity, shower and fixtures.

PromptRedesign this bathroom in warm spa-minimalism with micro-cement walls, a walk-in rain shower and an oak vanity. Keep the room's layout and plumbing positions unchanged.Copy

Reference images: Optional. Attach fixture or tile references.

Photo to render

Turn a grey 3D draft, a SketchUp screenshot or a rough photo into a photorealistic render, with no V-Ray and no hours of setup. Keep the geometry and camera, then add real light and materials.

AI Photo to Render

Draft or screenshot in, photorealistic photograph out, at the same geometry and camera angle.

PromptTurn this 3D draft / SketchUp screenshot into a photorealistic interior photograph. Keep the exact geometry, layout, materials and camera angle. Add realistic lighting, accurate shadows and true-to-life material detail.Copy

Reference images: No. The source image already defines the scene.

Video walkthrough

Animate a still into a short cinematic walkthrough with Veo 3.1. Feed a MeltFlex render (or any interior photo) and get back an MP4 URL. Costs 100 credits for a 4-second clip, 150 for 8 seconds. Full parameters are in the API Reference.

import requests

API_KEY = "mf_sk_..."
URL = "https://www.meltflexai.com/api/v1/video"

# Feed in a MeltFlex render (or any interior still) → cinematic walkthrough.
response = requests.post(URL, json={
    "imageUrl": "https://your-cdn.com/living-room-render.jpg",
    "durationSeconds": 4,          # 4 (100 credits) or 8 (150 credits)
    "aspectRatio": "16:9",         # "16:9" or "9:16"
    # "prompt": "Slow dolly forward, then pan left to the window"  # optional
}, headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}, timeout=300)

data = response.json()
if data.get("success"):
    print(f"Video ready: {data['videoUrl']} ({data['processingTime']}s)")
else:
    print(f"Error: {data.get('error')}")

Floorplan to 3D

One endpoint, two outputs. output: "render" turns a flat 2D floorplan into a rendered 3D picture in any of the six styles the Floorplan to 3D tool offers (photorealistic, 3D model, architectural drawing, hand-drawn sketch, wireframe, clay), with the same view, furniture, interior-style and labels options. Costs 10 credits.

output: "model" (the default) returns a downloadable GLB 3D mesh instead. The plan is first rendered as a 3D cutaway view (walls, doors and windows detected), then reconstructed into geometry, textured or bare. Costs 100 credits.

import requests

API_KEY = "mf_sk_..."
URL = "https://www.meltflexai.com/api/v1/floorplan-to-3d"

headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1) A rendered 3D picture of the plan (10 credits, ~20 s)
render = requests.post(URL, json={
    "output": "render",
    "imageUrl": "https://your-cdn.com/2d-floorplan.png",
    "style": "photorealistic",   # 3d-model | drawing | sketch | wireframe | clay
    "view": "isometric",         # topdown
    "furniture": "furnished",    # empty | styled
    "interiorStyle": "scandinavian",
    "labels": "names",           # full | none
}, headers=headers, timeout=120).json()
print("Render:", render.get("imageUrl"))

# 2) A downloadable GLB 3D model of the plan (100 credits, ~3 min)
model = requests.post(URL, json={
    "output": "model",
    "imageUrl": "https://your-cdn.com/2d-floorplan.png",
    "textured": True,  # False → bare geometry, no texture pass
}, headers=headers, timeout=300).json()
if model.get("success"):
    print("3D model (GLB):", model["modelUrl"])
else:
    print("Error:", model.get("error"))

Furniture to 3D model

One photo of a furniture piece in, a textured, downloadable GLB 3D model out. This is the AI 3D Furniture Generator as an endpoint: the same photo-to-mesh engine and the same 75 credits. Build a 3D catalogue from product photography, drop pieces into a game engine or an AR scene, or hand a client a model they can spin. Full parameters are in the API Reference.

Input photo

API result: the GLB, live (drag to orbit)

import time, requests

API_KEY = "mf_sk_..."
URL = "https://www.meltflexai.com/api/v1/furniture-3d"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# One furniture photo in → a textured GLB 3D model out (75 credits, ~2–3 min)
r = requests.post(URL, json={
    "imageUrl": "https://your-cdn.com/armchair-photo.jpg",
    "textured": True,   # False → bare geometry, no texture pass
}, headers=headers, timeout=300)
data = r.json()

# Still building when the server's wait ran out (HTTP 202)? Poll the taskId.
while data.get("status") in ("PENDING", "IN_PROGRESS"):
    time.sleep(8)
    data = requests.get(URL, params={"taskId": data["taskId"]}, headers=headers, timeout=60).json()

if data.get("success"):
    print("3D model (GLB):", data["modelUrl"])
    print("Thumbnail:", data.get("thumbnailUrl"))
    print("USDZ (signed, ~72 h):", data["formats"].get("usdz"))
else:
    print("Error:", data.get("error"))

Photo to 3D world

A single interior photo or render in, an explorable 3D world out: a Gaussian-splat scene you can look around and walk through from the camera's own viewpoint. This is the AI 3D Interior Design tool as an endpoint. Two tiers: draft (30 credits, about a minute) and hd (200 credits, about five minutes, sharper up close). Chain it after /v1/generate: redesign the room first, then let the client step into the result.

import time, requests

API_KEY = "mf_sk_..."
URL = "https://www.meltflexai.com/api/v1/world"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# A room photo or render in → an explorable 3D world out.
# "draft" = 30 credits, ~1 min. "hd" = Marble's full model, 200 credits, ~5 min.
data = requests.post(URL, json={
    "imageUrl": "https://your-cdn.com/living-room-render.jpg",
    "model": "draft",
    "name": "Client living room, option B",   # optional label
}, headers=headers, timeout=300).json()

# HTTP 202 means the build outlived the wait: poll the operationId until done.
while data.get("done") is False:
    time.sleep(8)
    data = requests.get(URL, params={"operationId": data["operationId"]}, headers=headers, timeout=60).json()

if data.get("success"):
    print("World id:", data["worldId"])              # store this; the links below expire
    print("Splat (.spz):", data["spzUrl"])           # load in three.js + Spark
    print("Hosted viewer:", data.get("viewerUrl"))
else:
    print("Error:", data.get("error"))

# Later: fresh signed links for a stored world
fresh = requests.get(URL, params={"worldId": data["worldId"]}, headers=headers, timeout=60).json()

API Reference

Generate Image

Transform a room photo into a photorealistic interior design image. Optionally attach reference images of furniture to place in the room.

Request Headers

Request Body

Response Body

A successful request returns HTTP 200 with a JSON body:

{
  "success": true,
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "images": ["data:image/png;base64,iVBORw0KGgo..."],
  "count": 1,
  "creditsUsed": 10
}

Generate Video

Animate a still image into a short cinematic walkthrough (Veo 3.1). Returns a hosted MP4 URL.

A successful request returns HTTP 200:

{
  "success": true,
  "videoUrl": "https://.../ai-videos/.../clip.mp4",
  "durationSeconds": 4,
  "aspectRatio": "16:9",
  "processingTime": "48.20",
  "creditsUsed": 100
}

Floorplan to 3D

Convert a 2D floorplan image into a rendered 3D picture (output: "render", 10 credits) or a downloadable GLB 3D model (output: "model", 100 credits).

A successful render request returns HTTP 200 with a hosted image URL and the options that were applied:

{
  "success": true,
  "output": "render",
  "imageUrl": "https://.../floorplans/render.png",
  "format": "png",
  "style": "photorealistic",
  "view": "isometric",
  "furniture": "furnished",
  "interiorStyle": "scandinavian",
  "labels": "names",
  "creditsUsed": 10
}

A successful model request returns HTTP 200 with a hosted model URL:

{
  "success": true,
  "output": "model",
  "modelUrl": "https://.../floorplans/model.glb",
  "format": "glb",
  "textured": true,
  "creditsUsed": 100
}

If storage is temporarily unavailable, the file is returned inline instead as base64: the GLB under a model field, the render as a data URL under image.

Furniture to 3D

Turn one photo of a furniture piece into a textured GLB 3D model. 75 credits, refunded if the build fails.

A finished model returns HTTP 200. modelUrl and thumbnailUrl are hosted by MeltFlex and permanent; formats are the engine's own signed links in other formats, valid for about 72 hours:

{
  "success": true,
  "status": "SUCCEEDED",
  "taskId": "0193f1a2-...",
  "modelUrl": "https://.../meshes/api_..._0193f1a2.glb",
  "thumbnailUrl": "https://.../meshes/api_..._0193f1a2.png",
  "format": "glb",
  "formats": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=...",
    "usdz": "https://assets.meshy.ai/.../model.usdz?Expires=...",
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "obj": "https://assets.meshy.ai/.../model.obj?Expires=..."
  },
  "textured": true,
  "creditsUsed": 75
}

If the build is still running when the request's time budget ends, you get HTTP 202 instead. Nothing is lost: the credits stay on the job and you poll it.

{
  "success": false,
  "status": "IN_PROGRESS",
  "taskId": "0193f1a2-...",
  "progress": 64,
  "pollUrl": "https://www.meltflexai.com/api/v1/furniture-3d?taskId=0193f1a2-...",
  "creditsUsed": 75
}

Poll every 5 to 10 seconds. While building it returns status PENDING or IN_PROGRESS with a progress percentage; on success the same body as above; on FAILED an error and refunded: true. The refund happens exactly once no matter how often you poll.

Loading the result in a page is one line with three.js:

import * as THREE from "three";
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

// data = the JSON from POST /v1/furniture-3d (or /v1/floorplan-to-3d)
new GLTFLoader().load(data.modelUrl, (gltf) => scene.add(gltf.scene));

3D World

Turn one interior photo or render into an explorable Gaussian-splat 3D world. 30 credits for a draft world, 200 for hd, refunded if the build fails.

A finished world returns HTTP 200:

{
  "success": true,
  "done": true,
  "worldId": "8641d179-d7c6-4b39-94b6-101a420e8d80",
  "spzUrl": "https://cdn.marble.worldlabs.ai/.../full_res.spz?...",
  "spzUrls": {
    "full_res": "https://cdn.marble.worldlabs.ai/.../full_res.spz?...",
    "500k": "https://cdn.marble.worldlabs.ai/.../500k.spz?...",
    "100k": "https://cdn.marble.worldlabs.ai/.../100k.spz?..."
  },
  "thumbnailUrl": "https://cdn.marble.worldlabs.ai/.../thumbnail.jpg?...",
  "caption": "A bright Scandinavian living room with a balcony",
  "viewerUrl": "https://marble.worldlabs.ai/world/8641d179-...",
  "format": "spz",
  "operationId": "op_...",
  "model": "draft",
  "creditsUsed": 30
}

spzUrl is the densest splat; spzUrls adds lighter tiers for a progressive open (the 100k file is about 1 MB). All of them are served with open CORS, so a browser loads them directly. They are signed and expire after a few days: persist worldId, not the links.

A build that outlives the request returns HTTP 202:

{
  "success": false,
  "done": false,
  "status": "IN_PROGRESS",
  "operationId": "op_...",
  "model": "hd",
  "pollUrl": "https://www.meltflexai.com/api/v1/world?operationId=op_...",
  "creditsUsed": 200
}

Poll every 5 to 10 seconds. done: false while building; the finished body above on success; on failure status: "FAILED" with an error and refunded: true, exactly once.

Fresh signed links for a world you built earlier, in the same finished-world shape. Free, no credits. Call it right before you show the world.

Showing the world in a page, with three.js and Spark (the renderer this page uses for the live world above):

import * as THREE from "three";
import { SplatMesh, SparkControls } from "@sparkjsdev/spark";

// data = the JSON from POST /v1/world. The camera sits at the origin: that is
// the photo's own viewpoint, so the world opens exactly where the picture was taken.
const world = new SplatMesh({ url: data.spzUrls?.["500k"] ?? data.spzUrl });
world.quaternion.set(1, 0, 0, 0); // .spz is Y-down
scene.add(world);

const controls = new SparkControls({ canvas: renderer.domElement });
renderer.setAnimationLoop(() => { controls.update(camera); renderer.render(scene, camera); });

Get Credits

Read your account's current credit balance and the per-operation cost table. Useful for pre-flight checks before a batch.

curl "https://www.meltflexai.com/api/v1/credits" \
  -H "Authorization: Bearer $MELTFLEX_API_KEY"

Returns HTTP 200:

{
  "balance": 340,
  "totalEarned": 500,
  "totalSpent": 160,
  "email": "you@studio.com",
  "costs": {
    "floorplan": 10,
    "photo": 10,
    "photo_furniture": 15,
    "video": 100,
    "prompt": 5,
    "removal": 10,
    "world": 30,
    "mesh3d": 50
  }
}

Resources

Limits

Error codes

Error responses include a JSON body with an error field:

{
  "error": "Insufficient credits",
  "message": "You need 10 credits. Check your balance at meltflexai.com/settings",
  "required": 10
}