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. The request body is capped at 4.5 MB and base64 inflates every input by a third, so inline images are really limited to about 3.3 MB of pixels. An oversized body is rejected at the edge with 413 before anything is charged. Downscaling references to roughly 800 px is usually enough.
• 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.

Embed on your website

No coding needed. Put a MeltFlex AI design tool on your own website with your logo, colour and language. Visitors upload a photo of their room and design it right on your page, without a MeltFlex account. No API key is involved: you paste one piece of code.

• Furniture brands and e-shops: shoppers place your products in a photo of their room.
• Design studios and real estate: visitors restyle a room, or see an empty listing furnished.

Building and previewing an embed is free with any account. The code unlocks on an Enterprise plan. Every design a visitor makes uses 10 credits from your account.

Set it up (5 min)

Open the Website Embed Builder and click New embed. The live preview on the right shows what your visitors will see.

1. Tool: pick who it is for: a furniture shop, a design studio or real estate.
2. Website: type your domain, e.g. yourshop.com. The tool only loads on that site and its subdomains, so nobody can copy it to theirs and spend your credits. Up to 10 domains.
3. Brand: your logo and button colour are read from your website and you can change them. Pick the language: English, Spanish, German, French or Portuguese.
4. Products (shops only): paste your product feed link, or add products by hand.
5. Code: click Copy code and paste it into your page.
6. Designs: later, come back here to see what your visitors made: before and after, the prompt and the products used. You can download them as a ZIP.

Add the code

The code is one iframe. Copy yours from the builder, it has your own embed ID in it:

<iframe
  src="https://widget.meltflexai.com/YOUR_EMBED_ID"
  title="AI Interior Design by MeltFlex"
  width="100%"
  height="720"
  style="border:0;border-radius:12px;max-width:100%;"
  allow="clipboard-write"
  loading="lazy"
></iframe>

Paste it where the tool should appear:

• WordPress: edit the page, add a "Custom HTML" block, paste, Update.
• Shopify: add a "Custom Liquid" section in the theme editor (or use the page's HTML editor), paste, Save.
• Webflow: drag an "Embed" element onto the page, paste, Publish.
• Any other site: paste it into the page's HTML.

You never need to paste the code again. Pause the embed or change its logo, colour, language, products or domains in the builder and your site shows it right away.

Shops: your products

• Product feed: paste the link to the feed you already use for Google Shopping (Google Merchant RSS or Atom, exported by Shopify, WooCommerce, Shoptet, Magento or Mergado) or a Heureka XML feed. Names, pictures, prices, stock, categories and colour variants come from it. Up to 3,000 products, refreshed every hour.
• By hand: no feed? Add up to 60 products with a photo, name, price and link. You can use both together.
• Choose what shows: Choose products lists everything from your feed and your own products. Switch off single products or whole categories; a hidden category stays hidden when your feed adds to it.
• On a product page: add ?product= with the page's address to src and the tool opens with that product ready to place. The address must be the same product link as in your feed or product list.

<!-- any product page -->
src="https://widget.meltflexai.com/YOUR_EMBED_ID?product=https://yourshop.com/products/oak-sofa"

<!-- Shopify product template -->
src="https://widget.meltflexai.com/YOUR_EMBED_ID?product={{ shop.url }}{{ product.url }}"

Set it up with AI or the API

Hundreds of products and no feed? Let an AI agent (Claude Code, Cursor, ChatGPT with code) or your own script build the embed and load the products for you. It needs an API key (any paid plan). Give your agent this:

Set up a MeltFlex website embed for my shop with the API at
https://www.meltflexai.com/api#embed-api (my key: mf_sk_...).
Tool "retailer", website yourshop.com. Take the products from
<my feed link / my product pages / this spreadsheet>: name, price,
currency, product link and one photo URL each.

/api/v1/embeds takes the same fields as the builder. Products added this way may use any public https photo URL; we keep our own copy. A feed is read before saving, and one we can't read returns 422 with the reason.

curl -X POST https://www.meltflexai.com/api/v1/embeds \
  -H "Authorization: Bearer mf_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "retailer",
    "name": "Main shop",
    "allowedDomains": ["yourshop.com"],
    "language": "en",
    "accentColor": "#1f2937",
    "logoUrl": "https://yourshop.com/logo.png",
    "productFeedUrl": "https://yourshop.com/feed.xml",
    "manualProducts": [
      { "name": "Oak sofa", "price": 1299, "currency": "EUR",
        "link": "https://yourshop.com/products/oak-sofa",
        "image": "https://yourshop.com/img/oak-sofa.jpg",
        "category": "Sofas" }
    ]
  }'

• GET /api/v1/embeds: your embeds. PATCH with id and any fields to change (manualProducts replaces the whole list), enabled: false to pause. DELETE with id.
• tool: retailer (shop products), interior, staging or kitchen. language: en, es, de, fr or pt.
• Retailer embeds need productFeedUrl, manualProducts (up to 60), or both. Up to 10 allowedDomains.
• Keep products out of the embed with productFilter: { "hidden": ["<product id>"], "hiddenCategories": ["Sofas"] }. The product id is the feed's item_group_id (or id when it has none). A hidden category also hides products the feed adds to it later. Send it whole on each change.
• The reply's link.token is the embed ID for https://widget.meltflexai.com/<token>. It is null (locked: true) until your account has Enterprise, as in the builder. Everything made here also shows in the builder.

Credits, limits, FAQ

• Who pays? Your account. Each design is 10 credits from your (team) balance. Failed designs are refunded automatically.
• Daily limit: set a maximum number of designs per 24 hours for all visitors together (default 100 = up to 1,000 credits a day), or choose No limit. Either way, each visitor can make up to 10 designs a day.
• Out of credits, plan ended or embed paused? Visitors see "this service is not available right now" and nothing is spent.
• Your team: everyone added under Team access sees and edits the same embeds and their designs.
• Testing locally? Add localhost to the website list.
• Blank frame on your site? The page's domain is not in the embed's website list. Check the spelling (no https:// needed) and that your site runs on https.
• Your site has its own Content Security Policy? Allow the frame: frame-src https://widget.meltflexai.com.
• Wix: not supported. Wix shows custom code from a different domain than your site, so the domain lock blocks it.

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); });

List jobs

Everything this key has started, newest first — the recovery path when a job id goes missing. A dropped connection, a killed process or a gateway timeout can take the id with it; the render carries on regardless, and this is how you find it again. Free, no credits.

Optional query: kind (video, world, furniture_3d, floorplan_3d), status (pending, running, succeeded, failed — video only, see below) and limit (1–100, default 20).

Video carries a definite state and the finished result inline, because it is tracked in its own job row the moment it starts. world, furniture_3d and floorplan_3d come back with status: "started" (or "failed" once refunded) and a pollUrl instead — this endpoint hands back the id you lost, it does not poll Marble or Meshy on your behalf for every job in your history. Call the pollUrl to get the real state.

{
  "success": true,
  "count": 3,
  "jobs": [
    {
      "jobId": "04c942b2-4359-4a26-a383-ea49124614d7",
      "kind": "video",
      "status": "succeeded",
      "createdAt": "2026-09-11T12:05:34Z",
      "creditsUsed": 100,
      "videoUrl": "https://.../api-videos/....mp4",
      "durationSeconds": 4,
      "aspectRatio": "16:9"
    },
    {
      "jobId": "7c1f0b2e-...",
      "kind": "video",
      "status": "running",
      "createdAt": "2026-09-11T12:11:02Z",
      "creditsUsed": 100,
      "pollUrl": "https://www.meltflexai.com/api/v1/video?jobId=7c1f0b2e-..."
    },
    {
      "jobId": "b7f2...",
      "kind": "world",
      "status": "started",
      "createdAt": "2026-09-11T11:40:02Z",
      "creditsUsed": 30,
      "pollUrl": "https://www.meltflexai.com/api/v1/world?operationId=..."
    }
  ]
}

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",
  "pricing": {
    "POST /api/v1/generate": {
      "perImage": { "lite": 8, "quick": 10, "pro": 15 },
      "note": "Multiplied by variations (1-3). Reference images and products are free."
    },
    "POST /api/v1/video": { "4s": 100, "8s": 150 },
    "POST /api/v1/world": { "draft": 30, "hd": 200 },
    "POST /api/v1/furniture-3d": 75,
    "POST /api/v1/floorplan-to-3d": 100
  },
  "costs": { "...": "the app's internal ledger, kept for backward compatibility" }
}

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
}