lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

Erreurs

Découvrez pourquoi une requête ou une tâche a échoué, et ce qu'il convient de 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'il rejette une requête. Pour savoir ce qui n'a pas fonctionné, vérifiez le code de statut HTTP et le champ message.

Format de la réponse

La réponse d'erreur contient un champ message qui décrit ce qui n'a pas fonctionné :

  • Name
    message
    Type
    string
    Description

    Une courte description de l'erreur.

Codes de statut

  • Name
    2xx
    Description

    Succès.

    • Name
      200 - OK
      Description

      La requête a fonctionné.

    • Name
      202 - Accepted
      Description

      Meshy a accepté la requête, et le traitement n'est pas encore terminé. Par exemple, une requête qui crée une tâche renvoie 202.

  • Name
    4xx
    Description

    Quelque chose ne va pas avec la requête ou votre compte. Chaque statut indique quoi faire.

    • Name
      400 - Bad Request
      Description

      La requête n'est pas valide, souvent parce qu'un paramètre requis est manquant ou qu'un paramètre est mal formé.

    • Name
      401 - Unauthorized
      Description

      La clé API est manquante, n'est pas valide, ou ne peut pas accéder à ce point de terminaison. Voir Authentification.

    • Name
      402 - Payment Required
      Description

      Le compte de la clé API n'a pas assez de crédits pour la requête. Dans le plan gratuit, la plupart des requêtes qui créent une tâche renvoient aussi 402.

    • Name
      403 - Forbidden
      Description

      Vous n'êtes pas autorisé à effectuer cette requête, par exemple pour l'une de ces raisons :

      • La requête provenait d'une adresse en dehors de la liste d'autorisation IP de la clé API.
      • Le filtrage IP de votre organisation a bloqué les fichiers d'une tâche lors de sa lecture.
      • Le point de terminaison n'est pas disponible sur votre plan.
      • La modération de contenu a bloqué l'entrée. Certains points de terminaison renvoient 400 pour cela à la place ; chaque page de point de terminaison liste ses codes.
      • La clé API appartient à un membre d'équipe qui n'est plus actif dans l'équipe.
      • Le compte est banni.
    • Name
      404 - Not Found
      Description

      La ressource n'existe pas. Par exemple, obtenir une tâche avec un ID qui n'existe pas renvoie 404.

    • Name
      409 - Conflict
      Description

      La ressource existe, mais son état ne permet pas l'opération. Par exemple, supprimer une tâche IN_PROGRESS renvoie 409, car Meshy ne peut pas rembourser une tâche qu'un worker a commencée. La tâche continue de s'exécuter. Attendez un statut final (SUCCEEDED, FAILED, ou CANCELED), puis supprimez la tâche.

    • Name
      422 - Unprocessable Entity
      Description

      La requête est valide, mais Meshy ne peut pas traiter son entrée. Par exemple, Rigging renvoie 422 lorsqu'il ne trouve pas de corps humanoïde dans le modèle.

    • Name
      429 - Too Many Requests
      Description

      Vous avez envoyé trop de requêtes, ou trop de vos tâches sont en file d'attente ou en cours d'exécution. Lorsque la réponse contient un en-tête Retry-After, attendez ce nombre de secondes, puis réessayez. Voir Limites de débit.

  • Name
    5xx
    Description

    Quelque chose s'est mal passé du côté de Meshy. Réessayez avec un délai croissant. Si l'erreur persiste, consultez la page de statut et contactez-nous sur Discord.

Example: 400 Bad Request

{
  "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.

Le task_error d'une tâche échouée comporte les champs suivants :

  • Name
    type
    Type
    string
    Description

    La catégorie de l'erreur. Elle est toujours présente sur une tâche échouée. Basez-vous dessus pour décider de retenter ou non. Voir Types d'erreurs.

  • Name
    message
    Type
    string
    Description

    Une description de l'erreur lisible par un humain. Elle est toujours présente sur une tâche échouée.

  • Name
    code
    Type
    string
    Optionnel
    Description

    Un problème spécifique et documenté sur lequel vous pouvez agir. Présent lorsque Meshy dispose de plus de détails. Voir Codes d'erreur. Meshy peut ajouter de nouveaux codes, donc gérez un code que vous ne reconnaissez pas en vous basant sur son type.

  • Name
    doc_url
    Type
    string
    Optionnel
    Description

    Un lien vers l'entrée du code sur cette page, qui indique quoi faire. Présent lorsque code est présent.

Error with details

{
  "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"
  }
}

Error without details

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

Error types

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

  • Name
    invalid_input
    Description

    Il y a un problème avec l'entrée que vous avez envoyée. Lisez code et message, corrigez l'entrée, puis créez une nouvelle tâche.

  • Name
    timeout
    Description

    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, et a échoué. Meshy rembourse les crédits correspondants. Il s'agit souvent d'un problème temporaire. Créez à nouveau la tâche, et si l'échec persiste, essayez une entrée plus simple.

  • Name
    service_unavailable
    Description

    Le service était temporairement indisponible. Patientez un instant, puis créez à nouveau la tâche.

  • Name
    server_error
    Description

    Un problème est survenu du côté de Meshy pendant l'exécution de la tâche. Créez à nouveau la tâche. Si l'échec persiste, contactez le support en indiquant l'ID de la tâche.


Codes d'erreur

Lorsque le champ 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 géométriquement pour la génération 3D.

Par exemple :

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

Ces entrées sont probablement trop complexes :

A crate of mixed berriesAn intricate cathedral ceilingA building under construction with scaffoldingA honeycomb lattice sphere

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 clairement défini, donc ne placez pas plusieurs objets distincts dans la même image ou le même prompt.
  • Simplifiez votre sujet. Par exemple, utilisez un simple vase 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 probablement trop complexes. Concentrez-vous sur un seul objet.
  • Évitez les structures répétitives denses. Les échafaudages, mailles métalliques, treillis et amas de petits objets sont des déclencheurs fréquents.

model_missing_uv

Vous avez envoyé un modèle pour la texturation avec enable_original_uv réglé sur true, mais le modèle ne possède pas de coordonnées UV. Les coordonnées UV définissent la façon dont une texture 2D s'enroule autour de la surface 3D.

No UVs vs Good UVs

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

  • Pour conserver la propre disposition UV de 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 réglez-le sur false. Meshy crée alors une disposition UV pour le modèle. Les nouveaux 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 celles-ci couvrent une portion trop réduite de l'espace UV pour permettre une bonne texture. Cela se produit souvent avec des modèles dont l'exportateur a écrit des UV provisoires ou aplaties, sans déploiement correct.

Insufficient UVs vs Good UVs

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

  • Pour conserver votre propre disposition UV, redéployez les UV du modèle dans votre logiciel 3D. Répartissez les îlots sur l'ensemble de l'espace UV au lieu de les concentrer dans un petit coin de celui-ci.
  • 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 un espace suffisant pour la texture.

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 3MF multicolore à partir des couleurs du modèle, donc un maillage blanc uni n'a 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 la sortie de Réparer l'imprimabilité, ou 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 nécessite 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 sommets pour les deux styles, plutôt que de laisser cartoon le transformer en impression monochrome.

Meshy refuse la plupart de ces requêtes avant même de créer la tâche, avec un 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 envoi .fbx qu'après que la tâche l'a converti.

Pour corriger cela, utilisez l'option qui convient à 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 avec couleurs de sommets, 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, donnez à chaque partie du maillage des UV et la même texture de couleur de base unique. Pour cela, texturez les parties restantes, ou fusionnez les textures en un seul atlas. Vous pouvez aussi basculer vers style: "cartoon".

textured_split_refused

Une tâche d'Auto Split avec keep_texture: true ne parvient pas à conserver la texture du modèle d'entrée sur les parties. Par exemple, le modèle n'a pas d'UV, ou sa texture ne dispose pas de place 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 parties sont alors renvoyées avec chacune 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éversé 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, lisez 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 des actions suivantes, ou les deux :

  • Reformulez le prompt pour supprimer les descriptions suggestives ou sensibles.
  • Changez les images de référence montrant un contenu que les filtres pourraient bloquer.

moderation_unavailable

Type : server_error. La moderation du contenu était temporairement indisponible, Meshy a donc fait échouer la tâche plutôt que d'ignorer la vérification. Rien n'est en cause dans 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, et Meshy l'a donc fait échouer et a remboursé ses crédits. Une forte charge, ou une entrée trop complexe pour être traitée à temps, peut en être la cause.

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. Voir Combien de temps attendre.

Pour corriger cela, suivez ces étapes :

  1. Recréez la tâche. Les timeouts sont souvent temporaires, et une nouvelle tâche pourrait 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é tous les crédits facturés pour celle-ci. Votre saisie n'est pas à l'origine de cette erreur.

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

format_conversion_failed

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

Pour résoudre ce problème, suivez ces étapes :

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

Bonnes pratiques

  • Relancez 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 peut 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.
  • Consignez les ID des 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 à toute personne qui ouvre la page.