Errors

Sa gabay na ito, pag-uusapan natin kung ano ang nangyayari kapag may nagkamali habang nagtatrabaho ka gamit ang Meshy API.

Mga Errors sa Request

Ibinabalik agad ang mga error na ito kapag tinanggihan ang iyong API request. Suriin ang HTTP status code at field na message upang maunawaan kung ano ang nangyari.

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

Mga Errors sa Gawain

Nangyayari ang mga error na ito matapos malikha ang isang gawain at habang pinoproseso ito. Tingnan ang object na task_error sa tugon ng gawain para sa mga detalye ng error.

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

Mga Uri ng Error

Sinasabi sa iyo ng field na type ang malawak na kategorya ng kabiguan. Gamitin ito para magpasya sa iyong estratehiya sa muling pagsubok.

Mga Code ng Error

Kapag naroroon ang field na code, tinutukoy nito ang isang partikular at naaaksyunang problema. Nasa ibaba ang kumpletong sanggunian para sa bawat code ng error.

image_too_complex

Nangyayari ang error na ito kapag ang input na larawan o prompt ay naglalarawan ng subject na masyadong komplikado sa geometry para maproseso ng modelo ng 3D generation.

Kabilang sa mga karaniwang halimbawa ang:

• Siksik na tambak ng maliliit na bagay (hal., isang kahong puno ng prutas, isang salansan ng mga libro)
• Masalimuot na paulit-ulit na pattern (hal., mga lattice structure, scaffolding, wire mesh)
• Komplikadong istruktura ng gusali (hal., mga gusaling maraming palapag na may maraming bintana at balkonahe)
• Maraming magkakaibang bagay sa iisang larawan sa halip na isang subject lang

Mga halimbawa ng mga input na malamang ay masyadong komplikado:

Resolusyon:

1. Gumamit ng isang object lang bawat larawan. Pinakamahusay gumana ang modelo kapag may isang malinaw na subject. Huwag magsama ng maraming magkakahiwalay na object sa parehong larawan o prompt.
2. Pasimplehin ang iyong subject. Bawasan ang antas ng detalye. Halimbawa, isang simpleng vase sa halip na vase na puno ng dose-dosenang bulaklak.
3. Iwasan ang mga prompt na nasa antas ng scene. Ang buong mga gusali, mga bloke ng lungsod, mga interior na puno ng muwebles, o mga landscape ay malamang na lumampas sa kapasidad ng modelo. Sa halip, mag-focus sa isang object lang.
4. Iwasan ang siksik na paulit-ulit na istruktura. Ang mga subject tulad ng scaffolding, wire mesh, lattice pattern, o mga tambak ng maraming maliliit na item ay karaniwang nagti-trigger nito.

model_missing_uv

Nangyayari ang error na ito kapag nag-upload ka ng model para lagyan ng texture na ang enable_original_uv ay nakatakda sa true, ngunit walang UV coordinates ang model. Tinutukoy ng UV coordinates kung paano bumabalot ang isang 2D texture sa 3D surface ng iyong model.

Resolusyon:

Nakadepende ang tamang pag-aayos sa kung bakit mo itinakda ang enable_original_uv sa true:

• Kung kailangan mong panatilihin ang orihinal na UV layout ng iyong model (hal., custom na paglalagay ng seam para sa eksaktong texture mapping): dapat may valid na UV coordinates ang iyong model. Tiyaking may UVs sa UV editor ng iyong 3D software bago mag-upload. Tandaan na hindi makakapag-store ng UV data ang mga STL file, kaya gumamit na lang ng GLB, FBX, o OBJ.
• Kung hindi mo kailangan ng partikular na UV control (o hindi ka sigurado): alisin ang enable_original_uv o itakda ito sa false. Awtomatikong gagawa ang system ng UV layout para sa iyong model. Ang mga auto-generated na UVs ay optimized para sa coverage, ngunit wala kang kontrol sa kung saan ilalagay ang mga texture seam.

model_insufficient_uv

Nangyayari ang error na ito kapag ang isang modelo ay may UV coordinates, ngunit masyadong maliit ang saklaw ng UV para sa de-kalidad na pagte-texture. Karaniwan itong nangyayari sa mga modelong na-export mula sa mga 3D tool na gumagawa ng placeholder o collapsed na mga UV nang walang tamang unwrap.

Resolusyon:

• Kung kailangan mong panatilihin ang iyong orihinal na UV layout: muling i-unwrap ang mga UV ng modelo sa iyong 3D software. Tiyaking maayos na nakakalat ang mga UV island sa buong UV space sa halip na nakakompress sa isang maliit na lugar.
• Kung hindi mo kailangan ng partikular na kontrol sa UV: alisin ang enable_original_uv o itakda ito sa false. Awtomatikong gagawa ang system ng bagong UV layout. Ang kapalit nito ay mawawala ang orihinal mong seam placement, ngunit magkakaroon ng wastong saklaw para sa pagte-texture ang mga awtomatikong nabuong UV.

invalid_input

Ito ang fallback na error code kapag nabigo ang input sa validation ngunit walang mas partikular na code na naaangkop. Ang field na message ay naglalaman ng partikular na dahilan ng pagkabigo.

Kabilang sa mga karaniwang sanhi ang:

• Walang laman o sira na mga model file
• Hindi sinusuportahang mga variation ng file format (hal., ASCII FBX files, meshopt-compressed GLB)
• Walang nahanap na valid na 3D objects sa na-upload na model (hal., ang file ay naglalaman lamang ng armatures, cameras, o lights)
• Content na hindi pumapasa sa safety filters

Resolution: Suriin ang field na message para sa mga detalye kung ano ang nagkamali. Tiyaking tumutugma ang iyong mga input file at parameter sa mga kinakailangan ng endpoint.

moderation_blocked

Nangyayari ang error na ito kapag ang iyong prompt o mga reference na larawan ay tinanggihan ng mga AI safety filter. Sinusuri ng filter ang text prompt at anumang reference na larawan nang magkasama.

Resolusyon:

• I-rephrase ang iyong text prompt upang alisin ang mga mapang-akit o sensitibong paglalarawan.
• Ayusin ang mga reference na larawan kung nagpapakita ang mga ito ng content na maaaring mag-trigger ng mga safety filter.

timeout

Ang error na ito ay nangangahulugang lumampas sa pinapayagang limitasyon ang oras ng pagproseso ng iyong gawain. Maaari itong mangyari dahil sa mataas na system load o dahil masyadong kumplikado ang input para iproseso sa loob ng limitasyon ng oras.

Resolusyon:

1. Subukang muli ang request. Madalas pansamantala lang ang mga timeout at maaaring magtagumpay ang pag-uulit.
2. Pasimplehin ang iyong input. Kung patuloy na nabibigo ang mga pag-uulit, maaaring masyadong kumplikado ang iyong input. Subukang bawasan ang antas ng detalye sa iyong larawan o prompt. Tingnan ang image_too_complex para sa gabay kung anong mga uri ng input ang mas mahirap iproseso.

format_conversion_failed

Nangyayari ang error na ito kapag hindi ma-convert ang nabuong 3D model sa hiniling mong output format. Matagumpay na nabuo ang model, ngunit nabigo ang hakbang ng conversion.

Resolusyon:

1. Subukang muli ang request.
2. Subukan ang ibang output format. Kung patuloy na nabibigo ang isang partikular na format, lumipat sa ibang format na angkop sa iyong mga pangangailangan.

Pinakamahuhusay na Kasanayan

1. Magpatupad ng retry logic. Para sa mga error na timeout at service_unavailable, magpatupad ng exponential backoff retry logic.
2. I-log ang mga task ID. Palaging i-log ang task ID para sa mga layunin ng pag-debug. Isama ito kapag nakikipag-ugnayan sa support.
3. I-validate ang mga input. Tiyaking natutugunan ng iyong mga input image at model ang mga kinakailangan sa format bago isumite.