Kesalahan

Dalam panduan ini, kita akan membahas tentang apa yang terjadi ketika sesuatu tidak berjalan dengan baik saat Anda bekerja dengan Meshy API.

Kesalahan Permintaan

Kesalahan-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 sebuah tugas telah 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

Kolom type memberi tahu Anda kategori umum dari kegagalan. Gunakan ini untuk memutuskan strategi pengulangan Anda.

Kode Kesalahan

Ketika bidang code ada, itu 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 menggambarkan subjek yang terlalu kompleks secara geometris untuk diproses oleh model generasi 3D.

Contoh umum termasuk:

• Tumpukan padat dari objek kecil (misalnya, peti penuh buah, tumpukan buku)
• Pola berulang yang rumit (misalnya, struktur kisi, perancah, jaring kawat)
• Struktur bangunan yang 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 diisi dengan puluhan bunga.
3. Hindari prompt tingkat adegan. Seluruh bangunan, blok kota, interior yang penuh dengan furnitur, atau lanskap kemungkinan akan melebihi 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 ketika Anda mengunggah model untuk tekstur dengan enable_original_uv diatur ke true, tetapi model tersebut tidak memiliki koordinat UV. Koordinat UV menentukan bagaimana tekstur 2D membungkus permukaan 3D dari model Anda.

Resolusi:

Perbaikan yang tepat tergantung pada mengapa Anda mengatur enable_original_uv ke true:

• Jika Anda perlu mempertahankan tata letak UV asli model Anda (misalnya, penempatan jahitan khusus untuk pemetaan tekstur yang tepat): model Anda harus memiliki koordinat UV yang valid. Verifikasi UV ada 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 spesifik (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 secara otomatis dioptimalkan untuk cakupan tetapi Anda tidak akan memiliki kontrol atas di mana jahitan tekstur ditempatkan.

model_insufficient_uv

Kesalahan ini terjadi ketika sebuah model memiliki koordinat UV, tetapi cakupan UV terlalu kecil untuk tekstur berkualitas. Ini biasanya terjadi dengan model yang diekspor dari alat 3D yang menghasilkan UV placeholder atau UV yang terlipat tanpa pembukaan yang tepat.

Resolusi:

• Jika Anda perlu mempertahankan tata letak UV asli Anda: buka kembali UV model di perangkat lunak 3D Anda. Pastikan pulau UV tersebar dengan baik di seluruh ruang UV daripada terlipat ke area kecil.
• Jika Anda tidak memerlukan kontrol UV spesifik: hilangkan enable_original_uv atau atur ke false. Sistem akan secara otomatis menghasilkan tata letak UV baru. Konsekuensinya adalah Anda kehilangan penempatan jahitan asli Anda, tetapi UV yang dihasilkan secara otomatis akan memiliki cakupan yang tepat untuk tekstur.

invalid_input

Ini adalah kode kesalahan cadangan ketika input gagal validasi tetapi tidak ada kode yang lebih spesifik yang berlaku. Bidang message berisi alasan spesifik untuk kegagalan tersebut.

Penyebab umum termasuk:

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

Resolusi: Periksa bidang message untuk rincian tentang apa yang salah. Verifikasi bahwa file dan parameter input Anda sesuai dengan persyaratan endpoint.

moderation_blocked

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

Resolusi:

• Ubah ulang teks prompt Anda untuk menghilangkan deskripsi yang sugestif atau sensitif.
• Sesuaikan gambar referensi jika mereka 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, mungkin input Anda terlalu kompleks. Cobalah mengurangi tingkat detail dalam gambar atau prompt Anda. Lihat image_too_complex untuk panduan tentang jenis input yang lebih sulit diproses.

format_conversion_failed

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

Resolusi:

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

Praktik Terbaik

1. Terapkan logika ulang. Untuk kesalahan timeout dan service_unavailable, terapkan logika ulang dengan backoff eksponensial.
2. Catat ID tugas. Selalu catat ID tugas untuk keperluan debugging. Sertakan saat menghubungi dukungan.
3. Validasi masukan. Pastikan gambar dan model masukan Anda memenuhi persyaratan format sebelum pengiriman.