Erreurs

Dans ce guide, nous verrons ce qui se passe lorsqu’un problème survient pendant que vous utilisez la Meshy API.

Erreurs de requête

Ces erreurs sont renvoyé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 s’est mal passé.

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

Erreurs de tâche

Ces erreurs se produisent après qu’une tâche a été créée et est en cours de traitement. Consultez l’objet task_error dans la réponse de la tâche pour obtenir 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 vous indique la catégorie générale de l’échec. Utilisez-le pour décider de 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.

Exemples courants :

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

Exemples d’entrées susceptibles d’être 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 le même 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, pâtés de maisons, intérieurs remplis de meubles ou paysages sont susceptibles de dépasser la capacité du modèle. Concentrez-vous plutôt sur un seul objet.
4. Évitez les structures répétitives denses. Les sujets comme les échafaudages, les maillages métalliques, les motifs en treillis ou les piles de nombreux petits éléments sont des déclencheurs courants.

model_missing_uv

Cette erreur se produit lorsque vous téléversez un modèle pour l’application de texture avec enable_original_uv défini sur true, mais que le modèle n’a pas de coordonnées UV. Les coordonnées UV définissent la manière dont une texture 2D s’enroule sur la surface 3D de votre modèle.

Résolution :

La bonne correction dépend de la raison pour laquelle vous avez défini enable_original_uv sur true :

• Si vous devez préserver la disposition UV d’origine de votre modèle (par exemple, un placement personnalisé des coutures pour un mappage de texture précis) : votre modèle doit avoir des coordonnées UV valides. Vérifiez que des UV existent dans l’éditeur UV de votre logiciel 3D avant le téléversement. Notez que les fichiers STL ne peuvent pas stocker de données UV ; utilisez donc plutôt GLB, FBX ou OBJ.
• Si vous n’avez pas besoin d’un contrôle UV spécifique (ou si vous n’êtes pas sûr) : omettez enable_original_uv ou définissez-le sur false. Le système générera automatiquement une disposition UV pour votre modèle. Les UV générées automatiquement sont optimisées pour la couverture, mais vous ne pourrez pas contrôler 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 faible pour un texturage de qualité. Cela arrive couramment avec des modèles exportés depuis des outils 3D qui génèrent des UV de substitution ou collapsés sans 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 îles UV sont correctement réparties dans l’espace UV plutôt que collapsées 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 de vos coutures d’origine, mais les UV générés automatiquement auront une couverture appropriée pour le texturage.

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 (p. ex., fichiers FBX ASCII, GLB compressé avec meshopt)
• Aucun objet 3D valide trouvé dans le modèle téléversé (p. ex., le fichier contient uniquement des armatures, des caméras ou des lumières)
• Contenu qui ne passe pas les filtres de sécurité

Résolution : Consultez le champ message pour obtenir des précisions sur ce qui s'est passé. Vérifiez que vos fichiers d'entrée et vos 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 toutes les images de référence ensemble.

Résolution :

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

timeout

Cette erreur signifie que le temps de traitement de votre tâche a dépassé la limite autorisée. Cela peut se produire en raison d’une charge système élevée ou parce que l’entrée est trop complexe à traiter dans la limite de temps.

Résolution :

1. Réessayez la requête. Les timeouts sont souvent transitoires et une nouvelle tentative 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 dans votre image ou votre prompt. Consultez image_too_complex pour obtenir des conseils sur les types d’entrées plus difficiles à traiter.

format_conversion_failed

Cette erreur se produit lorsque le modèle 3D généré n’a pas pu être converti au 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 autre format de sortie. Si un format spécifique continue d’échouer, passez à un autre format adapté à vos besoins.

Bonnes pratiques

1. Implémentez une logique de nouvelle tentative. Pour les erreurs timeout et service_unavailable, implémentez une logique de nouvelle tentative avec backoff exponentiel.
2. Journalisez les ID de tâche. Journalisez toujours l’ID de tâche à des fins de débogage. Incluez-le lorsque vous contactez le support.
3. Validez les entrées. Assurez-vous que vos images d’entrée et vos modèles respectent les exigences de format avant la soumission.