Fel

I den här guiden går vi igenom vad som händer när något går fel medan du arbetar med Meshy API.

Begäranfel

Dessa fel returneras omedelbart när din API-begäran avvisas. Kontrollera HTTP-statuskoden och fältet message för att förstå vad som gick fel.

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

Taskfel

Dessa fel uppstår efter att en uppgift har skapats och bearbetas. Kontrollera task_error-objektet i uppgiftens svar för felspecifikationer.

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

Feltyper

Fältet type berättar om den breda kategorin av felet. Använd det för att bestämma din strategi för att försöka igen.

Felkoder

När fältet code är närvarande identifierar det ett specifikt, åtgärdbart problem. Nedan finns den fullständiga referensen för varje felkod.

image_too_complex

Detta fel uppstår när inmatningsbilden eller prompt beskriver ett ämne som är för geometriskt komplext för 3D-genereringsmodellen att bearbeta.

Vanliga exempel inkluderar:

• Täta högar av små föremål (t.ex. en låda full med frukt, en hög med böcker)
• Intrikata upprepande mönster (t.ex. gallerstrukturer, byggnadsställningar, trådnät)
• Komplexa byggnadsstrukturer (t.ex. flervåningsbyggnader med många fönster och balkonger)
• Flera distinkta objekt i en bild istället för ett enda ämne

Exempel på inmatningar som sannolikt är för komplexa:

Lösning:

1. Använd ett enda objekt per bild. Modellen fungerar bäst med ett tydligt ämne. Inkludera inte flera separata objekt i samma bild eller prompt.
2. Förenkla ditt ämne. Minska detaljnivån. Till exempel, en enkel vas istället för en vas fylld med dussintals blommor.
3. Undvik scen-nivå prompts. Hela byggnader, kvarter, interiörer fyllda med möbler eller landskap överskrider sannolikt modellens kapacitet. Fokusera istället på ett enda objekt.
4. Undvik täta upprepande strukturer. Ämnen som byggnadsställningar, trådnät, gallerstrukturer eller högar av många små föremål är vanliga utlösare.

model_missing_uv

Detta fel uppstår när du laddar upp en modell för texturering med enable_original_uv inställt på true, men modellen saknar UV-koordinater. UV-koordinater definierar hur en 2D-textur lindas runt modellens 3D-yta.

Lösning:

Den rätta lösningen beror på varför du ställde in enable_original_uv till true:

• Om du behöver bevara modellens ursprungliga UV-layout (t.ex. anpassad sömplacering för exakt texturkartläggning): din modell måste ha giltiga UV-koordinater. Kontrollera att UVs finns i ditt 3D-programs UV-editor innan du laddar upp. Observera att STL-filer inte kan lagra UV-data, så använd GLB, FBX eller OBJ istället.
• Om du inte behöver specifik UV-kontroll (eller om du är osäker): utelämna enable_original_uv eller ställ in det på false. Systemet kommer automatiskt att generera en UV-layout för din modell. De automatiskt genererade UVs är optimerade för täckning men du kommer inte att ha kontroll över var textursömmarna placeras.

model_insufficient_uv

Detta fel uppstår när en modell har UV-koordinater, men UV-täckningen är för liten för kvalitativ texturering. Detta händer ofta med modeller som exporteras från 3D-verktyg som genererar platshållare eller kollapsade UVs utan en korrekt unwrap.

Lösning:

• Om du behöver bevara din ursprungliga UV-layout: gör en ny unwrap av modellens UVs i din 3D-programvara. Se till att UV-öarna är ordentligt utspridda över UV-utrymmet istället för att vara kollapsade till ett litet område.
• Om du inte behöver specifik UV-kontroll: utelämna enable_original_uv eller ställ in det på false. Systemet kommer automatiskt att generera en ny UV-layout. Nackdelen är att du förlorar din ursprungliga sömplacering, men de automatiskt genererade UVs kommer att ha korrekt täckning för texturering.

model_missing_texture

Detta fel uppstår när indatamodellen för en Multi-Color Print-uppgift saknar färginformation som konverteraren kan separera i utskriftsfärger. En 3MF-fil med flerfärgsutskrift byggs upp av modellens färger, så ett rent vitt nät — till exempel en Text till 3D- eller Bild till 3D-förhandsgranskning som aldrig texturerats, eller ett reparerat/autouppdelat resultat — ger inget att arbeta med.

Vad som räknas som en färgkälla beror på vilken style du begärt:

• realistic samplar bastexturen via modellens UV:er, så den kräver en enda bastextur med UV-koordinater på varje nätdel.
• cartoon plattar till färger per yta och accepterar en bastextur på vilken del som helst eller färger per vertex (COLOR_0).

En modell utan vare sig bastextur eller vertexfärger avvisas för båda stilarna; med cartoon skulle den annars "lyckas" som en enfärgsutskrift.

De flesta förfrågningar avvisas innan uppgiften skapas (400 Bad Request med samma förklaring), så du kommer vanligtvis bara att se denna kod när indata inte kunde inspekteras i förväg — en .fbx-uppladdning, till exempel, kontrolleras först när uppgiften har normaliserat den.

Lösning:

• Texturera modellen först. Kör en Omtexturering-uppgift på den, eller generera den med texturering aktiverad (en Text till 3D refine-uppgift, eller en Bild till 3D-uppgift med should_texture: true), och skicka den uppgiften som input_task_id.
• Vertexfärgade modeller (fotogrammetriskanningar, handmålade nät): begär style: "cartoon", som läser COLOR_0.
• Delvis texturerade eller flertexturerade modeller under realistic: varje nätdel behöver UV:er och samma, enda bastextur. Texturera de återstående delarna eller slå ihop texturerna till ett atlas, eller byt till style: "cartoon".

invalid_input

Detta är felkoden som används när inmatningen misslyckas med valideringen men ingen mer specifik kod är tillämplig. Fältet message innehåller den specifika orsaken till felet.

Vanliga orsaker inkluderar:

• Tomma eller korrupta modelfiler
• Icke-stödda filformatvariationer (t.ex. ASCII FBX-filer, meshopt-komprimerade GLB)
• Inga giltiga 3D-objekt hittades i den uppladdade modellen (t.ex. filen innehåller endast armaturer, kameror eller ljus)
• Innehåll som inte klarar säkerhetsfilter

Lösning: Kontrollera fältet message för specifika detaljer om vad som gick fel. Verifiera att dina inmatningsfiler och parametrar överensstämmer med endpointens krav.

moderation_blocked

Detta fel uppstår när din prompt eller referensbilder avvisas av AI-säkerhetsfilter. Filtret utvärderar både textprompten och eventuella referensbilder tillsammans.

Lösning:

• Omformulera din textprompt för att ta bort suggestiva eller känsliga beskrivningar.
• Justera referensbilder om de visar innehåll som kan utlösa säkerhetsfilter.

timeout

Detta fel innebär att din uppgifts bearbetningstid överskred den tillåtna gränsen. Detta kan hända på grund av hög systembelastning eller för att inmatningen är för komplex för att bearbetas inom tidsgränsen.

Lösning:

1. Försök igen med begäran. Timeout-fel är ofta tillfälliga och ett nytt försök kan lyckas.
2. Förenkla din inmatning. Om nya försök fortsätter att misslyckas kan din inmatning vara för komplex. Försök att minska detaljnivån i din bild eller prompt. Se image_too_complex för vägledning om vilka typer av inmatningar som är svårare att bearbeta.

format_conversion_failed

Detta fel inträffar när den genererade 3D-modellen inte kunde konverteras till det begärda utdataformatet. Modellen genererades framgångsrikt, men konverteringssteget misslyckades.

Lösning:

1. Försök igen med begäran.
2. Prova ett annat utdataformat. Om ett specifikt format fortsätter att misslyckas, byt till ett annat format som passar dina behov.

Bästa praxis

1. Implementera återförsökslogik. För timeout och service_unavailable fel, implementera exponentiell backoff återförsökslogik.
2. Logga uppgifts-ID:n. Logga alltid uppgifts-ID för felsökningsändamål. Inkludera det när du kontaktar support.
3. Validera indata. Se till att dina inmatningsbilder och modeller uppfyller formatkraven innan inlämning.