Guide d'utilisation de l'API Image to 3D Model : Guide complet 2026

L'API Image vers modèle 3D transforme une seule photo en modèle 3D prêt pour la production en quelques secondes—sans modélisation manuelle. Modéliser chaque actif à la main est lent et coûteux, et pour les studios de jeux, les applications de réalité augmentée et les équipes e-commerce, cela devient rapidement le goulot d'étranglement qui retarde les lancements. L'API Image vers modèle 3D de Meshy supprime cette friction : envoyez une image, convertissez-la en modèle 3D en quelques secondes, et téléchargez un maillage entièrement texturé dans des formats comme GLB, FBX et OBJ. Ce guide vous accompagne dans l'ensemble du flux de travail—de la création de votre clé API au téléchargement de votre premier modèle—avec du code prêt à copier-coller que vous pouvez exécuter en quelques minutes.

Qu'est-ce que l'API Image vers modèle 3D ?

À la base, l'API Image vers modèle 3D est un point de terminaison REST alimenté par l'IA Image vers modèle 3D de Meshy. Vous envoyez une seule image (JPG, JPEG ou PNG) sous forme d'URL publique ou de chaîne base64, et l'API renvoie un modèle 3D texturé—géométrie et textures de couleur de base incluses—dans des formats standard comme GLB, FBX, OBJ, USDZ, STL et 3MF. Des options complémentaires incluent les cartes PBR, des textures jusqu'en 4K et des vignettes d'aperçu multi-angles.

Alimentée par notre dernier modèle Meshy 6, l'API vous permet de configurer la topologie et le nombre de polygones, de définir les modes de pose et de guider la texturation avec une invite textuelle ou une image de référence—idéale pour générer des actifs pour les jeux, la réalité augmentée/réalité virtuelle, l'impression 3D et la visualisation de produits.

De quoi avez-vous besoin pour utiliser l'API Image vers 3D ?

Vous n'avez pas besoin de grand-chose pour suivre ce guide. Assurez-vous d'avoir :

• Un compte Meshy — inscrivez-vous gratuitement si vous n'en avez pas. Vous générerez votre clé API depuis le tableau de bord à l'étape 1.

• Une clé API — utilisée pour authentifier chaque requête. Nous allons vous guider dans la création d'une clé, et vous pouvez utiliser la clé de mode test gratuite pour suivre sans dépenser de crédits.

• Une image d'entrée — un fichier .jpg, .jpeg ou .png clair hébergé à une URL accessible publiquement (ou encodé en base64). Un arrière-plan propre et un sujet clairement visible donnent les meilleurs résultats.

• Un moyen d'effectuer des requêtes HTTP — curl (utilisé dans les exemples ci-dessous), Postman, ou toute bibliothèque HTTP dans le langage de votre choix. Une familiarité de base avec les API REST et JSON est utile mais pas obligatoire.

C'est tout—aucune expérience en modélisation 3D n'est nécessaire. Commençons.

Comment convertir une image en modèle 3D avec l'API (Guide étape par étape)

Étape 1 : Configurer vos paramètres API

Tout ce dont vous avez besoin pour commencer à construire se trouve sur la page des paramètres API. C'est votre centre de contrôle pour l'API Meshy, et elle comporte trois sections clés :

• Clés API — générez et gérez les clés qui authentifient vos requêtes.

• Webhooks — soyez notifié automatiquement lorsque vos tâches se terminent.

• Utilisation — suivez votre solde de crédits restants et votre consommation API en temps réel.

Parcourons chacune d'elles.

Obtenez votre clé API

Avant d'effectuer des requêtes, vous avez besoin d'une clé API pour vous authentifier de manière sécurisée. Sur la page des paramètres API, cliquez sur Générer une clé API. Chaque clé suit le format msy-<chaîne-aléatoire>.

Conseil : Une fois générée, stockez votre clé API dans un endroit sécurisé (par exemple, un gestionnaire de mots de passe ou une variable d'environnement). Traitez-la comme un mot de passe—ne la commettez jamais dans un système de contrôle de version et ne l'exposez pas dans du code côté client.

Clé API de mode test

Pendant le développement et les tests, vous pouvez utiliser la clé API de mode test pour explorer l'API sans consommer vos crédits :

msy_dummy_api_key_for_test_mode_12345678

Cette clé spéciale a les caractéristiques suivantes :

• Elle peut être utilisée pour effectuer des requêtes vers tous les points de terminaison de l'API Meshy.

• Aucun crédit n'est consommé lors de l'utilisation de cette clé.

• Toutes les requêtes valides renvoient le même résultat de tâche exemple, quels que soient les paramètres d'entrée.

• La structure des données de réponse correspond exactement à celle de l'API de production.

Cela la rend parfaite pour tester votre intégration avant de passer à votre vraie clé API.

Configurer des webhooks (Optionnel)

La génération d'un modèle 3D prend du temps, donc au lieu d'interroger l'API à plusieurs reprises pour vérifier si une tâche est terminée, vous pouvez laisser Meshy vous notifier dès qu'elle se termine. C'est à cela que servent les webhooks.

Dans la section Webhooks de la page des paramètres, ajoutez une URL de point de terminaison où Meshy doit envoyer les notifications d'événements. Lorsqu'une tâche change de statut (par exemple, lorsqu'elle se termine ou échoue), Meshy envoie une requête HTTP POST à votre URL avec les détails de la tâche dans la charge utile.

Conseil : Les webhooks sont l'approche recommandée pour la production. Ils réduisent les appels API inutiles et permettent à votre application de réagir aux résultats en temps réel. Pour les tests rapides, l'interrogation fonctionne également très bien. Pour tester le code webhook localement, pointez-le vers une URL proxy d'un service comme smee.io.

Essayez sans code — Bac à sable API (Optionnel)

Vous avez déjà votre clé API ? Avant d'écrire du code, vous pouvez exécuter une vraie tâche Image vers 3D directement dans votre navigateur.

Ouvrez meshy.ai/api-playground, sélectionnez Image vers 3D dans le panneau de gauche, et remplissez trois choses :

1. Autorisation — collez votre clé API (msy-xxxxxxxxxx)

2. Image — téléchargez un fichier .jpg, .jpeg ou .png depuis votre ordinateur

3. Appuyez sur Envoyer

Le Bac à sable soumet la tâche et interroge les résultats automatiquement. Une fois terminé, vous verrez l'aperçu du modèle 3D et les liens de téléchargement directement dans le navigateur — sans code requis.

Conseil de pro : Le panneau de requête/réponse brute sur la droite montre exactement ce que l'API envoie et renvoie. Vous pouvez copier le contenu directement — récupérez le task_id de la réponse, et les model_urls une fois la tâche terminée. Vous utiliserez les deux dans les prochaines étapes.

Étape 2 : Soumettre une tâche Image vers 3D

Avec votre clé API prête, lancez une tâche avec une seule requête POST :

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Vous obtiendrez une réponse comme celle-ci :

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Cette valeur result est votre task_id — conservez-la. Vous en aurez besoin à l'étape suivante pour vérifier la progression et récupérer votre modèle.

Optionnel : Pour être notifié automatiquement lorsque la tâche se termine, ajoutez un champ webhook_url au corps JSON—par exemple "webhook_url": "https://yourapp.com/webhooks/meshy". Voir l'étape 3, Option B pour son fonctionnement.

Étape 3 : Obtenir vos résultats

Votre tâche ne se termine pas instantanément—Meshy la traite en arrière-plan. Vous avez deux façons d'obtenir le résultat :

Option A : Interroger le statut (La plus simple)

Envoyez une requête GET toutes les 5 secondes jusqu'à ce que status passe à SUCCEEDED :

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

La réponse ressemble à ceci :

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Quelques champs utiles à connaître :

• model_urls contient un lien de téléchargement pour chaque format généré. Par défaut, cela inclut glb, fbx, obj, usdz, stl et mtl (le fichier de matériau qui accompagne obj).

• model_url est un raccourci vers le lien GLB—pratique lorsque vous n'avez besoin que du GLB.

• consumed_credits indique le nombre de crédits utilisés par la tâche (c'est 0 pour les tâches échouées, car les crédits sont remboursés).

• thumbnail_url est toujours présent et pointe vers la vignette de face.

• thumbnail_urls apparaît uniquement lorsque multi_view_thumbnails: true, et contient les vues de face, droite, arrière et gauche.

• alpha_thumbnail_url apparaît uniquement lorsque alpha_thumbnail: true, et contient la vignette avec fond transparent.

Valeurs possibles de status : PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Option B : Webhook (Recommandé pour la production)

Si vous avez défini un webhook_url à l'étape 2, Meshy enverra l'objet de la tâche terminée à votre URL automatiquement—pas besoin d'interrogation.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Lequel utiliser ? L'interrogation est parfaite pour le prototypage et les tâches ponctuelles. Utilisez les webhooks en production — c'est plus fiable et économise les appels API.

Étape 4 : Télécharger votre modèle 3D

Une fois que status est SUCCEEDED, récupérez les URL de téléchargement depuis model_urls et téléchargez le format dont vous avez besoin :

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Le drapeau -o model.glb enregistre le fichier dans votre répertoire de travail actuel sous ce nom—utilisez un chemin complet (par exemple -o /path/to/model.glb) pour l'enregistrer ailleurs.

Par défaut, chaque tâche renvoie GLB, FBX, OBJ, USDZ, STL et MTL (le fichier de matériau pour OBJ). 3MF est optionnel—vous ne l'obtenez que lorsque vous le demandez explicitement via target_formats (voir le tableau des paramètres ci-dessous).

⚠️ Les liens expirent dans 3 jours (les plans Entreprise ont des liens permanents). Téléchargez et stockez vos modèles rapidement — les liens ne fonctionneront plus après l'expiration, et vous devrez relancer la tâche.

Prêt à utiliser ce modèle dans votre outil DCC ? Consultez le guide Bridge vers Blender—Meshy propose également des bridges pour Unity, Unreal, Maya, et plus encore.

Comment obtenir les meilleurs résultats image-vers-3D ?

• Utilisez un sujet unique et clairement visible. Un objet principal, centré et entièrement dans le cadre, donne à l'IA la référence la plus propre—évitez les scènes chargées, les recadrages importants et les angles extrêmes.

• Préférez un arrière-plan propre et sans encombrement. Les arrière-plans unis ou simples aident le modèle à séparer le sujet de son environnement.

• Utilisez un éclairage diffus et uniforme. Les ombres dures et les reflets forts peuvent intégrer des détails trompeurs dans la texture générée.

• Commencez avec une image nette et haute résolution. Plus de détails en entrée équivaut à plus de détails en sortie—les entrées floues ou basse résolution produisent des modèles plus mous.

Quels langages de programmation puis-je utiliser avec l'API Image vers 3D ?

Tout langage capable d'effectuer des requêtes HTTP—vous envoyez un POST avec du JSON et interrogez avec GET. Options courantes :

• Python — utilisez la bibliothèque requests ou httpx

• JavaScript / TypeScript — utilisez fetch (intégré) ou axios

• Go — utilisez net/http de la bibliothèque standard

• cURL — idéal pour des tests rapides depuis le terminal

Vous pouvez également trouver des exemples de code prêts à copier pour les quatre dans le Bac à sable API.

Combien de crédits coûte une tâche Image vers 3D ?

Le coût dépend de la version du modèle et du fait que vous génériez des textures. La configuration par défaut (meshy-6 avec texturation) coûte 30 crédits par tâche :

Les tâches échouées sont automatiquement remboursées—consumed_credits renvoie 0. Vérifiez toujours la Tarification pour les tarifs les plus récents.

Quels paramètres l'API Image vers 3D accepte-t-elle ?

Envoyez un POST vers /openapi/v1/image-to-3d avec ces paramètres : Requis (un parmi) :

Optionnel :

Prochaines étapes avec l'API Image vers 3D

Vous avez maintenant le flux de travail complet : créez une clé API, soumettez une image, interrogez ou utilisez un webhook pour le résultat, puis téléchargez votre modèle. Les mêmes quatre étapes passent à l'échelle d'un prototype rapide à un pipeline de production qui transforme automatiquement des milliers d'images en actifs 3D. Récupérez votre clé depuis la page des paramètres API et expédiez votre premier modèle dès aujourd'hui. Vous préférez commencer par une invite plutôt qu'une photo ? Utilisez l'API Texte vers modèle 3D.

Foire aux questions

Comment convertir une image en modèle 3D via l'API ?

Envoyez une requête POST vers /openapi/v1/image-to-3d avec votre image_url et votre clé API, puis interrogez la tâche (ou utilisez un webhook) jusqu'à ce que son status soit SUCCEEDED. La réponse renvoie des liens de téléchargement pour le modèle généré. Le flux complet en quatre étapes—clé, soumission, récupération, téléchargement—est couvert dans le guide étape par étape ci-dessus.

Quels formats de sortie (STL, GLB, OBJ) l'API prend-elle en charge ?

Chaque tâche renvoie GLB, FBX, OBJ, USDZ, STL et MTL par défaut, avec 3MF disponible sur demande via target_formats. GLB est idéal pour le web et la réalité augmentée, FBX et OBJ pour les outils DCC et les moteurs de jeu, USDZ pour la réalité augmentée iOS, et STL pour l'impression 3D.

Quels formats d'image puis-je télécharger ?

L'API Image vers 3D prend en charge les images JPG, JPEG et PNG jusqu'à 100 Mo—plus grande que la limite de 20 Mo dans l'interface utilisateur de l'Espace de travail Meshy. Pour les résultats les plus précis, utilisez un PNG avec un fond transparent ou blanc propre, ce qui aide l'API à isoler le sujet et à générer un modèle 3D de meilleure qualité.

Puis-je obtenir un modèle 3D texturé depuis l'API ?

Oui. La texturation est activée par défaut ("should_texture": true). Pour ajouter des cartes PBR (métallique, rugosité, normale), définissez "enable_pbr": true—sur meshy-6/latest, cela inclut également une carte d'émission. Pour une texture de couleur de base en 4K, définissez "hd_texture": true (pris en charge uniquement sur meshy-6/latest ; les cartes PBR restent en 2K). Vous pouvez également orienter le style de texture avec un texture_prompt ou un texture_image_url.

Puis-je générer un modèle 3D prêt pour l'impression 3D (STL) ?

Oui—STL est généré par défaut, donc une conversion image vers 3D STL ne nécessite aucun paramètre supplémentaire : récupérez simplement model_urls.stl lorsque la tâche se termine. Cela simplifie les flux de travail image vers impression 3D, car STL est le format standard attendu par les slicers. Si vous voulez uniquement STL, définissez "target_formats": ["stl"] pour ignorer les autres formats et réduire le temps de génération.

Quels plans incluent l'accès à l'API ?

L'accès à l'API est disponible sur les plans Pro, Studio et Entreprise—c'est une fonctionnalité à partir de Pro. Le plan Starter gratuit n'inclut pas l'accès à l'API. Voir Tarification pour les détails.

Combien de temps les liens de téléchargement sont-ils valides ?

Les liens de téléchargement sont valides pendant 3 jours sur les plans Pro et Studio. Les clients Entreprise bénéficient de liens permanents. Enregistrez vos fichiers rapidement—les liens expirés ne peuvent pas être récupérés, et vous devrez relancer la tâche.

Puis-je exécuter plusieurs tâches en même temps ?

Oui, les requêtes simultanées sont prises en charge. Si vous rencontrez une erreur 429 Too Many Requests, votre compte a atteint sa limite de débit—implémentez un backoff exponentiel et réessayez. Consultez la page Limites de débit pour les limites de votre plan.

La tâche affiche FAILED — que dois-je faire ?

Vérifiez task_error.message pour la cause. Les plus courantes :

Si le problème persiste, contactez le support Meshy.