Fouten

Ontdek waarom een aanvraag of een taak is mislukt, en wat u vervolgens moet doen. Een aanvraag kan direct mislukken met een HTTP-fout, en een taak kan later mislukken met een task_error.

Verzoekfouten

Meshy geeft deze fouten direct terug wanneer het een verzoek weigert. Om te achterhalen wat er mis is gegaan, controleer je de HTTP-statuscode en het message-veld.

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

Taakfouten

Een taak die Meshy heeft aangemaakt kan nog steeds mislukken tijdens het uitvoeren. De status wordt FAILED, Meshy betaalt de credits terug, en task_error legt uit waarom.

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

Foutsoorten

type is de brede categorie van de fout. Gebruik dit om te bepalen wat je vervolgens moet doen.

Foutcodes

Wanneer code aanwezig is, benoemt het een van de volgende problemen.

image_too_complex

De invoerafbeelding of prompt beschrijft een onderwerp dat geometrisch te complex is voor 3D-generatie.

Bijvoorbeeld:

• Dichte stapels kleine objecten, zoals een krat vol fruit of een stapel boeken
• Ingewikkelde repeterende patronen, zoals rasterconstructies, steigers of draadgaas
• Complexe gebouwen, zoals gebouwen met meerdere verdiepingen met veel ramen en balkons
• Meerdere afzonderlijke objecten in één afbeelding, in plaats van één enkel onderwerp

Deze invoer is waarschijnlijk te complex:

Probeer, om dit op te lossen, een of meer van de volgende suggesties:

• Gebruik één object per afbeelding. Meshy werkt het best met één duidelijk onderwerp, dus plaats geen meerdere losse objecten in dezelfde afbeelding of prompt.
• Vereenvoudig je onderwerp. Gebruik bijvoorbeeld een eenvoudige vaas in plaats van een vaas vol met tientallen bloemen.
• Vermijd scènes. Hele gebouwen, stadsblokken, ingerichte kamers en landschappen zijn waarschijnlijk te veel. Focus op één enkel object.
• Vermijd dichte repeterende structuren. Steigers, draadgaas, rasterconstructies en stapels kleine items vormen veelvoorkomende struikelblokken.

model_missing_uv

Je hebt een model voor het aanbrengen van texturen verzonden met enable_original_uv ingesteld op true, maar het model heeft geen UV-coördinaten. UV-coördinaten bepalen hoe een 2D-textuur om het 3D-oppervlak wordt gewikkeld.

Om dit te verhelpen, doe je een van de volgende dingen:

• Om de eigen UV-layout van je model te behouden, bijvoorbeeld voor aangepaste naadplaatsing, voeg je UV's toe aan het model in je 3D-software. Controleer ze in de UV-editor van die software en upload het model vervolgens opnieuw. STL-bestanden kunnen geen UV's opslaan, gebruik dus GLB, FBX of OBJ.
• Als je geen eigen layout nodig hebt, of als je het niet zeker weet, laat je enable_original_uv weg of stel je deze in op false. Meshy maakt dan een UV-layout voor het model. De nieuwe UV's bedekken het model goed, maar je kunt niet bepalen waar de textuurnaden komen te liggen.

model_insufficient_uv

Het model heeft UV-coördinaten, maar deze bedekken te weinig van de UV-ruimte om goed te texturen. Dit gebeurt vaak bij modellen waarvan de exporter placeholder of ingestorte UV's heeft geschreven zonder een juiste unwrap.

Om dit op te lossen, doe een van de volgende dingen:

• Om je eigen UV-layout te behouden, unwrap de UV's van het model opnieuw in je 3D-software. Verspreid de eilanden over de UV-ruimte in plaats van een klein hoekje ervan.
• Als je je eigen layout niet nodig hebt, laat enable_original_uv weg of zet deze op false. Meshy maakt dan een nieuwe UV-layout aan. Je verliest je naadplaatsing, maar de nieuwe UV's bedekken voldoende ruimte om te texturen.

model_missing_texture

Het invoermodel van een Multi-Color Print-taak heeft geen kleur die Meshy kan opsplitsen in printkleuren. Meshy bouwt een meerkleuren-3MF op basis van de kleuren van het model, dus een gewone witte mesh biedt niets om mee te werken. Zo heeft bijvoorbeeld een Tekst naar 3D- of Afbeelding naar 3D-preview die nooit is voorzien van een textuur geen kleur. Datzelfde geldt voor de output van Printbaarheid repareren, of een Auto Split-taak waarbij de textuur niet behouden bleef.

Wat als kleur telt, hangt af van de style die je hebt opgegeven:

• realistic bemonstert de basiskleurtextuur via de UV's van het model. Dit vereist één enkele basiskleurtextuur, en UV's op elk mesh-onderdeel.
• cartoon maakt kleuren per vlak vlak (flattening). Dit accepteert een basiskleurtextuur op elk onderdeel, of kleuren per vertex (COLOR_0).

Meshy wijst een model zonder basiskleurtextuur én zonder vertex-kleuren af voor beide stijlen, in plaats van cartoon er een eenkleurige print van te laten maken.

Meshy weigert de meeste van deze verzoeken al voordat de taak wordt aangemaakt, met een 400 en dezelfde uitleg. Je krijgt deze code meestal alleen wanneer Meshy de invoer niet vooraf kan controleren. Zo controleert Meshy een .fbx-upload bijvoorbeeld pas nadat de taak deze heeft geconverteerd.

Om dit op te lossen, gebruik je de optie die bij je model past:

• Voorzie het model eerst van een textuur. Voer Hertextureren erop uit, of genereer het met een Tekst naar 3D refine-taak of een Afbeelding naar 3D-taak met should_texture: true. Stuur die taak vervolgens door als input_task_id.
• Gebruik voor een model met vertex-kleuren, zoals een fotogrammetrie-scan of een handbeschilderde mesh, style: "cartoon", die COLOR_0 uitleest.
• Geef voor een gedeeltelijk getextureerd model of een model met meerdere texturen met realistic elk mesh-onderdeel UV's en dezelfde enkele basiskleurtextuur. Doe dit door de resterende onderdelen van een textuur te voorzien, of door de texturen samen te voegen tot één atlas. Je kunt ook overschakelen naar style: "cartoon".

textured_split_refused

Een Auto Split-taak met keep_texture: true kan de textuur van het invoermodel niet behouden op de onderdelen. Het model heeft bijvoorbeeld geen UV's, of de textuur heeft geen ruimte voor de nieuwe vlakken die door de sneden ontstaan. Meshy betaalt de credits terug.

Om dit op te lossen, stuur het verzoek opnieuw zonder keep_texture, of met keep_texture: false. De onderdelen komen dan terug met elk een effen kleur.

invalid_input

De invoer is niet door een controle gekomen en er is geen specifiekere code van toepassing. message geeft de reden.

Bijvoorbeeld:

• Een leeg of beschadigd modelbestand
• Een niet-ondersteunde variant van een bestandsformaat, zoals een ASCII FBX-bestand of een met meshopt gecomprimeerd GLB-bestand
• Een geüpload model zonder geldige 3D-objecten, bijvoorbeeld een bestand met alleen armatuurstructuren, camera's of lichten
• Inhoud die niet door de veiligheidsfilters komt

Om dit op te lossen, lees message voor het specifieke probleem. Controleer of uw invoerbestanden en parameters voldoen aan de vereisten van de endpoint.

moderation_blocked

Veiligheidsfilters hebben uw prompt of referentieafbeeldingen afgewezen. De filters controleren de tekst en de afbeeldingen samen.

Doe een of beide van de volgende dingen om dit op te lossen:

• Herformuleer de prompt om suggestieve of gevoelige beschrijvingen te verwijderen.
• Wijzig referentieafbeeldingen die inhoud tonen die door de filters kan worden geblokkeerd.

moderation_unavailable

Type: server_error. Contentmoderation was tijdelijk niet beschikbaar, waardoor Meshy de taak liet mislukken in plaats van de controle over te slaan. Er is niets mis met uw inhoud.

Maak de taak opnieuw aan om dit op te lossen.

timeout

De taak overschreed een tijdslimiet aan de serverzijde, voor verwerking of voor wachten in de wachtrij, waardoor Meshy de taak liet mislukken en de credits terugbetaalde. Hoge belasting, of invoer die te complex is om op tijd af te ronden, kan dit veroorzaken.

Dit verschilt van een timeout in uw eigen code. Als uw client is gestopt met wachten, draait de taak nog steeds. Zie Hoe lang wachten.

Volg deze stappen om het probleem op te lossen:

1. Maak de taak opnieuw aan. Timeouts zijn vaak tijdelijk, en een nieuwe taak kan slagen.
2. Blijft het mislukken, vereenvoudig dan uw invoer, bijvoorbeeld door het detailniveau in uw afbeelding of prompt te verminderen. Zie voor invoer die lastiger te verwerken is image_too_complex.

queue_timeout

Type: timeout. De taak heeft te lang in de wachtrij gestaan zonder te starten, waardoor Meshy de taak als mislukt heeft gemarkeerd en eventuele in rekening gebrachte credits heeft terugbetaald. Jouw invoer heeft deze fout niet veroorzaakt.

Maak de taak opnieuw aan om dit op te lossen.

format_conversion_failed

Meshy heeft het model gegenereerd, maar het converteren ervan naar een door jou gevraagd formaat is mislukt.

Volg deze stappen om dit op te lossen:

1. Maak de taak opnieuw aan.
2. Als één formaat steeds blijft mislukken, vraag dan een ander formaat aan dat beter bij jouw behoeften past.

Best practices

• Probeer mislukte taken opnieuw. Maak voor een mislukte taak met timeout, service_unavailable of server_error een nieuwe taak aan met exponentiële backoff.
• Maak geen nieuwe taak aan wanneer uw eigen verzoek een timeout oplevert. De eerste taak kan nog steeds actief zijn, dus controleer of deze bestaat voordat u een nieuwe aanmaakt. Zie Hoe lang wachten.
• Leg taak-ID's vast. Vermeld de ID wanneer u contact opneemt met support.
• Controleer invoer voordat u deze verstuurt. Zorg ervoor dat afbeeldingen en modellen voldoen aan de formaatvereisten van de endpoint.
• Roep de API aan vanaf uw server. Code die in een browser wordt uitgevoerd, stelt uw API-sleutel bloot aan iedereen die de pagina opent.