Fouten

In deze gids bespreken we wat er gebeurt wanneer er iets misgaat terwijl je met de Meshy API werkt.

Aanvraagfouten

Deze fouten worden onmiddellijk geretourneerd wanneer je API-aanvraag wordt afgewezen. Controleer de HTTP-statuscode en het veld message om te begrijpen wat er misging.

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

Taakfouten

Deze fouten treden op nadat een taak is aangemaakt en wordt verwerkt. Controleer het object task_error in de taakrespons voor foutdetails.

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

Fouttypen

Het veld type geeft de brede categorie van de fout aan. Gebruik dit om je strategie voor opnieuw proberen te bepalen.

Foutcodes

Wanneer het veld code aanwezig is, identificeert het een specifiek, uitvoerbaar probleem. Hieronder staat de volledige referentie voor elke foutcode.

image_too_complex

Deze fout treedt op wanneer de invoerafbeelding of prompt een onderwerp beschrijft dat geometrisch te complex is voor het 3D-generatiemodel om te verwerken.

Veelvoorkomende voorbeelden zijn:

• Dichte stapels kleine objecten (bijv. een krat vol fruit, een stapel boeken)
• Ingewikkelde herhalende patronen (bijv. roosterstructuren, steigers, draadgaas)
• Complexe gebouwstructuren (bijv. gebouwen met meerdere verdiepingen met veel ramen en balkons)
• Meerdere afzonderlijke objecten in één afbeelding in plaats van één enkel onderwerp

Voorbeelden van invoer die waarschijnlijk te complex is:

Oplossing:

1. Gebruik één enkel object per afbeelding. Het model werkt het best met één duidelijk onderwerp. Neem geen meerdere afzonderlijke objecten op in dezelfde afbeelding of prompt.
2. Vereenvoudig je onderwerp. Verminder het detailniveau. Bijvoorbeeld een eenvoudige vaas in plaats van een vaas gevuld met tientallen bloemen.
3. Vermijd prompts op scèneniveau. Volledige gebouwen, stadsblokken, interieurs gevuld met meubels of landschappen overschrijden waarschijnlijk de capaciteit van het model. Richt je in plaats daarvan op één enkel object.
4. Vermijd dichte herhalende structuren. Onderwerpen zoals steigers, draadgaas, roosterpatronen of stapels van veel kleine items zijn veelvoorkomende triggers.

model_missing_uv

Deze fout treedt op wanneer je een model uploadt om van textuur te voorzien met enable_original_uv ingesteld op true, maar het model geen UV-coördinaten heeft. UV-coördinaten definiëren hoe een 2D-textuur om het 3D-oppervlak van je model wordt gewikkeld.

Oplossing:

De juiste oplossing hangt af van waarom je enable_original_uv op true hebt ingesteld:

• Als je de oorspronkelijke UV-layout van je model moet behouden (bijv. aangepaste plaatsing van naden voor nauwkeurige textuurmapping): je model moet geldige UV-coördinaten hebben. Controleer vóór het uploaden in de UV-editor van je 3D-software of er UV's bestaan. Houd er rekening mee dat STL-bestanden geen UV-gegevens kunnen opslaan, dus gebruik in plaats daarvan GLB, FBX of OBJ.
• Als je geen specifieke UV-controle nodig hebt (of als je het niet zeker weet): laat enable_original_uv weg of stel het in op false. Het systeem genereert automatisch een UV-layout voor je model. De automatisch gegenereerde UV's zijn geoptimaliseerd voor dekking, maar je hebt geen controle over waar textuurnaden worden geplaatst.

model_insufficient_uv

Deze fout treedt op wanneer een model UV-coördinaten heeft, maar de UV-dekking te klein is voor texturing van goede kwaliteit. Dit gebeurt vaak bij modellen die zijn geëxporteerd vanuit 3D-tools die tijdelijke of samengevouwen UV's genereren zonder een correcte unwrap.

Oplossing:

• Als je je oorspronkelijke UV-layout moet behouden: unwrap de UV's van het model opnieuw in je 3D-software. Zorg ervoor dat UV-eilanden goed over de UV-ruimte zijn verdeeld in plaats van samengevouwen in een klein gebied.
• Als je geen specifieke UV-controle nodig hebt: laat enable_original_uv weg of stel het in op false. Het systeem genereert automatisch een nieuwe UV-layout. Het nadeel is dat je je oorspronkelijke plaatsing van naden verliest, maar de automatisch gegenereerde UV's hebben voldoende dekking voor texturing.

invalid_input

Dit is de fallback-foutcode wanneer de invoer niet door de validatie komt, maar er geen specifiekere code van toepassing is. Het veld message bevat de specifieke reden voor de fout.

Veelvoorkomende oorzaken zijn:

• Lege of beschadigde modelbestanden
• Niet-ondersteunde variaties van bestandsformaten (bijv. ASCII FBX-bestanden, met meshopt gecomprimeerde GLB)
• Geen geldige 3D-objecten gevonden in het geüploade model (bijv. het bestand bevat alleen armaturen, camera's of lichten)
• Content die niet door veiligheidsfilters komt

Oplossing: Controleer het veld message voor details over wat er misging. Controleer of je invoerbestanden en parameters overeenkomen met de vereisten van de endpoint.

moderation_blocked

Deze fout treedt op wanneer je prompt of referentieafbeeldingen worden afgewezen door AI-veiligheidsfilters. Het filter beoordeelt zowel de tekstprompt als eventuele referentieafbeeldingen samen.

Oplossing:

• Herformuleer je tekstprompt om suggestieve of gevoelige beschrijvingen te verwijderen.
• Pas referentieafbeeldingen aan als ze inhoud weergeven die veiligheidsfilters kan activeren.

timeout

Deze fout betekent dat de verwerkingstijd van je taak de toegestane limiet heeft overschreden. Dit kan gebeuren door hoge systeembelasting of omdat de invoer te complex is om binnen de tijdslimiet te verwerken.

Oplossing:

1. Probeer het verzoek opnieuw. Timeouts zijn vaak tijdelijk en een nieuwe poging kan slagen.
2. Vereenvoudig je invoer. Als nieuwe pogingen blijven mislukken, is je invoer mogelijk te complex. Probeer het detailniveau in je afbeelding of prompt te verminderen. Zie image_too_complex voor richtlijnen over welke typen invoer moeilijker te verwerken zijn.

format_conversion_failed

Deze fout treedt op wanneer het gegenereerde 3D-model niet kon worden geconverteerd naar het door jou aangevraagde uitvoerformaat. Het model is succesvol gegenereerd, maar de conversiestap is mislukt.

Oplossing:

1. Probeer de aanvraag opnieuw.
2. Probeer een ander uitvoerformaat. Als een specifiek formaat blijft mislukken, schakel dan over naar een ander formaat dat aan je behoeften voldoet.

Aanbevolen werkwijzen

1. Implementeer retry-logica. Implementeer voor timeout- en service_unavailable-fouten retry-logica met exponentiële backoff.
2. Log taak-ID's. Log altijd de taak-ID voor foutopsporingsdoeleinden. Vermeld deze wanneer je contact opneemt met support.
3. Valideer invoer. Zorg ervoor dat je invoerafbeeldingen en modellen voldoen aan de formaatvereisten voordat je ze indient.