Guia da API do MakerWorld: Detalhes de Modelo, Coleções e Endpoints de Busca (2026)

Existe uma API Pública do MakerWorld?

Resposta curta: nenhuma oficial. O MakerWorld não publica uma API com chaves, cotas ou documentação. O que existe — e no que toda ferramenta de terceiros, incluindo esta plataforma, se apoia — são os endpoints JSON internos que o próprio app web do MakerWorld e o Bambu Handy chamam.

Este guia documenta os dois endpoints usados em produção pelo MakerWorld Estimator, os campos de resposta com que você pode contar e os caminhos de busca que realmente funcionam para desenvolvedores. Trate tudo aqui como não documentado, mas observável: os endpoints podem mudar sem aviso, então sempre faça cache e degrade com elegância.

Endpoint 1: Detalhes do Modelo

GET https://makerworld.com/api/v1/design-service/design/{modelId}?handle=en

O modelId é o número em qualquer URL de modelo:

https://makerworld.com/en/models/1717122-statue-of-liberty
                                  └── modelId = 1717122

Uma requisição curl mínima se parece com isto:

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'

Campos de resposta que vale conhecer

O array instances[]

Cada instância é um perfil de impressão — a unidade útil para estimativa de custo:

O array plates é o que torna possível o custeio por mesa — contagem de mesas, pesos por mesa, tempos de impressão por mesa e cores por mesa. Se plates estiver ausente, use os totais em nível de perfil como alternativa.

Endpoint 2: Coleções (Favoritos)

GET https://makerworld.com/api/v1/design-service/favorites/{collectionId}?handle=en

O ID de coleção é o número em uma URL de coleção:

https://makerworld.com/en/collections/27910720-large-prints
                                   └── collectionId = 27910720

Esse endpoint retorna metadados da coleção (nome, criador, descrição, capa) mais a lista de designs dentro dela. É a base para a estimativa em lote — busque uma vez, depois resolva cada design com o endpoint de detalhes do modelo (ou reutilize dados em cache).

Nosso próprio fluxo em lote está documentado no guia de precificação de coleções; o equivalente do lado da API é GET /api/scrape/collection?url={collectionUrl} na API do estimador.

Busca: O Que Funciona em Vez disso

A consulta "endpoint de busca de modelos do MakerWorld" sugere uma API pública de busca. Não existe uma documentada. A busca do site é uma chamada interna usada pelos próprios clientes do MakerWorld, sem contrato publicado.

Para busca programática, use caminhos estáveis e dentro dos termos:

1. Busca do diretório do estimador — GET /api/models?q={query}&sort={sort}&page={n} retorna modelos já em cache com custos pré-calculados. Rápido, documentado e amigável a cache. Veja a referência da API.
2. MCP list_models — o mesmo catálogo para agentes de IA através do servidor MCP.
3. Seu próprio índice — se você precisar do catálogo completo do MakerWorld, construa-o a partir de IDs de modelos que você coleta legitimamente (seus próprios uploads, links públicos fornecidos pelos seus usuários) e faça cache agressivamente.

Evite martelar os endpoints internos de busca: eles não são documentados, são limitados por taxa na prática e são frágeis.

Confiabilidade, Cabeçalhos e Etiqueta

• Envie cabeçalhos de navegador. Referer, Origin, accept e um user-agent real importam. Alguns ambientes sofrem fingerprinting e são bloqueados pelo Cloudflare independentemente disso — o servidor de desenvolvimento local desta plataforma chega até a recorrer ao curl por esse motivo.
• Tente novamente com backoff. Trate 403, 429 e 5xx com pelo menos uma nova tentativa atrasada; backoff exponencial é melhor.
• Faça cache de tudo. Os dados do modelo mudam raramente. Nosso cache de produção armazena linhas por perfil e serve requisições repetidas da memória/banco de dados; um TTL sensato é de dias, não de minutos.
• Defina timeout rígido. Timeouts de 10 segundos nas requisições evitam que um upstream travado prenda seus workers.
• Seja um bom cidadão. Nada de rastreamento em massa de perfis de usuários ou páginas de busca; busque o que você precisa para uma ação iniciada pelo usuário.

Transformando Dados de API em Custos

Gramas e segundos brutos viram dinheiro com um modelo de precificação — taxa de filamento por grama, taxa de máquina por hora, configuração por mesa, taxas de purga para multicolor e margem. É exatamente isso que esta plataforma calcula:

• REST: GET /api/scrape?url={makerworld_url} retorna o modelo mais um detalhamento completo de custos (referência).
• MCP: a ferramenta scrape_model faz o mesmo para agentes de IA (configuração).
• Navegador: cole qualquer URL do MakerWorld na calculadora para o resultado mesa por mesa.
• Licenciamento: verifique o campo license na referência de licenças antes de orçar trabalho comercial.

A documentação completa em nível de campo de nossa API (parâmetros, respostas, autenticação, créditos) está em /api, com a especificação legível por máquina em /openapi.yaml.