Errors

Alamin kung bakit nabigo ang isang request o task, at ano ang dapat gawin sa susunod. Ang isang request ay maaaring mabigo agad dahil sa isang HTTP error, at ang isang task ay maaaring mabigo sa ibang pagkakataon na may task_error.

Mga error sa request

Ibinabalik agad ni Meshy ang mga error na ito kapag tinanggihan nito ang isang request. Para malaman kung ano ang nangyaring mali, tingnan ang HTTP status code at ang message field.

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

Task errors

Ang isang task na ginawa ng Meshy ay maaari pa ring mabigo habang ito ay tumatakbo. Ang status nito ay nagiging FAILED, ire-refund ni Meshy ang mga credits nito, at ipinapaliwanag ng task_error kung bakit.

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

Ang type ay ang malawak na kategorya ng kabiguan. Gamitin ito upang magpasya kung ano ang susunod na gagawin.

Error codes

Kapag naroroon ang code, tinutukoy nito ang isa sa mga sumusunod na problema.

image_too_complex

Inilalarawan ng input image o prompt ang isang subject na masyadong komplikado sa heometriya para sa 3D generation.

Halimbawa:

• Siksik na tambak ng maliliit na bagay, tulad ng isang kahon na puno ng prutas o isang stack ng mga libro
• Masalimuot na paulit-ulit na pattern, tulad ng mga lattice structure, scaffolding, o wire mesh
• Komplikadong mga gusali, tulad ng mga multi-story na gusali na may maraming bintana at balkonahe
• Ilang magkakaibang bagay sa iisang imahe, sa halip na iisang subject

Malamang na masyadong komplikado ang mga input na ito:

Upang ayusin ito, subukan ang isa o higit pa sa mga sumusunod:

• Gumamit ng isang bagay lamang kada imahe. Pinakamainam gumana ang Meshy kapag may isang malinaw na subject, kaya huwag maglagay ng ilang magkakahiwalay na bagay sa iisang imahe o prompt.
• Gawing simple ang iyong subject. Halimbawa, gumamit ng isang simpleng plorera sa halip na isang plorera na puno ng dose-dosenang bulaklak.
• Iwasan ang mga eksena. Malamang na masyadong marami ang buong gusali, bloke ng lungsod, kuwartong may kasangkapan, at tanawin. Magpokus sa iisang bagay.
• Iwasan ang siksik na paulit-ulit na istruktura. Karaniwang sanhi ang scaffolding, wire mesh, lattice, at tambak ng maliliit na bagay.

model_missing_uv

Nagpadala ka ng modelo para sa texturing na may enable_original_uv na naka-set sa true, ngunit ang modelo ay walang UV coordinates. Ang UV coordinates ang nagtatakda kung paano babalot ang isang 2D texture sa ibabaw ng 3D surface.

Para ayusin ito, gawin ang isa sa mga sumusunod:

• Upang mapanatili ang sarili mong UV layout ng modelo, halimbawa para sa custom na paglalagay ng seam, magdagdag ng UVs sa modelo gamit ang iyong 3D software. Suriin ang mga ito sa UV editor nito, pagkatapos ay i-upload muli ang modelo. Hindi maaaring mag-imbak ng UVs ang mga STL file, kaya gumamit ng GLB, FBX, o OBJ.
• Kung hindi mo kailangan ang sarili mong layout, o kung hindi ka sigurado, huwag isama ang enable_original_uv o i-set ito sa false. Gagawa si Meshy ng UV layout para sa modelo. Masaklaw nang maayos ng bagong UVs ang modelo, ngunit hindi mo makokontrol kung saan mapupunta ang mga texture seam.

model_insufficient_uv

May UV coordinates ang modelo, ngunit sumasaklaw lang ang mga ito sa napakaliit na bahagi ng UV space para mag-texture nang maayos. Madalas itong nangyayari sa mga modelong ang exporter ay sumulat ng placeholder o nakoliyaw na mga UV nang walang tamang unwrap.

Upang ayusin ito, gawin ang isa sa mga sumusunod:

• Upang mapanatili ang sarili mong UV layout, i-unwrap muli ang mga UV ng modelo sa iyong 3D software. Ikalat ang mga islands sa buong UV space sa halip na sa isang maliit na sulok nito.
• Kung hindi mo kailangan ang sarili mong layout, huwag isama ang enable_original_uv o itakda ito sa false. Gagawa si Meshy ng bagong UV layout pagkatapos. Mawawala ang pagkakalagay ng iyong seam, ngunit ang bagong mga UV ay sumasaklaw na sa sapat na espasyo para mag-texture.

model_missing_texture

Ang input model ng isang Multi-Color Print task ay walang kulay na puwedeng hatiin ni Meshy sa mga kulay na pang-print. Gumagawa si Meshy ng multi-color 3MF mula sa mga kulay ng model, kaya't walang magagawa sa isang payak na puting mesh. Halimbawa, ang isang Text to 3D o Image to 3D preview na hindi pa natetekstyur ay walang kulay. Ganito rin ang output ng Repair Printability, o ng isang Auto Split task na hindi napanatili ang texture.

Ang itinuturing na kulay ay depende sa style na hiniling mo:

• Ang realistic ay kumukuha ng sample mula sa base color texture gamit ang mga UV ng model. Kailangan nito ng iisang base color texture, at mga UV sa bawat bahagi ng mesh.
• Ang cartoon ay nagpapapantay ng mga kulay kada face. Tumatanggap ito ng base color texture sa kahit anong bahagi, o per-vertex colors (COLOR_0).

Tinatanggihan ni Meshy ang isang model na walang parehong base color texture at vertex colors para sa dalawang style, sa halip na hayaang gawin ito ng cartoon na single-color print.

Tinatanggihan ni Meshy ang karamihan sa mga hiling na ito bago pa nito likhain ang task, gamit ang 400 at ang parehong paliwanag. Karaniwan mong matatanggap ang code na ito kapag hindi kayang suriin ni Meshy ang input nang maaga. Halimbawa, sinusuri lamang ni Meshy ang isang .fbx upload matapos i-convert ng task ito.

Para ayusin ito, gamitin ang opsyon na angkop sa iyong model:

• Tekstyurin muna ang model. Patakbuhin ang Retexture dito, o buuin ito gamit ang Text to 3D refine task o isang Image to 3D task na may should_texture: true. Pagkatapos, ipadala ang task na iyon bilang input_task_id.
• Para sa isang vertex-colored na model, gaya ng photogrammetry scan o isang mano-manong kinulayang mesh, gamitin ang style: "cartoon", na nagbabasa ng COLOR_0.
• Para sa bahagyang natekstyur o multi-texture na model gamit ang realistic, bigyan ng UV ang bawat bahagi ng mesh at ng parehong iisang base color texture. Para magawa ito, tekstyurin ang mga natitirang bahagi, o pagsamahin ang mga texture sa isang atlas. Puwede ka ring lumipat sa style: "cartoon".

textured_split_refused

Ang isang Auto Split task na may keep_texture: true ay hindi mapapanatili ang texture ng input model sa mga parte. Halimbawa, walang UVs ang modelo, o walang puwang ang texture nito para sa mga bagong face na nalikha ng mga hiwa. Ire-refund ni Meshy ang credits.

Upang ayusin ito, ipadala ulit ang request nang walang keep_texture, o may keep_texture: false. Babalik ang mga parte na may flat color sa bawat isa.

invalid_input

Nabigo ang input sa isang check, at wala nang mas specific na code na naaangkop. Ang message ang nagbibigay ng dahilan.

Halimbawa:

• Isang walang laman o sirang model file
• Isang hindi suportadong variant ng isang file format, tulad ng isang ASCII FBX file o isang meshopt-compressed GLB file
• Isang na-upload na modelo na walang valid na 3D object, halimbawa isang file na may armatures, camera, o ilaw lamang
• Content na hindi pumasa sa mga safety filter

Upang ayusin ito, basahin ang message para sa specific na problema. Tiyaking natutugunan ng iyong mga input file at parameter ang mga requirement ng endpoint.

moderation_blocked

Tinanggihan ng mga safety filter ang iyong prompt o reference images. Sinusuri ng mga filter ang teksto at mga larawan nang sabay-sabay.

Upang ayusin ito, gawin ang isa o pareho sa mga sumusunod:

• Baguhin ang pagkakasulat ng prompt upang alisin ang mga suhestibo o sensitibong paglalarawan.
• Palitan ang mga reference image na nagpapakita ng content na maaaring harangin ng mga filter.

moderation_unavailable

Uri: server_error. Pansamantalang hindi available ang content moderation, kaya binigo ni Meshy ang task sa halip na laktawan ang pagsusuri. Walang mali sa iyong content.

Upang ayusin ito, gawin muli ang task.

timeout

Ang gawain ay lumampas sa limitasyon ng oras sa server-side, para sa pagproseso o para sa paghihintay sa pila, kaya pinalya ito ng Meshy at ibinalik ang mga credits nito. Maaaring maging dahilan nito ang mataas na load, o isang input na masyadong komplikado para matapos sa tamang oras.

Ito ay iba sa isang timeout sa iyong sariling code. Kung huminto ang iyong client sa paghihintay, patuloy pa ring tumatakbo ang gawain. Tingnan ang Gaano katagal maghintay.

Upang ayusin ito, sundin ang mga hakbang na ito:

1. Gawin muli ang gawain. Ang mga timeout ay kadalasang pansamantala lamang, at maaaring magtagumpay ang isang bagong gawain.
2. Kung patuloy itong napapalya, gawing mas simple ang iyong input, halimbawa sa pamamagitan ng pagbawas sa detalye ng iyong imahe o prompt. Para sa mga input na mas mahirap iproseso, tingnan ang image_too_complex.

queue_timeout

Uri: timeout. Masyadong nagtagal ang paghihintay ng gawain sa pila nang hindi nagsisimula, kaya pinabigo ito ng Meshy at ibinalik ang anumang credits na sinisingil para rito. Ang iyong input ay hindi naging sanhi ng error na ito.

Upang ayusin ito, likhain muli ang gawain.

format_conversion_failed

Nabuo ng Meshy ang modelo, ngunit nabigo ang pag-convert nito sa format na hiniling mo.

Upang ayusin ito, sundin ang mga hakbang na ito:

1. Likhain muli ang gawain.
2. Kung patuloy na nabibigo ang isang format, humiling ng ibang format na angkop sa iyong mga pangangailangan.

Best practices

• Subukan muli ang mga nabigong task. Para sa isang nabigong task na may timeout, service_unavailable, o server_error, gumawa ng bagong task gamit ang exponential backoff.
• Huwag gumawa ng bagong task kapag nag-timeout ang sarili mong request. Maaaring tumatakbo pa rin ang unang task, kaya tingnan muna kung umiiral ito bago ka gumawa ng isa pa. Tingnan ang Gaano katagal maghihintay.
• I-log ang mga task ID. Isama ang ID kapag nakikipag-ugnayan ka sa support.
• Suriin ang mga input bago mo ipadala ang mga ito. Siguraduhing tumutugma ang mga imahe at mga modelo sa mga kinakailangang format ng endpoint.
• Tawagin ang API mula sa iyong server. Ang code na tumatakbo sa isang browser ay inilalantad ang iyong API key sa kahit sinong magbukas ng pahina.