Ralat

Dalam panduan ini, kita akan membincangkan apa yang berlaku apabila sesuatu tidak kena semasa anda bekerja dengan Meshy API.

Ralat Permintaan

Ralat ini dikembalikan dengan segera apabila permintaan API anda ditolak. Semak kod status HTTP dan medan message untuk memahami apa 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 tersebut. Gunakannya untuk menentukan strategi cuba 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 secara bersama.

Penyelesaian:

• Ubah semula prompt teks anda untuk mengalih keluar penerangan yang bersifat sugestif atau sensitif.
• Laraskan imej rujukan jika ia menggambarkan kandungan yang mungkin mencetuskan penapis keselamatan.

moderation_unavailable

Ralat ini berlaku apabila moderation kandungan tidak tersedia buat sementara waktu, menyebabkan tugas gagal dijalankan dan bukannya dijalankan tanpa pemeriksaan tersebut. Tiada apa-apa yang salah dengan kandungan anda. type baginya ialah server_error.

Penyelesaian: Cipta semula tugas tersebut.

timeout

Ralat ini bermaksud tugas melebihi had masa di pihak pelayan, sama ada untuk pemprosesan atau semasa menunggu dalam baris gilir, lalu tugas itu gagal dan kreditnya dikembalikan. Ini boleh berlaku akibat beban sistem yang tinggi atau kerana input terlalu kompleks untuk diproses dalam had masa yang ditetapkan.

Ini berbeza daripada timeout dalam kod anda sendiri. Jika klien anda berhenti menunggu, tugas tersebut masih berjalan; lihat Task Lifecycle.

Penyelesaian:

1. Cipta semula tugas tersebut. Timeout selalunya bersifat sementara dan tugas baharu mungkin berjaya.
2. Permudahkan input anda. Jika percubaan semula terus gagal, input anda mungkin terlalu kompleks. Cuba kurangkan tahap perincian pada imej atau prompt anda. Lihat image_too_complex untuk panduan mengenai jenis input yang lebih sukar diproses.

queue_timeout

Ralat ini bermaksud tugas tersebut menunggu terlalu lama dalam baris gilir tanpa bermula, jadi ia gagal dan sebarang kredit yang dicaj untuknya telah dikembalikan. Input anda bukan puncanya. type ralat ini ialah timeout.

Penyelesaian: Cipta semula tugas tersebut.

format_conversion_failed

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

Penyelesaian:

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

Amalan Terbaik

1. Laksanakan logik cuba semula. Apabila tugas gagal dengan ralat timeout, service_unavailable atau server_error, cipta semula tugas tersebut dengan exponential backoff. Jika permintaan anda sendiri tamat masa, jangan cipta tugas baharu: semak dahulu tugas yang sedia ada (lihat Kitaran Hayat Tugas).
2. Log ID tugas. Sentiasa log ID tugas untuk tujuan penyahpepijatan. Sertakan ID tersebut semasa menghubungi sokongan.
3. Sahkan input. Pastikan imej dan model input anda memenuhi keperluan format sebelum penghantaran.
4. Panggil API dari pelayan anda. Kod yang dijalankan dalam pelayar akan mendedahkan kunci API anda kepada sesiapa sahaja yang membuka halaman tersebut.