Fel

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

Förfrågningsfel

Dessa fel returneras omedelbart när din API-förfrågan 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 anger den övergripande kategorin för felet. Använd det för att avgöra din strategi för återförsök.

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

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

Åtgärd:

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

moderation_unavailable

Det här felet uppstår när innehållsmoderering tillfälligt var otillgänglig, så uppgiften misslyckades i stället för att köras utan kontrollen. Det är inget fel på ditt innehåll. Dess type är server_error.

Åtgärd: Skapa uppgiften igen.

timeout

Det här felet betyder att uppgiften överskred en tidsgräns på serversidan, antingen för bearbetning eller för väntan i kön, vilket gjorde att uppgiften misslyckades och dess credits återbetalades. Detta kan inträffa på grund av hög systembelastning eller för att indata är för komplexa för att bearbetas inom tidsgränsen.

Detta skiljer sig från en timeout i din egen kod. Om din klient slutade vänta körs uppgiften fortfarande; se Task Lifecycle.

Åtgärd:

1. Skapa uppgiften igen. Timeouts är ofta tillfälliga och en ny uppgift kan lyckas.
2. Förenkla din indata. Om nya försök fortsätter att misslyckas kan din indata 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 indata som är svårare att bearbeta.

queue_timeout

Det här felet innebär att uppgiften väntade för länge i kön utan att starta, så den misslyckades och eventuella credits som debiterats för den återbetalades. Din indata orsakade det inte. Dess type är timeout.

Lösning: Skapa uppgiften igen.

format_conversion_failed

Det här felet uppstår när den genererade 3D-modellen inte kunde konverteras till det begärda utdataformatet. Modellen genererades utan problem, 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.

Best Practices

1. Implementera återförsöksloggik. När en uppgift misslyckas med ett timeout-, service_unavailable- eller server_error-fel, skapa den igen med exponentiell backoff. Om din egen förfrågan fick timeout, skapa inte en ny uppgift: kontrollera den befintliga först (se Uppgiftens livscykel).
2. Logga uppgifts-ID:n. Logga alltid uppgifts-ID:t för felsökningsändamål. Inkludera det när du kontaktar supporten.
3. Validera indata. Säkerställ att dina inmatade bilder och modeller uppfyller formatkraven innan inlämning.
4. Anropa API:et från din server. Kod som körs i en webbläsare skulle exponera din API-nyckel för vem som helst som öppnar sidan.