Kesalahan

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

Kesalahan Permintaan

Kesalahan ini dikembalikan segera saat permintaan API Anda ditolak. Periksa kode status HTTP dan kolom 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."
  }
}

Tipe Error

Field type memberitahu Anda kategori umum dari kegagalan tersebut. Gunakan ini untuk menentukan strategi percobaan ulang 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.

model_missing_texture

Kesalahan ini terjadi ketika model input dari tugas Multi-Color Print tidak memiliki informasi warna yang dapat dipisahkan oleh converter menjadi warna cetak. 3MF multiwarna dibangun dari warna model, sehingga mesh putih polos — misalnya preview Teks ke 3D atau Gambar ke 3D yang belum pernah diberi tekstur, atau output hasil perbaikan/auto-split — tidak memiliki bahan untuk diolah.

Apa yang dianggap sebagai sumber warna tergantung pada style yang Anda minta:

• realistic mengambil sampel tekstur warna dasar melalui koordinat UV model, sehingga memerlukan satu tekstur warna dasar dengan koordinat UV pada setiap bagian mesh.
• cartoon meratakan warna per permukaan (face) dan menerima tekstur warna dasar pada bagian mana pun atau warna per-vertex (COLOR_0).

Model yang tidak memiliki tekstur warna dasar maupun warna vertex akan ditolak untuk kedua style tersebut; dengan cartoon, jika tidak ditolak, model tersebut akan "berhasil" sebagai cetak satu warna.

Sebagian besar permintaan ditolak sebelum tugas dibuat (400 Bad Request dengan penjelasan yang sama), sehingga Anda biasanya hanya akan melihat kode ini ketika input tidak dapat diperiksa terlebih dahulu — misalnya unggahan .fbx diperiksa setelah tugas menormalkannya.

Penyelesaian:

• Beri tekstur pada model terlebih dahulu. Jalankan tugas Retexture padanya, atau buat model dengan pemberian tekstur diaktifkan (tugas refine Teks ke 3D, atau tugas Gambar ke 3D dengan should_texture: true), lalu berikan tugas tersebut sebagai input_task_id.
• Model dengan warna vertex (hasil pindaian fotogrametri, mesh yang dilukis manual): minta style: "cartoon", yang membaca COLOR_0.
• Model dengan tekstur sebagian atau multi-tekstur di bawah realistic: setiap bagian mesh memerlukan koordinat UV dan tekstur warna dasar yang sama dan tunggal. Beri tekstur pada bagian yang tersisa atau gabungkan tekstur-tekstur tersebut menjadi satu atlas, atau beralih ke style: "cartoon".

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 prompt teks maupun gambar referensi secara bersamaan.

Resolusi:

• Ubah kalimat prompt teks Anda untuk menghilangkan deskripsi yang bersifat sugestif atau sensitif.
• Sesuaikan gambar referensi jika gambar tersebut menampilkan konten yang dapat memicu filter keamanan.

moderation_unavailable

Kesalahan ini terjadi ketika moderation konten untuk sementara tidak tersedia, sehingga tugas dinyatakan gagal alih-alih dijalankan tanpa pemeriksaan. Tidak ada yang salah dengan konten Anda. type-nya adalah server_error.

Resolusi: Buat tugas tersebut lagi.

timeout

Error ini berarti tugas melebihi batas waktu di sisi server, baik untuk pemrosesan maupun saat menunggu dalam antrean, sehingga tugas gagal dan kreditnya dikembalikan. Hal ini dapat terjadi karena beban sistem yang tinggi atau karena input terlalu kompleks untuk diproses dalam batas waktu yang ditentukan.

Ini berbeda dengan timeout pada kode Anda sendiri. Jika klien Anda berhenti menunggu, tugas tersebut masih berjalan; lihat Task Lifecycle.

Penyelesaian:

1. Buat tugas lagi. Timeout sering kali bersifat sementara dan tugas baru mungkin berhasil.
2. Sederhanakan input Anda. Jika percobaan ulang terus gagal, input Anda mungkin terlalu kompleks. Coba kurangi tingkat detail pada gambar atau prompt Anda. Lihat image_too_complex untuk panduan mengenai jenis input apa saja yang lebih sulit diproses.

queue_timeout

Error ini berarti task menunggu di antrean terlalu lama tanpa dimulai, sehingga gagal dan kredit apa pun yang dikenakan untuknya dikembalikan. Input Anda tidak menyebabkan hal ini. type-nya adalah timeout.

Resolusi: Buat task tersebut lagi.

format_conversion_failed

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

Resolusi:

1. Coba lagi permintaan tersebut.
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 percobaan ulang. Ketika sebuah tugas gagal dengan error timeout, service_unavailable, atau server_error, buat ulang dengan exponential backoff. Jika permintaan Anda sendiri yang mengalami timeout, jangan membuat tugas baru: periksa dulu tugas yang sudah ada (lihat Siklus Hidup Tugas).
2. Catat ID tugas. Selalu catat ID tugas untuk keperluan debugging. Sertakan ID tersebut saat menghubungi dukungan.
3. Validasi input. Pastikan gambar dan model input Anda memenuhi persyaratan format sebelum dikirimkan.
4. Panggil API dari server Anda. Kode yang berjalan di browser akan membuka kunci API Anda kepada siapa pun yang membuka halaman tersebut.