Kesalahan

Dalam panduan ini, kita akan membahas apa yang terjadi ketika ada sesuatu yang salah saat Anda bekerja dengan Meshy API.

Kesalahan Permintaan

Kesalahan ini dikembalikan segera ketika permintaan API Anda ditolak. Periksa kode status HTTP dan bidang message untuk memahami apa yang salah.

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

Kesalahan Tugas

Kesalahan ini terjadi setelah tugas dibuat dan sedang diproses. Periksa objek task_error pada respons tugas untuk detail kesalahan.

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

Field type memberi tahu Anda kategori umum kegagalan. Gunakan ini untuk menentukan strategi percobaan ulang Anda.

Kode Kesalahan

Ketika field code ada, field tersebut mengidentifikasi masalah spesifik yang dapat ditindaklanjuti. Di bawah ini adalah referensi lengkap untuk setiap kode kesalahan.

image_too_complex

Kesalahan ini terjadi ketika gambar input atau prompt mendeskripsikan subjek yang terlalu kompleks secara geometris untuk diproses oleh model pembuatan 3D.

Contoh umum meliputi:

• Tumpukan padat objek kecil (misalnya, peti penuh buah, tumpukan buku)
• Pola berulang yang rumit (misalnya, struktur kisi, perancah, jaring kawat)
• Struktur bangunan kompleks (misalnya, bangunan bertingkat dengan banyak jendela dan balkon)
• Beberapa objek berbeda dalam satu gambar alih-alih satu subjek tunggal

Contoh input yang kemungkinan terlalu kompleks:

Resolusi:

1. Gunakan satu objek per gambar. Model bekerja paling baik dengan satu subjek yang jelas. Jangan sertakan beberapa objek terpisah dalam gambar atau prompt yang sama.
2. Sederhanakan subjek Anda. Kurangi tingkat detail. Misalnya, vas sederhana alih-alih vas yang dipenuhi puluhan bunga.
3. Hindari prompt tingkat adegan. Seluruh bangunan, blok kota, interior yang dipenuhi furnitur, atau lanskap kemungkinan akan melampaui kapasitas model. Fokus pada satu objek saja.
4. Hindari struktur berulang yang padat. Subjek seperti perancah, jaring kawat, pola kisi, atau tumpukan banyak item kecil adalah pemicu umum.

model_missing_uv

Kesalahan ini terjadi saat Anda mengunggah model untuk diberi tekstur dengan enable_original_uv diatur ke true, tetapi model tersebut tidak memiliki koordinat UV. Koordinat UV menentukan bagaimana tekstur 2D membungkus permukaan 3D model Anda.

Resolusi:

Perbaikan yang tepat bergantung pada alasan Anda mengatur enable_original_uv ke true:

• Jika Anda perlu mempertahankan tata letak UV asli model Anda (misalnya, penempatan seam kustom untuk pemetaan tekstur yang presisi): model Anda harus memiliki koordinat UV yang valid. Pastikan UV tersedia di editor UV perangkat lunak 3D Anda sebelum mengunggah. Perhatikan bahwa file STL tidak dapat menyimpan data UV, jadi gunakan GLB, FBX, atau OBJ sebagai gantinya.
• Jika Anda tidak memerlukan kontrol UV tertentu (atau Anda tidak yakin): hilangkan enable_original_uv atau atur ke false. Sistem akan secara otomatis menghasilkan tata letak UV untuk model Anda. UV yang dihasilkan otomatis dioptimalkan untuk cakupan, tetapi Anda tidak akan memiliki kontrol atas tempat seam tekstur ditempatkan.

model_insufficient_uv

Kesalahan ini terjadi ketika sebuah model memiliki koordinat UV, tetapi cakupan UV terlalu kecil untuk tekstur berkualitas. Ini umumnya terjadi pada model yang diekspor dari alat 3D yang menghasilkan UV placeholder atau UV yang runtuh tanpa unwrap yang benar.

Resolusi:

• Jika Anda perlu mempertahankan tata letak UV asli Anda: unwrap ulang UV model di perangkat lunak 3D Anda. Pastikan pulau UV tersebar dengan benar di seluruh ruang UV, bukan runtuh ke area kecil.
• Jika Anda tidak memerlukan kontrol UV tertentu: hilangkan enable_original_uv atau atur ke false. Sistem akan secara otomatis menghasilkan tata letak UV baru. Komprominya adalah Anda kehilangan penempatan seam asli, tetapi UV yang dihasilkan otomatis akan memiliki cakupan yang memadai untuk tekstur.

invalid_input

Ini adalah kode kesalahan fallback ketika input gagal divalidasi tetapi tidak ada kode yang lebih spesifik yang berlaku. Field message berisi alasan spesifik kegagalan tersebut.

Penyebab umum meliputi:

• File model kosong atau rusak
• Variasi format file yang tidak didukung (misalnya, file FBX ASCII, GLB terkompresi meshopt)
• Tidak ada objek 3D valid yang ditemukan dalam model yang diunggah (misalnya, file hanya berisi armature, kamera, atau lampu)
• Konten yang tidak lolos filter keamanan

Resolusi: Periksa field message untuk detail spesifik tentang apa yang salah. Verifikasi file input dan parameter Anda sesuai dengan persyaratan endpoint.

moderation_blocked

Kesalahan ini terjadi ketika prompt atau gambar referensi Anda ditolak oleh filter keamanan AI. Filter mengevaluasi prompt teks dan setiap gambar referensi secara bersamaan.

Resolusi:

• Susun ulang prompt teks Anda untuk menghapus deskripsi yang sugestif atau sensitif.
• Sesuaikan gambar referensi jika menggambarkan konten yang dapat memicu filter keamanan.

timeout

Kesalahan ini berarti waktu pemrosesan tugas Anda melebihi batas yang diizinkan. Ini dapat terjadi karena beban sistem yang tinggi atau karena input terlalu kompleks untuk diproses dalam batas waktu.

Resolusi:

1. Coba ulang permintaan. timeout sering kali bersifat sementara dan percobaan ulang mungkin berhasil.
2. Sederhanakan input Anda. Jika percobaan ulang terus gagal, input Anda mungkin terlalu kompleks. Coba kurangi tingkat detail dalam gambar atau prompt Anda. Lihat image_too_complex untuk panduan tentang jenis input apa yang lebih sulit diproses.

format_conversion_failed

Kesalahan ini terjadi ketika model 3D yang dihasilkan tidak dapat dikonversi ke format output yang Anda minta. Model berhasil dibuat, tetapi langkah konversi gagal.

Resolusi:

1. Coba ulang permintaan.
2. Coba format output yang berbeda. Jika format tertentu terus gagal, beralihlah ke format lain yang sesuai dengan kebutuhan Anda.

Praktik Terbaik

1. Terapkan logika retry. Untuk Kesalahan timeout dan service_unavailable, terapkan logika retry exponential backoff.
2. Catat ID tugas. Selalu catat ID tugas untuk tujuan debugging. Sertakan ID tersebut saat menghubungi dukungan.
3. Validasi input. Pastikan gambar dan model input Anda memenuhi persyaratan format sebelum pengiriman.