meltflex-3d

MeltFlex — 写真や間取り図から3Dを作成

3つのエンドポイント、1つのAPIキー。どのエンドポイントも画像を入力すると、ホストされた3Dアセットを出力します。

目的	エンドポイント	出力	クレジット	目安時間
1つの家具の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スプラット＋ビューアーリンク	30（ドラフト）／200（HD）	約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分間実行されます。その時間内にモデルの生成が終わらない場合、サーバーはジョブIDと pollUrl を含む HTTP 202 を返します。データが失われることはありません。クレジットはジョブに紐付いたままなので、完了するまで5～10秒ごとにポーリングURLへ GET します。ジョブに失敗した場合、ポーリング応答には error と refunded: true が含まれます（ポーリングの回数にかかわらず、返金は1回のみです）。必ずタイムアウトを300秒以上に設定し、HTTP 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 — 家具を1点、正面斜めから撮影します。背景は無地または白で、被写体が切れないようにしてください。
• 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

Body:

• 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 秒に設定してください）。ストレージが一時的に利用できない場合は、ファイルがインラインで返されます。GLB は model に base64 形式で、レンダリング画像は image にデータ URL として格納されます。

おすすめの使い方：まず低コストの render を実行して、間取り図が正しく読み取られていることをユーザーに確認してもらってから、100 クレジットを使って model を生成します。

3. 部屋の写真またはレンダリング画像 → 探索可能な 3D ワールド

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

Body:

• imageUrl / image — 通常の室内写真、または MeltFlex のレンダリング画像です（360° パノラマは自動検出されます）。/meltflex:design の結果は最適な入力です。
• model — draft（デフォルト）：すばやく生成でき、歩き回れるワールドです。30 クレジットで、所要時間は約 1 分です。hd：より鮮明で、近づいても細部を確認できます。200 クレジットで、所要時間は約 5 分です。それ以外の値を指定すると 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 は最も高密度なスプラットです。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 を読み込みます。GLB の場合は three.js の GLTFLoader を使用します。どちらのコード例も API ドキュメントにあります：https://www.meltflexai.com/api#world-3d および https://www.meltflexai.com/api#furniture-3d。

ユーザーとの作業方法

1. 入力に合ったエンドポイントを選びます。 製品の写真が1枚の場合は furniture-3d、間取り図の場合は floorplan-to-3d、部屋の写真やレンダリング画像の場合は world を使います。メッシュではなく3D画像を希望している場合は、output: "render" を指定した floorplan-to-3d を使うと、コストを10分の1に抑えられます。
2. 30クレジットを超える処理を実行する前に料金を伝えます（家具は75、間取り図モデルは100、hd worldは200）。hd の前に draft、model の前に render を提案します。
3. 数秒ではなく数分かかる想定です。 ビルドの実行中であることをユーザーに伝え、202が返されたらポーリングします。同じジョブを再度POSTしないでください（再度課金されます）。
4. 保存先のパスまたはホストされたURL、worldId / taskId、使用したクレジット数を報告します。worldの場合は viewerUrl も伝えます。
5. エラー： 400 = 無効なオプション値（本文に有効な値が記載されています）、401 = 無効なキー、402 = クレジット不足（/settingsを案内）、429 = リクエストを控えます。ジョブがFAILEDになった場合は自動的に返金されます。

ヒント

• 家具の写真：家具は1点のみ、背景はシンプルにし、家具が切れないようにします。正面から斜め45度の写真が最適なメッシュを生成できます。
• 間取り図：壁がはっきりした、見やすい図面が最適です。render では図面上のテキストを残しても問題ありませんが、model では自動的に削除されます。
• World：床と天井が見える、明るく広角の室内写真が最も歩きやすい空間を生成できます。resolution: "2K" の /meltflex:design レンダリングが理想的です。
• APIキーを表示したり、コミットしたりしないでください。