Guida all'API MakerWorld: endpoint per dettaglio modello, collezioni e ricerca (2026)
TryAR Labs
Esiste un'API pubblica di MakerWorld?
Risposta breve: nessuna ufficiale. MakerWorld non pubblica un'API con chiavi, quote o documentazione. Ciò che esiste — e su cui si basa ogni strumento di terzi, inclusa questa piattaforma — sono gli endpoint JSON interni che la web app di MakerWorld e Bambu Handy chiamano.
Questa guida documenta i due endpoint usati in produzione da MakerWorld Estimator, i campi di risposta su cui puoi contare e i percorsi di ricerca che funzionano davvero per gli sviluppatori. Tratta tutto qui come non documentato ma osservabile: gli endpoint possono cambiare senza preavviso, quindi usa sempre la cache e degrada con grazia.
Endpoint 1: dettaglio modello
GET https://makerworld.com/api/v1/design-service/design/{modelId}?handle=enIl modelId è il numero in qualsiasi URL di modello:
https://makerworld.com/en/models/1717122-statue-of-liberty
└── modelId = 1717122Una richiesta curl minima è questa:
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'Campi di risposta che vale la pena conoscere
| Campo | Tipo | Significato |
|---|---|---|
title |
string | Nome del modello |
coverUrl |
string | URL dell'immagine di copertina |
defaultInstanceId |
number | ID del profilo di stampa predefinito |
instances |
array | Tutti i profili di stampa (vedi sotto) |
creator.name / creator.avatar |
string | Identità del designer |
likeCount, downloadCount, printCount |
number | Statistiche di engagement |
license |
string | Tag della licenza (CC BY, Standard Digital File License, …) |
needAms |
boolean | Se è richiesto multi-colore/3D Printing Glossary">AMS |
ratingScore |
number | Valutazione media |
description |
string | Descrizione del modello (può contenere HTML) |
L'array instances[]
Ogni istanza è un profilo di stampa — l'unità utile per la stima dei costi:
| Campo | Tipo | Significato |
|---|---|---|
id |
number | ID del profilo (#profileId-XXXX negli URL) |
title |
string | Nome del profilo |
prediction |
number | Tempo di stampa in secondi (dividi per 3600 per le ore) |
weight |
number | Peso totale del filamento in grammi |
cover |
string | Immagine del profilo |
instanceFilaments |
array | [{ type, color, usedG, usedM }] per filamento |
extention.modelInfo.plates |
array | Dettaglio per piatto: { index, name, thumbnail, prediction, weight, filaments } |
L'array plates è ciò che rende possibile il costo per piatto — numero di piatti, pesi dei piatti, tempi di stampa dei piatti e colori per piatto. Se plates manca, ripiega sui totali a livello di profilo.
Endpoint 2: collezioni (preferiti)
GET https://makerworld.com/api/v1/design-service/favorites/{collectionId}?handle=enL'ID della collezione è il numero in un URL di collezione:
https://makerworld.com/en/collections/27910720-large-prints
└── collectionId = 27910720Questo endpoint restituisce i metadati della collezione (nome, creatore, descrizione, copertina) più la lista dei design al suo interno. È la base per la stima in batch — recupera una volta, poi risolvi ogni design con l'endpoint di dettaglio modello (o riusa i dati in cache).
Il nostro flusso batch è documentato nella guida ai prezzi delle collezioni; l'equivalente lato API è GET /api/scrape/collection?url={collectionUrl} sull'API dell'estimator.
Ricerca: cosa funziona invece
La query "MakerWorld search models endpoint" implica un'API di ricerca pubblica. Non ne esiste una documentata. La ricerca del sito è una chiamata interna usata dai client di MakerWorld, senza contratto pubblicato.
Per la ricerca programmatica, usa percorsi stabili e conformi ai termini:
- Ricerca nella directory dell'estimator —
GET /api/models?q={query}&sort={sort}&page={n}restituisce modelli già in cache con costi precalcolati. Veloce, documentato e compatibile con la cache. Vedi il riferimento API. - MCP
list_models— lo stesso catalogo per gli agenti AI tramite il server MCP. - Il tuo indice — se ti serve l'intero catalogo MakerWorld, costruiscilo dagli ID dei modelli che raccogli legittimamente (i tuoi caricamenti, i link pubblici che i tuoi utenti forniscono) e usa la cache in modo aggressivo.
Evita di martellare gli endpoint di ricerca interni: sono non documentati, con limiti di frequenza nella pratica e fragili.
Affidabilità, header ed etichetta
- Invia header simili a un browser.
Referer,Origin,accepte unuser-agentreale contano. Alcuni ambienti sono identificati e bloccati da Cloudflare a prescindere — il server di sviluppo locale di questa piattaforma ripiega persino sucurlper questo motivo. - Riprova con backoff. Gestisci
403,429e5xxcon almeno un singolo tentativo ritardato; il backoff esponenziale è meglio. - Metti tutto in cache. I dati dei modelli cambiano raramente. La nostra cache di produzione memorizza righe per profilo e serve le richieste ripetute dalla memoria/database; un TTL sensato è in giorni, non in minuti.
- Timeout rigidi. Timeout di richiesta di 10 secondi impediscono a un upstream bloccato di tenere occupati i tuoi worker.
- Sii un buon cittadino. Nessun crawling massivo di profili utente o pagine di ricerca; recupera ciò che ti serve per un'azione avviata dall'utente.
Trasformare i dati API in costi
Grammi e secondi grezzi diventano denaro con un modello di prezzo — tariffa del filamento per grammo, tariffa macchina per ora, allestimento per piatto, costi di spurgo per multi-colore e margine. È esattamente ciò che calcola questa piattaforma:
- REST:
GET /api/scrape?url={makerworld_url}restituisce il modello più un dettaglio completo dei costi (riferimento). - MCP: lo strumento
scrape_modelfa lo stesso per gli agenti AI (configurazione). - Browser: incolla qualsiasi URL MakerWorld nel calcolatore per il risultato piatto per piatto.
- Licenze: controlla il campo
licenserispetto al riferimento sulle licenze prima di preventivare lavoro commerciale.
La documentazione completa campo per campo della nostra API (parametri, risposte, autenticazione, crediti) è su /api, con la specifica leggibile da macchina su /openapi.yaml.