Ralat

Dalam panduan ini, kita akan membincangkan perkara yang berlaku apabila sesuatu masalah berlaku semasa anda bekerja dengan Meshy API.

Ralat Permintaan

Ralat ini dikembalikan serta-merta apabila permintaan API anda ditolak. Semak kod status HTTP dan medan message untuk memahami perkara yang tidak kena.

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

Ralat Tugasan

Ralat ini berlaku selepas tugasan telah dicipta dan sedang diproses. Semak objek task_error pada respons tugasan untuk butiran ralat.

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

Jenis Ralat

Medan type memberitahu anda kategori umum kegagalan. Gunakannya untuk menentukan strategi cuba semula anda.

Kod Ralat

Apabila medan code hadir, ia mengenal pasti masalah khusus yang boleh diambil tindakan. Di bawah ialah rujukan penuh untuk setiap kod ralat.

image_too_complex

Ralat ini berlaku apabila imej input atau prompt menerangkan subjek yang terlalu kompleks secara geometri untuk diproses oleh model penjanaan 3D.

Contoh biasa termasuk:

• Longgokan padat objek kecil (cth., krat penuh buah-buahan, timbunan buku)
• Corak berulang yang rumit (cth., struktur kekisi, perancah, jejaring dawai)
• Struktur bangunan yang kompleks (cth., bangunan bertingkat dengan banyak tingkap dan balkoni)
• Berbilang objek berbeza dalam satu imej dan bukannya satu subjek tunggal

Contoh input yang berkemungkinan terlalu kompleks:

Penyelesaian:

1. Gunakan satu objek bagi setiap imej. Model berfungsi paling baik dengan satu subjek yang jelas. Jangan sertakan berbilang objek berasingan dalam imej atau prompt yang sama.
2. Permudahkan subjek anda. Kurangkan tahap perincian. Contohnya, pasu ringkas dan bukannya pasu yang dipenuhi berpuluh-puluh bunga.
3. Elakkan prompt peringkat adegan. Keseluruhan bangunan, blok bandar, ruang dalaman yang dipenuhi perabot, atau landskap berkemungkinan melebihi keupayaan model. Sebaliknya, fokus pada satu objek.
4. Elakkan struktur berulang yang padat. Subjek seperti perancah, jejaring dawai, corak kekisi, atau longgokan banyak item kecil ialah pencetus biasa.

model_missing_uv

Ralat ini berlaku apabila anda memuat naik model untuk peneksturan dengan enable_original_uv ditetapkan kepada true, tetapi model tersebut tiada koordinat UV. Koordinat UV mentakrifkan cara tekstur 2D membalut pada permukaan 3D model anda.

Penyelesaian:

Pembaikan yang betul bergantung pada sebab anda menetapkan enable_original_uv kepada true:

• Jika anda perlu mengekalkan susun atur UV asal model anda (cth., peletakan jahitan tersuai untuk pemetaan tekstur yang tepat): model anda mesti mempunyai koordinat UV yang sah. Sahkan UV wujud dalam penyunting UV perisian 3D anda sebelum memuat naik. Perlu diingat bahawa fail STL tidak boleh menyimpan data UV, jadi gunakan GLB, FBX, atau OBJ sebaliknya.
• Jika anda tidak memerlukan kawalan UV tertentu (atau anda tidak pasti): abaikan enable_original_uv atau tetapkannya kepada false. Sistem akan menjana susun atur UV secara automatik untuk model anda. UV yang dijana secara automatik dioptimumkan untuk liputan tetapi anda tidak akan mempunyai kawalan ke atas tempat jahitan tekstur diletakkan.

model_insufficient_uv

Ralat ini berlaku apabila model mempunyai koordinat UV, tetapi liputan UV terlalu kecil untuk penteksturan berkualiti. Ini biasanya berlaku dengan model yang dieksport daripada alat 3D yang menjana UV pemegang tempat atau UV yang runtuh tanpa nyahbungkus yang betul.

Penyelesaian:

• Jika anda perlu mengekalkan susun atur UV asal anda: nyahbungkus semula UV model dalam perisian 3D anda. Pastikan pulau UV disebarkan dengan betul merentasi ruang UV dan bukannya runtuh ke dalam kawasan kecil.
• Jika anda tidak memerlukan kawalan UV khusus: abaikan enable_original_uv atau tetapkannya kepada false. Sistem akan menjana susun atur UV baharu secara automatik. Komprominya ialah anda kehilangan peletakan kelim asal anda, tetapi UV yang dijana secara automatik akan mempunyai liputan yang betul untuk penteksturan.

invalid_input

Ini ialah kod ralat sandaran apabila input gagal pengesahan tetapi tiada kod yang lebih khusus terpakai. Medan message mengandungi sebab khusus kegagalan tersebut.

Punca lazim termasuk:

• Fail model kosong atau rosak
• Variasi format fail yang tidak disokong (cth., fail ASCII FBX, GLB termampat meshopt)
• Tiada objek 3D yang sah ditemui dalam model yang dimuat naik (cth., fail hanya mengandungi armatur, kamera, atau lampu)
• Kandungan yang tidak melepasi penapis keselamatan

Penyelesaian: Semak medan message untuk butiran khusus tentang perkara yang berlaku. Sahkan fail input dan parameter anda sepadan dengan keperluan endpoint.

moderation_blocked

Ralat ini berlaku apabila prompt atau imej rujukan anda ditolak oleh penapis keselamatan AI. Penapis menilai prompt teks dan sebarang imej rujukan bersama-sama.

Penyelesaian:

• Ungkap semula prompt teks anda untuk membuang perihalan yang berunsur sugestif atau sensitif.
• Laraskan imej rujukan jika imej tersebut menggambarkan kandungan yang mungkin mencetuskan penapis keselamatan.

timeout

Ralat ini bermaksud masa pemprosesan tugasan anda melebihi had yang dibenarkan. Ini boleh berlaku disebabkan beban sistem yang tinggi atau kerana input terlalu kompleks untuk diproses dalam had masa.

Penyelesaian:

1. Cuba semula permintaan. timeout selalunya bersifat sementara dan cubaan semula mungkin berjaya.
2. Permudahkan input anda. Jika cubaan semula terus gagal, input anda mungkin terlalu kompleks. Cuba kurangkan tahap perincian dalam imej atau prompt anda. Lihat image_too_complex untuk panduan tentang jenis input yang lebih sukar diproses.

format_conversion_failed

Ralat ini berlaku apabila model 3D yang dijana tidak dapat ditukar kepada format output yang anda minta. Model telah berjaya dijana, tetapi langkah penukaran gagal.

Penyelesaian:

1. Cuba semula permintaan.
2. Cuba format output yang berbeza. Jika format tertentu terus gagal, tukar kepada format lain yang sesuai dengan keperluan anda.

Amalan Terbaik

1. Laksanakan logik cuba semula. Untuk ralat timeout dan service_unavailable, laksanakan logik cuba semula dengan backoff eksponen.
2. Log ID tugas. Sentiasa log ID tugas untuk tujuan penyahpepijatan. Sertakannya apabila menghubungi sokongan.
3. Sahkan input. Pastikan imej input dan model anda memenuhi keperluan format sebelum penyerahan.