Kesalahan

Dalam panduan ini, kita akan membahas apa yang terjadi ketika ada sesuatu yang tidak beres 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."
  }
}

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.

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 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.