meltflex-3d

MeltFlex — 从照片和户型图生成 3D 内容

三个端点，一个 API 密钥。每个端点都接收图片，并返回托管的 3D 资源。

需求	端点	输出	积分	通常耗时
一件家具的 3D 模型	POST /api/v1/furniture-3d	GLB（+ 已签名的 USDZ / FBX / OBJ）	75	2–3 分钟
户型图的 3D 模型	POST /api/v1/floorplan-to-3d（output: "model"）	GLB	100	~3 分钟
户型图的3D 图片渲染	POST /api/v1/floorplan-to-3d（output: "render"）	PNG	10	~20 秒
房间的可探索 3D 世界	POST /api/v1/world	.spz splat + 查看器链接	30（草稿）/ 200（高清）	~1 分钟 / ~5 分钟

如果已配置 meltflex-mcp 服务，请优先使用其工具——furniture_to_3d、floorplan_to_3d、generate_world——它们会为你轮询并保存文件。对应的 CLI 命令是 meltflex furniture、meltflex floorplan、meltflex world。

前提条件

MELTFLEX_API_KEY（mf_sk_...，需要任意有效订阅，可从 https://www.meltflexai.com/settings 获取）。每次调用都要设置：Authorization: Bearer $MELTFLEX_API_KEY、Content-Type: application/json。积分会预先扣除，如果构建失败则自动退还。

每个端点都通过 imageUrl（公开 URL，推荐）或 image（base64 数据 URL，data:image/jpeg;base64,...，请求体上限为 15 MB）接收源图片。支持 JPEG、PNG 或 WebP。

耗时较长的构建：HTTP 202 和轮询

3D 构建会在请求中运行，最长 5 分钟。如果达到时限时模型仍在构建，服务端会返回 HTTP 202，其中包含任务 ID 和 pollUrl。不会丢失任何内容：积分会保留在任务中，你可以每隔 5–10 秒对轮询 URL 发送一次 GET 请求，直到任务完成。如果任务失败，轮询响应会包含 error 和 refunded: true（无论轮询多少次，都会且仅会退款一次）。客户端超时始终应至少设置为 300 s，并且始终要处理 202 响应。

import os, time, requests

H = {"Authorization": f"Bearer {os.environ['MELTFLEX_API_KEY']}"}

def run_3d(url, body):
    r = requests.post(url, headers=H, json=body, timeout=310)
    data = r.json()
    while r.status_code == 202:                      # still building — poll
        time.sleep(8)
        r = requests.get(data["pollUrl"], headers=H, timeout=60)
        data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("error") or data.get("message") or data)
    return data

1. 家具照片 → GLB 3D 模型

POST https://www.meltflexai.com/api/v1/furniture-3d — 75 积分。

请求体：

• imageUrl / image — 一件家具，采用正面偏侧视角，背景简洁或为白色，物体不得被裁切。
• textured（布尔值，默认 true）— 设置为 false 可跳过纹理处理并返回纯几何模型：速度更快、文件更小，价格不变。

完成时的响应（HTTP 200）：

{
  "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/...", "usdz": "...", "fbx": "...", "obj": "..." },
  "textured": true, "creditsUsed": 75
}

modelUrl 和 thumbnailUrl 由 MeltFlex 托管，且永久有效。formats 是引擎生成的已签名链接（有效期约 72 小时）——如果用户需要 USDZ/FBX/OBJ，请立即下载。

仍在构建 → HTTP 202 { "status": "IN_PROGRESS", "taskId", "progress": 64, "pollUrl": ".../api/v1/furniture-3d?taskId=..." }。通过 GET /api/v1/furniture-3d?taskId=... 轮询。

data = run_3d("https://www.meltflexai.com/api/v1/furniture-3d",
              {"imageUrl": "https://your-cdn.com/armchair.jpg"})
open("armchair.glb", "wb").write(requests.get(data["modelUrl"], timeout=120).content)
print("Saved armchair.glb — credits used:", data["creditsUsed"])

2. 平面图 → GLB 模型或 3D 渲染图

POST https://www.meltflexai.com/api/v1/floorplan-to-3d

请求体：

• imageUrl / image — 2D 平面图。
• output — "model"（默认）返回 GLB 网格模型，100 点数；"render" 返回平面图的 3D 渲染图，10 点数。
• textured（布尔值，仅适用于 model，默认值为 true）— false = 裸墙，速度更快、文件更小，价格不变。
• style（仅适用于 render）— photorealistic（默认）、3d-model、drawing、sketch、wireframe、clay。
• view（仅适用于 render）— isometric（默认）或 topdown。
• furniture（仅适用于 render）— furnished（默认，与平面图中的标记相匹配）、empty 或 styled（带家具，另加地毯、艺术品、植物和摆好餐具的餐桌）。
• interiorStyle（仅适用于 render，且仅限 photorealistic 和 3d-model 风格）— auto（默认）、modern、scandinavian、minimalist、japandi、coastal、industrial、luxury、traditional。
• labels（仅适用于 render）— full（默认，名称 + 尺寸 + 尺寸线）、names 或 none。

选项值未知时会返回 HTTP 400，并列出有效值。

model 响应：{ "success": true, "output": "model", "modelUrl": "https://.../floorplans/model.glb", "format": "glb", "textured": true, "creditsUsed": 100 }。 render 响应：{ "success": true, "output": "render", "imageUrl": "https://.../floorplans/render.png", "format": "png", "style": "...", "view": "...", "furniture": "...", "interiorStyle": "...", "labels": "...", "creditsUsed": 10 }。

渲染约需 20 秒；GLB 转换约需 3 分钟，通常会在请求结束前完成（请保留 300 s 超时）。如果存储暂时不可用，文件会以内嵌形式返回：GLB 以 base64 编码后放在 model 中，渲染图则作为数据 URL 放在 image 中。

建议做法：先运行低成本的 render，让用户确认平面图识别无误，再花费 100 点数生成 model。

3. 房间照片或渲染图 → 可探索的 3D 世界

POST https://www.meltflexai.com/api/v1/world

请求体：

• imageUrl / image — 普通室内照片或 MeltFlex 渲染图（系统会自动检测 360° 全景图）。/meltflex:design 的结果是很好的输入。
• model — draft（默认）：快速生成可步行探索的世界，30 点数，约需一分钟。hd：更清晰，近距离观察效果更好，200 点数，约需五分钟。其他值均会返回 HTTP 400。
• name（≤ 64 个字符）— 托管查看器中显示的标签。

完成时的响应（HTTP 200）：

{
  "success": true, "done": true,
  "worldId": "8641d179-d7c6-4b39-94b6-101a420e8d80",
  "spzUrl": "https://cdn.marble.worldlabs.ai/.../full_res.spz?...",
  "spzUrls": { "full_res": "...", "500k": "...", "100k": "..." },
  "thumbnailUrl": "https://.../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 是密度最高的 splat；spzUrls 还会提供更轻量的层级，以便渐进式打开（100k 文件约为 1 MB）。所有文件均支持开放 CORS。链接带签名，几天后会过期 — 请持久化保存 worldId，而不是链接。viewerUrl 是托管查看器，可直接提供给用户。

仍在构建中 → HTTP 202 { "done": false, "status": "IN_PROGRESS", "operationId": "op_...", "pollUrl": ".../api/v1/world?operationId=op_..." }。draft 世界通常会在请求结束前完成；对于 hd，请将 202 视为常规情况。

• GET /api/v1/world?operationId=... — 轮询正在构建的内容（构建期间 done: false；失败时为 status: "FAILED" + refunded: true）。
• GET /api/v1/world?worldId=... — 免费：获取之前构建的世界的新签名链接，响应结构与完成时相同。请在展示世界前立即调用。

data = run_3d("https://www.meltflexai.com/api/v1/world",
              {"imageUrl": "https://your-cdn.com/living-room.jpg", "model": "draft", "name": "Living room"})
print("World id:", data["worldId"])          # store this; the links expire
print("Open it:", data["viewerUrl"])
open("world.spz", "wb").write(requests.get(data["spzUrl"], timeout=300).content)

在网页中展示世界：使用 three.js + Spark（SplatMesh）加载 .spz；使用 three.js GLTFLoader 加载 GLB。API 文档中提供了两者的代码片段：https://www.meltflexai.com/api#world-3d 和 https://www.meltflexai.com/api#furniture-3d。

如何与用户协作

1. 根据输入选择对应端点。 一张产品照片 → furniture-3d。一张平面图 → floorplan-to-3d。一张房间照片或渲染图 → world。如果用户想要的是 3D 图片而非网格，使用 floorplan-to-3d 并设置 output: "render"，成本可降低 10 倍。
2. 对于超过 30 个积分的操作（家具 75 个、平面图模型 100 个、高清 world 200 个），先告知价格再执行。 先提供 draft，再提供 hd；先提供 render，再提供 model。
3. 预计需要几分钟，而不是几秒。 告知用户构建正在进行；收到 202 后轮询；绝不要对同一任务重复 POST（否则会再次收费）。
4. 报告已保存的路径或托管 URL、worldId / taskId，以及使用的积分。对于 worlds，请提供 viewerUrl。
5. **错误：**400 = 选项值无效（响应正文会列出有效值）；401 = 密钥无效；402 = 积分不足（提示用户前往 /settings）；429 = 暂缓重试；任务状态为 FAILED = 自动退款。

提示

• 家具照片：拍摄单件家具，背景简洁，主体完整；正面四分之三视角能生成效果最佳的网格。
• 平面图：线条清晰、墙体明确的平面图转换效果最佳；平面图上的文字不影响 render，使用 model 时会自动移除。
• Worlds：宽敞、光线充足且能看清地面和天花板的室内照片，能生成最适合行走的结果；resolution: "2K" 的 /meltflex:design 渲染图效果理想。
• 切勿打印或提交 API 密钥。