Ralat

Dalam panduan ini, kita akan membincangkan apa yang berlaku apabila terdapat masalah 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 Tugas

Ralat-ralat ini berlaku selepas tugas telah dicipta dan sedang diproses. Semak objek task_error pada respons tugas 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 cubaan semula anda.

Kod Ralat

Apabila medan code hadir, ia mengenal pasti masalah khusus yang boleh diambil tindakan. Di bawah adalah 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 model penjanaan 3D memproses.

Contoh biasa termasuk:

• Timbunan padat objek kecil (contohnya, peti penuh buah, timbunan buku)
• Corak berulang yang rumit (contohnya, struktur kisi, perancah, jaring wayar)
• Struktur bangunan yang kompleks (contohnya, bangunan bertingkat dengan banyak tingkap dan balkoni)
• Pelbagai objek berbeza dalam satu imej dan bukannya satu subjek tunggal

Contoh input yang mungkin terlalu kompleks:

Penyelesaian:

1. Gunakan satu objek bagi setiap imej. Model berfungsi dengan baik dengan satu subjek yang jelas. Jangan sertakan pelbagai objek berasingan dalam imej atau prompt yang sama.
2. Permudahkan subjek anda. Kurangkan tahap perincian. Sebagai contoh, pasu mudah dan bukannya pasu yang dipenuhi dengan berpuluh-puluh bunga.
3. Elakkan prompt tahap adegan. Seluruh bangunan, blok bandar, bahagian dalam yang dipenuhi perabot, atau landskap mungkin melebihi kapasiti model. Fokus pada satu objek sahaja.
4. Elakkan struktur berulang yang padat. Subjek seperti perancah, jaring wayar, corak kisi, atau timbunan banyak item kecil adalah pencetus biasa.

model_missing_uv

Ralat ini berlaku apabila anda memuat naik model untuk tekstur dengan enable_original_uv ditetapkan kepada true, tetapi model tersebut tidak mempunyai koordinat UV. Koordinat UV menentukan bagaimana tekstur 2D membalut permukaan 3D model anda.

Penyelesaian:

Penyelesaian yang betul bergantung kepada mengapa anda menetapkan enable_original_uv kepada true:

• Jika anda perlu mengekalkan susun atur UV asal model anda (contohnya, penempatan 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. Perhatikan bahawa fail STL tidak boleh menyimpan data UV, jadi gunakan GLB, FBX, atau OBJ sebagai gantinya.
• Jika anda tidak memerlukan kawalan UV khusus (atau anda tidak pasti): abaikan enable_original_uv atau tetapkan kepada false. Sistem akan secara automatik menjana susun atur UV untuk model anda. UV yang dijana secara automatik dioptimumkan untuk liputan tetapi anda tidak akan mempunyai kawalan ke atas di mana jahitan tekstur diletakkan.

model_insufficient_uv

Ralat ini berlaku apabila model mempunyai koordinat UV, tetapi liputan UV terlalu kecil untuk tekstur berkualiti. Ini biasanya berlaku dengan model yang dieksport dari alat 3D yang menjana UV sementara atau runtuh tanpa pembukaan yang betul.

Penyelesaian:

• Jika anda perlu mengekalkan susun atur UV asal anda: buka semula UV model dalam perisian 3D anda. Pastikan pulau UV tersebar dengan betul di seluruh ruang UV dan tidak runtuh ke kawasan kecil.
• Jika anda tidak memerlukan kawalan UV khusus: abaikan enable_original_uv atau tetapkan kepada false. Sistem akan menjana susun atur UV baru secara automatik. Kelemahannya adalah anda kehilangan penempatan jahitan asal anda, tetapi UV yang dijana secara automatik akan mempunyai liputan yang betul untuk tekstur.

model_missing_texture

Ralat ini berlaku apabila model input bagi tugasan Multi-Color Print tidak mempunyai maklumat warna yang boleh dipisahkan oleh penukar kepada warna cetakan. 3MF pelbagai warna dibina daripada warna model, jadi jejaring putih biasa — contohnya pratonton Teks ke 3D atau Imej ke 3D yang tidak pernah ditekstur, atau output yang dibaiki / dipisah secara automatik — tidak mempunyai apa-apa untuk diproses.

Apa yang dikira sebagai sumber warna bergantung pada style yang anda minta:

• realistic mengambil sampel tekstur warna asas melalui koordinat UV model, jadi ia memerlukan satu tekstur warna asas dengan koordinat UV pada setiap bahagian jejaring.
• cartoon meratakan warna bagi setiap muka dan menerima tekstur warna asas pada mana-mana bahagian atau warna setiap bucu (COLOR_0).

Model yang tiada tekstur warna asas mahupun warna bucu akan ditolak untuk kedua-dua gaya; dengan cartoon, sebaliknya ia akan "berjaya" sebagai cetakan satu warna.

Kebanyakan permintaan ditolak sebelum tugasan dicipta (400 Bad Request dengan penjelasan yang sama), jadi anda biasanya hanya akan melihat kod ini apabila input tidak dapat diperiksa terlebih dahulu — muat naik .fbx, misalnya, diperiksa sebaik sahaja tugasan telah dinormalkan.

Penyelesaian:

• Tekstur model terlebih dahulu. Jalankan tugasan Retekstur ke atasnya, atau hasilkannya dengan pentekstur diaktifkan (tugasan refine Teks ke 3D, atau tugasan Imej ke 3D dengan should_texture: true), dan hantar tugasan tersebut sebagai input_task_id.
• Model berwarna bucu (imbasan fotogrametri, jejaring dicat secara manual): minta style: "cartoon", yang membaca COLOR_0.
• Model yang ditekstur sebahagian atau bertekstur berbilang di bawah realistic: setiap bahagian jejaring memerlukan UV dan tekstur warna asas yang sama serta tunggal. Tekstur bahagian yang tinggal atau gabungkan tekstur-tekstur tersebut menjadi satu atlas, atau tukar kepada style: "cartoon".

invalid_input

Ini adalah kod ralat lalai apabila input gagal pengesahan tetapi tiada kod yang lebih spesifik terpakai. Medan message mengandungi sebab khusus untuk kegagalan tersebut.

Punca biasa termasuk:

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

Penyelesaian: Semak medan message untuk butiran khusus mengenai apa yang salah. 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 kedua-dua prompt teks dan mana-mana imej rujukan bersama-sama.

Penyelesaian:

• Ubah suai prompt teks anda untuk mengeluarkan deskripsi yang menggoda atau sensitif.
• Laraskan imej rujukan jika ia menggambarkan kandungan yang mungkin mencetuskan penapis keselamatan.

timeout

Ralat ini bermaksud masa pemprosesan tugas anda melebihi had yang dibenarkan. Ini boleh berlaku disebabkan oleh 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 mengenai jenis input yang lebih sukar untuk diproses.

format_conversion_failed

Ralat ini berlaku apabila model 3D yang dijana tidak dapat ditukar kepada format output yang diminta. Model tersebut 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 peningkatan masa secara eksponen.
2. Log ID tugas. Sentiasa log ID tugas untuk tujuan penyahpepijatan. Sertakan ia apabila menghubungi sokongan.
3. Sahkan input. Pastikan imej dan model input anda memenuhi keperluan format sebelum penghantaran.