Erreurs

Dans ce guide, nous allons voir ce qui se passe lorsque quelque chose ne fonctionne pas correctement lorsque vous travaillez avec la Meshy API.

Erreurs de requête

Ces erreurs sont retournées immédiatement lorsque votre requête API est rejetée. Vérifiez le code de statut HTTP et le champ message pour comprendre ce qui n'a pas fonctionné.

{
  "message": "Invalid model file extension: .3dm"
}

Erreurs de Tâche

Ces erreurs surviennent après qu'une tâche a été créée et est en cours de traitement. Vérifiez l'objet task_error dans la réponse de la tâche pour les détails de l'erreur.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Types d'erreurs

Le champ type indique la catégorie générale de l'échec. Utilisez-le pour déterminer votre stratégie de nouvelle tentative.

Codes d'erreur

Lorsque le champ code est présent, il identifie un problème spécifique et exploitable. Vous trouverez ci-dessous la référence complète pour chaque code d'erreur.

image_too_complex

Cette erreur se produit lorsque l'image d'entrée ou le prompt décrit un sujet trop complexe géométriquement pour que le modèle de génération 3D puisse le traiter.

Des exemples courants incluent :

• Piles denses de petits objets (par exemple, une caisse pleine de fruits, une pile de livres)
• Motifs répétitifs complexes (par exemple, structures en treillis, échafaudages, treillis métalliques)
• Structures de bâtiments complexes (par exemple, bâtiments à plusieurs étages avec de nombreuses fenêtres et balcons)
• Plusieurs objets distincts dans une image au lieu d'un seul sujet

Exemples d'entrées probablement trop complexes :

Résolution :

1. Utilisez un seul objet par image. Le modèle fonctionne mieux avec un sujet clair. N'incluez pas plusieurs objets séparés dans la même image ou prompt.
2. Simplifiez votre sujet. Réduisez le niveau de détail. Par exemple, un vase simple au lieu d'un vase rempli de dizaines de fleurs.
3. Évitez les prompts au niveau de la scène. Les bâtiments entiers, les blocs de ville, les intérieurs remplis de meubles ou les paysages risquent de dépasser la capacité du modèle. Concentrez-vous sur un seul objet à la place.
4. Évitez les structures répétitives denses. Les sujets comme les échafaudages, les treillis métalliques, les motifs en treillis ou les piles de nombreux petits objets sont des déclencheurs courants.

model_missing_uv

Cette erreur se produit lorsque vous téléchargez un modèle pour texturer avec enable_original_uv réglé sur true, mais que le modèle n'a pas de coordonnées UV. Les coordonnées UV définissent comment une texture 2D s'enroule sur la surface 3D de votre modèle.

Résolution :

La bonne solution dépend de la raison pour laquelle vous avez réglé enable_original_uv sur true :

• Si vous devez préserver la disposition UV originale de votre modèle (par exemple, placement personnalisé des coutures pour un mappage de texture précis) : votre modèle doit avoir des coordonnées UV valides. Vérifiez que les UV existent dans l'éditeur UV de votre logiciel 3D avant de télécharger. Notez que les fichiers STL ne peuvent pas stocker de données UV, utilisez donc GLB, FBX ou OBJ à la place.
• Si vous n'avez pas besoin de contrôle spécifique sur les UV (ou si vous n'êtes pas sûr) : omettez enable_original_uv ou réglez-le sur false. Le système générera automatiquement une disposition UV pour votre modèle. Les UV générés automatiquement sont optimisés pour la couverture, mais vous n'aurez pas de contrôle sur l'emplacement des coutures de texture.

model_insufficient_uv

Cette erreur se produit lorsqu'un modèle possède des coordonnées UV, mais que la couverture UV est trop petite pour un texturage de qualité. Cela se produit couramment avec des modèles exportés à partir d'outils 3D qui génèrent des UV de remplacement ou effondrés sans un dépliage approprié.

Résolution :

• Si vous devez préserver votre disposition UV d'origine : redépliez les UV du modèle dans votre logiciel 3D. Assurez-vous que les îlots UV sont correctement répartis dans l'espace UV plutôt que d'être regroupés dans une petite zone.
• Si vous n'avez pas besoin d'un contrôle UV spécifique : omettez enable_original_uv ou définissez-le sur false. Le système générera automatiquement une nouvelle disposition UV. Le compromis est que vous perdez le placement original des coutures, mais les UV générées automatiquement auront une couverture appropriée pour le texturage.

model_missing_texture

Cette erreur se produit lorsque le modèle d'entrée d'une tâche Multi-Color Print ne contient aucune information de couleur que le convertisseur puisse séparer en couleurs d'impression. Un 3MF multicolore est construit à partir des couleurs du modèle, donc un maillage blanc uni — par exemple un aperçu Texte en 3D ou Image en 3D qui n'a jamais été texturé, ou une sortie réparée / auto-découpée — n'offre rien à exploiter.

Ce qui compte comme source de couleur dépend du style demandé :

• realistic échantillonne la texture de couleur de base à travers les coordonnées UV du modèle, ce qui nécessite une seule texture de couleur de base avec des coordonnées UV sur chaque partie du maillage.
• cartoon aplatit les couleurs par face et accepte une texture de couleur de base sur n'importe quelle partie ou des couleurs par sommet (COLOR_0).

Un modèle ne possédant ni texture de couleur de base ni couleurs de sommets est rejeté pour les deux styles ; avec cartoon, il « réussirait » sinon en tant qu'impression monochrome.

La plupart des requêtes sont refusées avant même la création de la tâche (400 Bad Request avec la même explication), donc vous ne verrez généralement ce code que lorsque l'entrée n'a pas pu être inspectée en amont — un fichier .fbx téléversé, par exemple, est vérifié une fois que la tâche l'a normalisé.

Résolution :

• Texturez d'abord le modèle. Exécutez une tâche Retexturisation dessus, ou générez-le avec la texturation activée (une tâche Texte en 3D en mode refine, ou une tâche Image en 3D avec should_texture: true), puis transmettez cette tâche en tant que input_task_id.
• Modèles avec couleurs de sommets (scans de photogrammétrie, maillages peints à la main) : demandez style: "cartoon", qui lit COLOR_0.
• Modèles partiellement texturés ou à textures multiples sous realistic : chaque partie du maillage a besoin de coordonnées UV et d'une seule et même texture de couleur de base. Texturez les parties restantes ou fusionnez les textures en un seul atlas, ou passez au style: "cartoon".

invalid_input

Il s'agit du code d'erreur de secours lorsque l'entrée échoue à la validation mais qu'aucun code plus spécifique ne s'applique. Le champ message contient la raison spécifique de l'échec.

Les causes courantes incluent :

• Fichiers de modèle vides ou corrompus
• Variations de format de fichier non prises en charge (par exemple, fichiers FBX ASCII, GLB compressés avec meshopt)
• Aucun objet 3D valide trouvé dans le modèle téléchargé (par exemple, le fichier ne contient que des armatures, des caméras ou des lumières)
• Contenu qui ne passe pas les filtres de sécurité

Résolution : Vérifiez le champ message pour des détails sur ce qui a mal tourné. Assurez-vous que vos fichiers d'entrée et paramètres correspondent aux exigences du point de terminaison.

moderation_blocked

Cette erreur se produit lorsque votre prompt ou vos images de référence sont rejetés par les filtres de sécurité de l'IA. Le filtre évalue à la fois le prompt textuel et les éventuelles images de référence.

Résolution :

• Reformulez votre prompt textuel pour supprimer les descriptions suggestives ou sensibles.
• Ajustez les images de référence si elles représentent un contenu susceptible de déclencher les filtres de sécurité.

timeout

Cette erreur signifie que la tâche a dépassé une limite de temps côté serveur, que ce soit pour le traitement ou pour l'attente dans la file d'attente ; la tâche a donc échoué et ses crédits ont été remboursés. Cela peut se produire en raison d'une charge système élevée ou parce que l'entrée est trop complexe pour être traitée dans le délai imparti.

Ceci est différent d'un timeout dans votre propre code. Si votre client a cessé d'attendre, la tâche est toujours en cours d'exécution ; consultez Task Lifecycle.

Résolution :

1. Créez à nouveau la tâche. Les timeouts sont souvent transitoires et une nouvelle tâche peut réussir.
2. Simplifiez votre entrée. Si les nouvelles tentatives continuent d'échouer, votre entrée est peut-être trop complexe. Essayez de réduire le niveau de détail de votre image ou de votre prompt. Consultez image_too_complex pour des conseils sur les types d'entrées les plus difficiles à traiter.

format_conversion_failed

Cette erreur se produit lorsque le modèle 3D généré n'a pas pu être converti dans le format de sortie demandé. Le modèle a été généré avec succès, mais l'étape de conversion a échoué.

Résolution :

1. Réessayez la requête.
2. Essayez un format de sortie différent. Si un format spécifique échoue systématiquement, passez à un autre format adapté à vos besoins.

Bonnes pratiques

1. Implémentez une logique de nouvelle tentative. Lorsqu'une tâche échoue avec une erreur timeout, service_unavailable ou server_error, recréez-la avec un backoff exponentiel. Si c'est votre propre requête qui a expiré, ne créez pas de nouvelle tâche : vérifiez d'abord celle existante (voir Cycle de vie d'une tâche).
2. Consignez les identifiants de tâche. Enregistrez toujours l'identifiant de la tâche à des fins de débogage. Incluez-le lorsque vous contactez le support.
3. Validez les entrées. Assurez-vous que vos images et modèles d'entrée respectent les exigences de format avant la soumission.