Erreurs

Découvrez pourquoi une requête ou une tâche a échoué, et ce qu'il faut faire ensuite. Une requête peut échouer immédiatement avec une erreur HTTP, et une tâche peut échouer plus tard avec une task_error.

Erreurs de requête

Meshy renvoie ces erreurs immédiatement, lorsqu'elle rejette une requête. Pour savoir ce qui n'a pas fonctionné, vérifiez le code de statut HTTP et le champ message.

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

Erreurs de tâche

Une tâche créée par Meshy peut tout de même échouer pendant son exécution. Son status devient FAILED, Meshy rembourse ses crédits, et task_error explique pourquoi.

{
  "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'erreur

type est la catégorie générale de l'échec. Utilisez-le pour décider de la marche à suivre.

Codes d'erreur

Lorsque code est présent, il désigne l'un des problèmes suivants.

image_too_complex

L'image d'entrée ou le prompt décrit un sujet trop complexe sur le plan géométrique pour la génération 3D.

Par exemple :

• Des amas denses de petits objets, comme une caisse pleine de fruits ou une pile de livres
• Des motifs répétitifs complexes, comme des structures en treillis, des échafaudages ou des grillages métalliques
• Des bâtiments complexes, comme des immeubles à plusieurs étages avec de nombreuses fenêtres et balcons
• Plusieurs objets distincts dans une seule image, au lieu d'un sujet unique

Ces entrées sont probablement trop complexes :

Pour résoudre ce problème, essayez une ou plusieurs des solutions suivantes :

• Utilisez un seul objet par image. Meshy fonctionne mieux avec un seul sujet clair, donc évitez de placer plusieurs objets distincts dans la même image ou le même prompt.
• Simplifiez votre sujet. Par exemple, utilisez un vase simple plutôt qu'un vase rempli de dizaines de fleurs.
• Évitez les scènes. Des bâtiments entiers, des pâtés de maisons, des pièces meublées et des paysages sont susceptibles d'être trop complexes. Concentrez-vous sur un seul objet.
• Évitez les structures répétitives denses. Les échafaudages, les grillages métalliques, les treillis et les amas de petits objets sont des déclencheurs fréquents.

model_missing_uv

Vous avez envoyé un modèle pour le texturage avec enable_original_uv défini sur true, mais le modèle ne possède pas de coordonnées UV. Les coordonnées UV définissent comment une texture 2D s'enroule sur la surface 3D.

Pour résoudre ce problème, effectuez l'une des opérations suivantes :

• Pour conserver la disposition UV propre à votre modèle, par exemple pour un placement personnalisé des coutures, ajoutez des UV au modèle dans votre logiciel 3D. Vérifiez-les dans son éditeur UV, puis téléchargez à nouveau le modèle. Les fichiers STL ne peuvent pas stocker d'UV, utilisez donc GLB, FBX ou OBJ.
• Si vous n'avez pas besoin de votre propre disposition, ou si vous n'êtes pas sûr, omettez enable_original_uv ou définissez-le sur false. Meshy crée alors une disposition UV pour le modèle. Les nouvelles UV couvrent bien le modèle, mais vous ne pouvez pas contrôler l'emplacement des coutures de la texture.

model_insufficient_uv

Le modèle possède des coordonnées UV, mais elles ne couvrent qu'une trop petite partie de l'espace UV pour permettre une bonne texturation. Cela arrive souvent avec des modèles dont l'exportateur a écrit des UV provisoires ou effondrées sans dépliage correct.

Pour corriger cela, procédez de l'une des manières suivantes :

• Pour conserver votre propre disposition UV, redépliez les UV du modèle dans votre logiciel 3D. Répartissez les îlots sur l'ensemble de l'espace UV au lieu de les regrouper dans un petit coin.
• Si vous n'avez pas besoin de votre propre disposition, omettez enable_original_uv ou définissez-le sur false. Meshy crée alors une nouvelle disposition UV. Vous perdez le placement de vos coutures, mais les nouvelles UV couvrent suffisamment d'espace pour la texturation.

model_missing_texture

Le modèle d'entrée d'une tâche Multi-Color Print n'a aucune couleur que Meshy peut répartir en couleurs d'impression. Meshy construit un fichier 3MF multicolore à partir des couleurs du modèle, donc un maillage blanc uni n'offre rien à exploiter. Par exemple, un aperçu Texte en 3D ou Image en 3D qui n'a jamais été texturé n'a pas de couleur. Il en va de même pour le résultat de Réparer l'imprimabilité, ou pour une tâche Auto Split qui n'a pas conservé la texture.

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

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

Meshy rejette un modèle qui n'a ni texture de couleur de base ni couleurs de sommet pour les deux styles, plutôt que de laisser cartoon le transformer en une impression monochrome.

Meshy refuse la plupart de ces requêtes avant même de créer la tâche, avec un code 400 et la même explication. Vous n'obtenez généralement ce code que lorsque Meshy ne peut pas vérifier l'entrée à l'avance. Par exemple, Meshy ne vérifie un fichier .fbx téléversé qu'après la conversion de la tâche.

Pour corriger cela, utilisez l'option adaptée à votre modèle :

• Texturez d'abord le modèle. Exécutez Retexturisation dessus, ou générez-le avec une tâche refine Texte en 3D ou une tâche Image en 3D avec should_texture: true. Envoyez ensuite cette tâche en tant que input_task_id.
• Pour un modèle à couleurs de sommet, comme un scan photogrammétrique ou un maillage peint à la main, utilisez style: "cartoon", qui lit COLOR_0.
• Pour un modèle partiellement texturé ou multi-texture avec realistic, attribuez des UV à chaque partie du maillage ainsi qu'une seule et même texture de couleur de base. Pour ce faire, texturez les parties restantes, ou fusionnez les textures en un seul atlas. Vous pouvez aussi passer à style: "cartoon".

textured_split_refused

Une tâche Auto Split avec keep_texture: true ne peut pas conserver la texture du modèle d'entrée sur les pièces. Par exemple, le modèle n'a pas d'UV, ou sa texture ne dispose pas d'espace pour les nouvelles faces créées par les découpes. Meshy rembourse les crédits.

Pour corriger cela, envoyez à nouveau la requête sans keep_texture, ou avec keep_texture: false. Les pièces reviennent alors chacune avec une couleur unie.

invalid_input

L'entrée a échoué à une vérification, et aucun code plus spécifique ne s'applique. message indique la raison.

Par exemple :

• Un fichier de modèle vide ou corrompu
• Une variante non prise en charge d'un format de fichier, comme un fichier FBX en ASCII ou un fichier GLB compressé avec meshopt
• Un modèle téléchargé sans objet 3D valide, par exemple un fichier contenant uniquement des armatures, des caméras ou des lumières
• Un contenu qui ne passe pas les filtres de sécurité

Pour corriger cela, consultez message pour connaître le problème précis. Vérifiez que vos fichiers d'entrée et vos paramètres respectent les exigences du point de terminaison.

moderation_blocked

Les filtres de sécurité ont rejeté votre prompt ou vos images de référence. Les filtres vérifient le texte et les images ensemble.

Pour résoudre ce problème, effectuez l'une ou l'autre des actions suivantes (ou les deux) :

• Reformulez le prompt pour supprimer les descriptions suggestives ou sensibles.
• Changez les images de référence qui montrent un contenu susceptible d'être bloqué par les filtres.

moderation_unavailable

Type : server_error. La moderation de contenu était temporairement indisponible, donc Meshy a fait échouer la tâche plutôt que d'ignorer la vérification. Il n'y a rien d'anormal avec votre contenu.

Pour résoudre ce problème, créez à nouveau la tâche.

timeout

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, Meshy l'a donc fait échouer et a remboursé ses crédits. Une charge élevée, ou une entrée trop complexe pour être traitée dans les délais, peut en être la cause.

Ceci est différent d'un timeout dans votre propre code. Si votre client a arrêté d'attendre, la tâche continue de s'exécuter. Voir Combien de temps attendre.

Pour corriger ce problème, suivez ces étapes :

1. Recréez la tâche. Les timeouts sont souvent temporaires, et une nouvelle tâche peut réussir.
2. Si l'échec persiste, simplifiez votre entrée, par exemple en réduisant le niveau de détail de votre image ou de votre prompt. Pour les entrées plus difficiles à traiter, voir image_too_complex.

queue_timeout

Type : timeout. La tâche a attendu trop longtemps dans la file d'attente sans démarrer, Meshy l'a donc fait échouer et a remboursé les crédits facturés pour celle-ci. Votre saisie n'est pas à l'origine de cette erreur.

Pour corriger ce problème, recréez la tâche.

format_conversion_failed

Meshy a généré le modèle, mais sa conversion vers un format que vous avez demandé a échoué.

Pour corriger ce problème, suivez ces étapes :

1. Recréez la tâche.
2. Si un format échoue systématiquement, demandez un format différent adapté à vos besoins.

Bonnes pratiques

• Réessayez les tâches échouées. Pour une tâche échouée avec timeout, service_unavailable ou server_error, créez une nouvelle tâche avec un backoff exponentiel.
• Ne créez pas de nouvelle tâche lorsque votre propre requête expire. La première tâche pourrait encore être en cours d'exécution, vérifiez donc si elle existe avant d'en créer une autre. Consultez Combien de temps attendre.
• Journalisez les ID de tâches. Incluez l'ID lorsque vous contactez le support.
• Vérifiez les entrées avant de les envoyer. Assurez-vous que les images et les modèles respectent les exigences de format du point de terminaison.
• Appelez l'API depuis votre serveur. Le code exécuté dans un navigateur expose votre clé API à quiconque ouvre la page.