Guide de l'API MakerWorld : model detail, collections et endpoints de recherche (2026)

Existe-t-il une API publique MakerWorld ?

Réponse courte : aucune officielle. MakerWorld ne publie pas d'API avec des clés, des quotas ou de la documentation. Ce qui existe — et sur quoi repose tout outil tiers, y compris cette plateforme — ce sont les endpoints JSON internes qu'appellent l'application web de MakerWorld elle-même et Bambu Handy.

Ce guide documente les deux endpoints utilisés en production par MakerWorld Estimator, les champs de réponse sur lesquels vous pouvez compter, et les chemins de recherche qui fonctionnent réellement pour les développeurs. Considérez tout ce qui suit comme non documenté mais observable : les endpoints peuvent changer sans préavis, alors mettez toujours en cache et dégradez gracieusement.

Endpoint 1 : model detail

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

Le modelId est le nombre présent dans n'importe quelle URL de modèle :

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

Une requête curl minimale ressemble à ceci :

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'

Champs de réponse à connaître

Le tableau instances[]

Chaque instance est un profil d'impression — l'unité utile pour l'estimation du coût :

Le tableau plates est ce qui rend possible le calcul du coût par plateau — nombre de plateaux, poids par plateau, temps d'impression par plateau et couleurs par plateau. Si plates est absent, repliez-vous sur les totaux à l'échelle du profil.

Endpoint 2 : collections (favoris)

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

L'ID de collection est le nombre présent dans une URL de collection :

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

Cet endpoint renvoie les métadonnées de la collection (nom, créateur, description, couverture) plus la liste des designs qu'elle contient. C'est la base de l'estimation par lots — récupérez une fois, puis résolvez chaque design avec l'endpoint de détail du modèle (ou réutilisez les données en cache).

Notre propre flux par lots est documenté sur le guide de tarification des collections ; l'équivalent côté API est GET /api/scrape/collection?url={collectionUrl} sur l'API de l'estimateur.

Recherche : ce qui fonctionne à la place

La requête « MakerWorld search models endpoint » suppose une API de recherche publique. Il n'en existe aucune de documentée. La recherche du site est un appel interne utilisé par les propres clients de MakerWorld, sans contrat publié.

Pour une recherche programmatique, utilisez des chemins stables et conformes aux conditions d'utilisation :

1. Recherche dans l'annuaire de l'estimateur — GET /api/models?q={query}&sort={sort}&page={n} renvoie des modèles déjà en cache avec des coûts précalculés. Rapide, documenté et compatible avec le cache. Voir la référence API.
2. MCP list_models — le même catalogue pour les agents IA via le serveur MCP.
3. Votre propre index — si vous avez besoin du catalogue MakerWorld complet, construisez-le à partir d'IDs de modèles que vous collectez légitimement (vos propres uploads, les liens publics fournis par vos utilisateurs) et mettez en cache agressivement.

Évitez de marteler les endpoints de recherche internes : ils sont non documentés, limités en débit en pratique et fragiles.

Fiabilité, en-têtes et étiquette

• Envoyez des en-têtes de type navigateur. Referer, Origin, accept et un vrai user-agent comptent. Certains environnements sont identifiés et bloqués par Cloudflare indépendamment de cela — le serveur de dev local de cette plateforme bascule même sur curl pour cette raison.
• Réessayez avec backoff. Gérez 403, 429 et 5xx avec au minimum un unique réessai différé ; l'exponentiel est préférable.
• Mettez tout en cache. Les données de modèle changent rarement. Notre cache de production stocke des lignes par profil et sert les requêtes répétées depuis la mémoire/base de données ; un TTL raisonnable se compte en jours, pas en minutes.
• Délai d'expiration strict. Des timeouts de requête de 10 secondes empêchent un amont bloqué d'immobiliser vos workers.
• Soyez un bon citoyen. Pas de crawler en masse des profils d'utilisateurs ou des pages de recherche ; récupérez ce dont vous avez besoin pour une action déclenchée par un utilisateur.

Transformer les données de l'API en coûts

Des grammes et des secondes bruts deviennent de l'argent avec un modèle de prix — tarif du filament au gramme, tarif machine à l'heure, préparation par plateau, frais de purge pour le multicolore, et marge. C'est exactement ce que calcule cette plateforme :

• REST : GET /api/scrape?url={makerworld_url} renvoie le modèle plus une ventilation complète des coûts (référence).
• MCP : l'outil scrape_model fait de même pour les agents IA (configuration).
• Navigateur : collez n'importe quelle URL MakerWorld dans le calculateur pour le résultat plateau par plateau.
• Licences : vérifiez le champ license par rapport à la référence des licences avant de chiffrer un travail commercial.

La documentation complète champ par champ de notre API (paramètres, réponses, authentification, crédits) se trouve à /api, avec la spécification lisible par machine à /openapi.yaml.