MakerWorld API 指南：模型详情、合集与搜索端点（2026）
TryAR Labs
有公共的 MakerWorld API 吗？
简短回答：没有官方的。MakerWorld 并未发布带密钥、配额或文档的 API。存在的——以及包括本平台在内的所有第三方工具所依赖的——是 MakerWorld 自家网页应用和 Bambu Handy 调用的内部 JSON 端点。
本指南记录了 MakerWorld 估算器在生产中使用的两个端点、你可以依赖的响应字段，以及对开发者真正有效的搜索路径。把这里的一切都当作无文档但可观测：端点可能在不通知的情况下变更，所以务必缓存并优雅降级。
端点 1：模型详情
GET https://makerworld.com/api/v1/design-service/design/{modelId}?handle=enmodelId 是任意模型 URL 中的数字：
https://makerworld.com/en/models/1717122-statue-of-liberty
└── modelId = 1717122一个最简的 curl 请求如下所示：
curl 'https://makerworld.com/api/v1/design-service/design/1717122?handle=en' \
-H 'accept: application/json, text/plain, */*' \
-H 'referer: https://makerworld.com/' \
-H 'origin: https://makerworld.com' \
-H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'值得了解的响应字段
| 字段 | 类型 | 含义 |
|---|---|---|
title |
string | 模型名称 |
coverUrl |
string | 封面图片 URL |
defaultInstanceId |
number | 默认打印配置 ID |
instances |
array | 所有打印配置（见下文） |
creator.name / creator.avatar |
string | 设计师身份 |
likeCount、downloadCount、printCount |
number | 互动统计数据 |
license |
string | 许可标签（CC BY、Standard Digital File License……） |
needAms |
boolean | 是否需要多色/3D Printing Glossary">AMS |
ratingScore |
number | 平均评分 |
description |
string | 模型描述（可能包含 HTML） |
instances[] 数组
每个 instance 是一个打印配置——成本估算中最有用的单位：
| 字段 | 类型 | 含义 |
|---|---|---|
id |
number | 配置 ID（URL 中的 #profileId-XXXX） |
title |
string | 配置名称 |
prediction |
number | 打印时间，单位为秒（除以 3600 得到小时） |
weight |
number | 耗材总重量，单位为克 |
cover |
string | 配置图片 |
instanceFilaments |
array | 每种耗材的 [{ type, color, usedG, usedM }] |
extention.modelInfo.plates |
array | 按打印板的拆分：{ index, name, thumbnail, prediction, weight, filaments } |
plates 数组正是按打印板计费得以实现的原因——打印板数量、每板重量、每板打印时间和每板颜色。如果 plates 缺失，则回退使用配置级别的合计值。
端点 2：合集（收藏）
GET https://makerworld.com/api/v1/design-service/favorites/{collectionId}?handle=en合集 ID 就是合集 URL 中的数字：
https://makerworld.com/en/collections/27910720-large-prints
└── collectionId = 27910720该端点返回合集元数据（名称、创建者、描述、封面）以及其中的设计列表。它是批量估算的基础——获取一次，然后用模型详情端点逐一解析每个设计（或复用缓存数据）。
我们自己的批量流程记录在合集定价指南中；API 侧的等价物是估算器 API 上的 GET /api/scrape/collection?url={collectionUrl}。
搜索：什么是可行的替代方案
「MakerWorld 搜索模型端点」这一查询暗示存在一个公共搜索 API。并没有有文档的那个。该站点的搜索是 MakerWorld 自家客户端使用的内部调用，没有任何公开的契约。
若要进行程序化搜索，请使用稳定且符合条款的路径：
- 估算器目录搜索——
GET /api/models?q={query}&sort={sort}&page={n}返回已缓存的模型及预先算好的成本。快速、有文档，且对缓存友好。参见 API 参考。 - MCP
list_models——面向 AI 智能体的同一目录，通过 MCP 服务器提供。 - 你自己的索引——如果你需要完整的 MakerWorld 目录，就由你合法收集的模型 ID（你自己的上传、用户提供的公开链接）来构建，并积极缓存。
避免猛击内部搜索端点：它们无文档、实际上有限流，而且脆弱。
可靠性、请求头与礼仪
- 发送类似浏览器的请求头。
Referer、Origin、accept以及一个真实的user-agent都很重要。某些环境无论请求头如何都会被 Cloudflare 指纹识别并拦截——本平台的本地开发服务器甚至正因此才回退到curl。 - 带退避地重试。至少对
403、429和5xx做一次延迟重试；指数退避更好。 - 缓存一切。模型数据很少变化。我们的生产缓存按配置逐行存储，并从内存/数据库响应重复请求；合理的 TTL 是天级，而非分钟级。
- 硬性超时。10 秒的请求超时能防止卡住的上游拖住你的 worker。
- 做个好公民。不要批量爬取用户主页或搜索页；只为用户发起的操作获取所需内容。
把 API 数据转化为成本
原始克数和秒数要借助定价模型才能变成金钱——每克耗材费率、每小时机器费率、每板装夹费、多色冲刷费，以及利润。这正是本平台所计算的：
- REST：
GET /api/scrape?url={makerworld_url}返回模型以及完整的成本拆分（参考）。 - MCP：
scrape_model工具为 AI 智能体做同样的事（配置）。 - 浏览器：把任意 MakerWorld URL 粘贴进计算器即可得到逐板结果。
- 许可：在报出商业工作前，用
license字段对照许可参考核对。
我们 API 的完整字段级文档（参数、响应、鉴权、积分）位于 /api，机器可读的规范位于 /openapi.yaml。