Fel

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

Begärandefel

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

Uppgiftsfel

Dessa fel uppstår efter att en uppgift har skapats och bearbetas. Kontrollera objektet task_error i uppgiftssvaret för felinformation.

{
  "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 nya försök.

Felkoder

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

image_too_complex

Det här felet uppstår när inmatningsbilden eller prompt beskriver ett motiv som är för geometriskt komplext för att 3D-genereringsmodellen ska kunna bearbeta det.

Vanliga exempel inkluderar:

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

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

Lösning:

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

model_missing_uv

Det här felet uppstår när du laddar upp en modell för texturering med enable_original_uv satt till true, men modellen saknar UV-koordinater. UV-koordinater definierar hur en 2D-textur lindas runt 3D-ytan på din modell.

Lösning:

Rätt lösning beror på varför du satte enable_original_uv till true:

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

model_insufficient_uv

Det här felet uppstår när en modell har UV-koordinater, men UV-täckningen är för liten för texturering av god kvalitet. Detta händer ofta med modeller som exporteras från 3D-verktyg som genererar platshållar-UV:er eller kollapsade UV:er utan en korrekt unwrap.

Lösning:

• Om du behöver bevara din ursprungliga UV-layout: gör om unwrap av modellens UV:er i din 3D-programvara. Se till att UV-öar är korrekt utspridda över UV-utrymmet i stä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 genererar automatiskt en ny UV-layout. Kompromissen är att du förlorar din ursprungliga placering av sömmar, men de automatiskt genererade UV:erna kommer att ha korrekt täckning för texturering.

invalid_input

Detta är reservfelkoden när indata inte klarar valideringen men ingen mer specifik kod är tillämplig. Fältet message innehåller den specifika orsaken till felet.

Vanliga orsaker inkluderar:

• Tomma eller skadade modellfiler
• Variationer av filformat som inte stöds (t.ex. ASCII FBX-filer, meshopt-komprimerad 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 detaljer om vad som gick fel. Verifiera att dina indatafiler och parametrar matchar kraven för denna endpoint.

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 prompt och eventuella referensbilder tillsammans.

Lösning:

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

timeout

Det här felet innebär att bearbetningstiden för din uppgift överskred den tillåtna gränsen. Detta kan hända på grund av hög systembelastning eller för att indata är för komplex för att bearbetas inom tidsgränsen.

Lösning:

1. Försök med begäran igen. Timeouts är ofta tillfälliga och ett nytt försök kan lyckas.
2. Förenkla dina indata. Om nya försök fortsätter att misslyckas kan dina indata vara för komplexa. 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.

format_conversion_failed

Det här felet uppstår när den genererade 3D-modellen inte kunde konverteras till det utdataformat du begärde. Modellen genererades framgångsrikt, men konverteringssteget misslyckades.

Lösning:

1. Försök med begäran igen.
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 Fel av typen timeout och service_unavailable, implementera återförsökslogik med exponentiell backoff.
2. Logga uppgifts-ID:n. Logga alltid uppgifts-ID:t för felsökningsändamål. Inkludera det när du kontaktar support.
3. Validera indata. Säkerställ att dina indatabilder och modeller uppfyller formatkraven före inskickning.