OPEN API · v1
把家具 AI 能力
把家具 AI 能力
接入你的平台
三视图、换皮、改一改、加背景、换产品、原创爆款、多维影棚、图转3D、3D拆件——瞄图旗下九大产品系列，一套标准 REST API，图片传公网 URL 即可调用。
快速开始
两步完成第一次调用。
1
获取 API Key
在瞄图主站「API 账户」页一键开通，即生成形如 mt_ext_xxxxxxxx 的 Key，每个请求在 Header 中携带即可鉴权。复用你的账户积分作为调用余额，无需单独建号。
2
发起第一次调用
用图片网址调用任意接口（如三视图），拿到任务号（taskId）后轮询查询结果。
Base URL：
https://api.miaotool.cn · 所有路径前缀 /v1 · 示例：POST /v1/threeview/generate
开通 API 与充值
API 的开通、积分查询与微信充值统一在瞄图主站「API 账户」页完成；本文档页只做接口说明。
🚀 前往主站 API 账户页（Key · 积分 · 微信充值） 前往 →
说明：API 调用消耗的是你的瞄图账户积分，与网站工具余额相互独立、互不影响。余额不足时网关返回 402 Payment Required。
鉴权
统一使用 API Key 鉴权，无需 OAuth、无需签名计算。
# 每个请求都带这两个头
X-API-Key: <YOUR_API_KEY>
Content-Type: application/json
⚠️ 余额预校验：网关在调用业务前检查你的账户积分余额，不足时直接返回 402 Payment Required，调用不进业务函数（不浪费算力）。请确保账户内有足够积分。
通用约定
所有接口遵循同一套输入输出规范。
📷 图片输入
传 公网可访问的 http(s) 图片 URL 即可（如 https://your-cdn.com/sofa.jpg）。
网关会自动下载并转存为云存储，调用方无需理解底层存储。
也支持同环境 cloud:// fileID（原样透传）。
⏱ 异步任务模式
绝大多数接口为异步：POST /generate 立即返回 { "data": { "taskId": "..." } }，
随后用该 taskId 轮询 GET /poll?taskId=...，直到 status 变为 success 或 failed。
换产品接口为同步，直接返回最终图。
🔔 Webhook 回调（可选）
配置回调地址后，任务完成时网关会自动 POST 结果，无需主动轮询：
{
"taskId": "material_xxxx",
"status": "success",
"source": "material",
"result": { "resultImage": "https://..." },
"timestamp": 1753000000000
}📤 统一响应结构
{
"code": 0, // 0=成功，非0=错误码
"message": "ok", // 人类可读信息
"data": { ... }, // 业务数据
"requestId": "..." // 排查用
}接口列表
共 7 大能力族。每个 /generate 返回 taskId，对应 /poll 查询进度。
家具换皮
Material · 视觉渲染
上传家具原图 + 目标材质，生成换皮效果图。节省90%产品手册成本。
POST /v1/material/generate
GET /v1/material/poll
必填：
imageUrl · 可选：textureName/colorName/fabricImageUrl外观改一改
Modify · 视觉渲染
高矮胖瘦随心改，调整家具尺寸 / 弧度 / 高度等结构参数。节省90%手绘时间。
POST /v1/modify/generate
GET /v1/modify/poll
必填：
imageUrl · 可选：params{ volume, curvature, baseHeight }三视图
ThreeView · 工程落地
效果图转三视图 / 六视图工程图。省90%画图时间。支持导出 DXF 矢量文件。
POST /v1/threeview/generate
GET /v1/threeview/poll
必填：
imageUrl(公网图) 或 fileID(云存储) · 可选：mode|category加背景
Scene · 视觉渲染
白底图加场景背景，室内户外炫酷百变。节省99%修图时间。
POST /v1/scene/generate
GET /v1/scene/poll
必填：
imageUrl · 可选：sceneStyle/envMode/furnitureType换产品
ProductSwap · 视觉渲染
喜欢的场景图，换成自家产品。同步接口，直接返回最终图。无 taskId。
POST /v1/productswap/swap
必填：
composited_base64/scene_base64/product_base64/selection{x,y,w,h}原创爆款
Master · 设计推演
老款一张图，变万千灵感。基于原图推演原创爆款外观。爆款的起点。
POST /v1/master/generate
GET /v1/master/status
必填：
imageUrl · 可选：masterName/targetCategory/count(1–4)多维影棚
Studio · 视觉渲染
一张图，变前后左右多张影棚级渲染图。节省90%摄影师费用。
POST /v1/studio/generate
GET /v1/studio/poll
必填：
imageUrl · 可选：views[front|side|side_45|left_45]图转3D
ThreeD · 三维建模
一张家具图，AI 生成可编辑 3D 模型（GLB）。混元 3.0 引擎，商业渲染 / 工业拓扑两档。
POST /v1/threed/generate
GET /v1/threed/poll
POST /v1/threed/export
必填：
imageUrl(公网图) · 可选：mode=commercial|industrial3D 拆件
Component · 三维建模
上传 3D 模型，AI 自动拆解为多个 GLB 零件，用于生产打样 / 注塑开模。
POST /v1/component/generate
GET /v1/component/poll
POST /v1/component/export
必填：
fileUrl(模型公网直链) · 支持 GLB/FBX/OBJ/STL/ZIP
轮询通用写法：
curl "https://api.miaotool.cn/v1/<族>/poll?taskId=<TASK_ID>" -H "X-API-Key: <YOUR_API_KEY>"
，直到 data.status 为 success。
3D 两族请求示例：
# 图转3D（商业渲染 20 / 工业拓扑 15）
curl -X POST "https://api.miaotool.cn/v1/threed/generate" \
-H "Content-Type: application/json" -H "X-API-Key: <YOUR_API_KEY>" \
-d '{ "imageUrl": "https://your-cdn.com/sofa.jpg", "mode": "commercial" }'
# 3D 拆件（拆件 20 / 导出 3）
curl -X POST "https://api.miaotool.cn/v1/component/generate" \
-H "Content-Type: application/json" -H "X-API-Key: <YOUR_API_KEY>" \
-d '{ "fileUrl": "https://your-cdn.com/model.glb" }'价格
按调用次数消耗积分。以下为单次预估消耗。
家具换皮
material/generate
3 积分
改一改
modify/generate
5 积分
三视图
threeview/generate
7 积分起
极速 7 · 标准 9 · Pro 12
（按传入
（按传入
mode 选择）DXF 导出
threeview/export
2 积分
加背景
scene/generate
5 积分
换产品
productswap/swap
5 积分
原创爆款
master/generate
8 积分
多维影棚
studio/generate
5 积分起
标准 5 · Pro 18 · Ultra 22 · Mega 25
（按传入视角数选择）
（按传入视角数选择）
图转3D
threed/generate
20 积分
3D拆件
component/generate
20 积分
三视图（极速 7 / 标准 9 / Pro 12，按传入 mode 选择）与多维影棚（标准 5 / Pro 18 / Ultra 22 / Mega 25，按传入视角数选择）提供多档位；其余接口为固定单价。
代码示例
以「三视图」为例，三种语言通用写法。三视图按传入 mode 分档位（PURE 极速/7 · SIMPLE 标准/9 · DETAIL Pro/12），其余接口替换路径与 body 即可。
# 1) 发起三视图（mode 选档位：PURE 极速/7 · SIMPLE 标准/9 · DETAIL Pro/12）
curl -X POST "https://api.miaotool.cn/v1/threeview/generate" \
-H "Content-Type: application/json" \
-H "X-API-Key: <YOUR_API_KEY>" \
-d '{ "imageUrl": "https://your-cdn.com/sofa.jpg", "mode": "SIMPLE" }'
# 2) 轮询结果（把 TASK_ID 换成上一步返回的 taskId）
curl "https://api.miaotool.cn/v1/threeview/poll?taskId=<TASK_ID>" \
-H "X-API-Key: <YOUR_API_KEY>"const API = "https://api.miaotool.cn";
const KEY = "<YOUR_API_KEY>";
// 1) 发起三视图（mode：PURE 极速/7 · SIMPLE 标准/9 · DETAIL Pro/12）
const r = await fetch(API + "/v1/threeview/generate", {
method: "POST",
headers: { "Content-Type": "application/json", "X-API-Key": KEY },
body: JSON.stringify({ imageUrl: "https://your-cdn.com/sofa.jpg", mode: "SIMPLE" })
});
const { data } = await r.json();
const taskId = data.taskId;
// 2) 轮询直到完成
let res;
do {
await new Promise(s => setTimeout(s, 3000));
const p = await fetch(API + \`/v1/material/poll?taskId=${taskId}\`, { headers: { "X-API-Key": KEY } });
res = await p.json();
} while (res.data.status === "pending" || res.data.status === "processing");
console.log(res.data.resultImage);import requests, time
API = "https://api.miaotool.cn"
KEY = "<YOUR_API_KEY>"
HDR = {"Content-Type": "application/json", "X-API-Key": KEY}
# 1) 发起三视图（mode：PURE 极速/7 · SIMPLE 标准/9 · DETAIL Pro/12）
r = requests.post(API + "/v1/threeview/generate", headers=HDR,
json={"imageUrl": "https://your-cdn.com/sofa.jpg", "mode": "SIMPLE"})
task_id = r.json()["data"]["taskId"]
# 2) 轮询直到完成
while True:
time.sleep(3)
p = requests.get(API + f"/v1/material/poll?taskId={task_id}", headers=HDR)
d = p.json()["data"]
if d["status"] in ("success", "error", "failed"):
break
print(d.get("resultImage"))错误码
| Status | 含义 | 处理建议 |
|---|---|---|
| 200 | 成功 | — |
| 400 | 参数缺失 / 图片处理失败 | 检查必填字段、确认图片 URL 公网可访问 |
| 401 | 未授权 | 检查 X-API-Key 是否正确 |
| 402 | 余额不足 | 请先在账户内补充积分再调用 |
| 404 | 路由不存在 | 检查路径是否带 /v1 前缀 |
| 429 | 触发限流 | 降低频率或联系提额 |
| 500 | 服务器内部错误 | 重试或联系支持 |