Kesalahan

Cari tahu mengapa sebuah permintaan atau tugas gagal, dan apa yang harus dilakukan selanjutnya. Sebuah permintaan dapat langsung gagal dengan kesalahan HTTP, dan sebuah tugas dapat gagal kemudian dengan task_error.

Request errors

Meshy mengembalikan kesalahan ini segera, saat menolak sebuah request. Untuk mengetahui apa yang salah, periksa kode status HTTP dan field message.

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

Kesalahan tugas

Tugas yang dibuat oleh Meshy tetap bisa gagal saat berjalan. status-nya menjadi FAILED, Meshy mengembalikan kredit-nya, dan task_error menjelaskan alasannya.

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

type adalah kategori umum dari kegagalan tersebut. Gunakan ini untuk menentukan langkah selanjutnya.

Kode kesalahan

Saat code muncul, kode tersebut menyebutkan salah satu masalah berikut.

image_too_complex

Gambar input atau prompt menggambarkan subjek yang secara geometris terlalu kompleks untuk pembuatan 3D.

Sebagai contoh:

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

Input berikut kemungkinan besar terlalu kompleks:

Untuk memperbaikinya, coba satu atau beberapa cara berikut:

• Gunakan satu objek per gambar. Meshy bekerja paling baik dengan satu subjek yang jelas, jadi jangan menempatkan beberapa objek terpisah dalam gambar atau prompt yang sama.
• Sederhanakan subjek Anda. Misalnya, gunakan vas sederhana alih-alih vas yang dipenuhi puluhan bunga.
• Hindari pemandangan (scene). Seluruh bangunan, blok kota, ruangan berperabot, dan lanskap kemungkinan besar terlalu banyak. Fokuslah pada satu objek.
• Hindari struktur berulang yang padat. Perancah, jaring kawat, kisi-kisi, dan tumpukan barang kecil adalah pemicu umum.

model_missing_uv

Anda mengirim model untuk pembuatan tekstur dengan enable_original_uv yang diatur ke true, tetapi model tersebut tidak memiliki koordinat UV. Koordinat UV menentukan bagaimana tekstur 2D membungkus permukaan 3D.

Untuk memperbaikinya, lakukan salah satu hal berikut:

• Untuk mempertahankan tata letak UV model Anda sendiri, misalnya untuk penempatan sambungan (seam) khusus, tambahkan UV ke model di perangkat lunak 3D Anda. Periksa UV tersebut di editor UV-nya, lalu unggah model tersebut lagi. File STL tidak dapat menyimpan UV, jadi gunakan GLB, FBX, atau OBJ.
• Jika Anda tidak memerlukan tata letak Anda sendiri, atau tidak yakin, hilangkan enable_original_uv atau atur ke false. Meshy kemudian akan membuat tata letak UV untuk model tersebut. UV baru ini akan menutupi model dengan baik, tetapi Anda tidak dapat mengontrol di mana sambungan tekstur akan ditempatkan.

model_insufficient_uv

Model memiliki koordinat UV, tetapi koordinat tersebut mencakup terlalu sedikit ruang UV untuk dapat menghasilkan tekstur dengan baik. Hal ini sering terjadi pada model yang exporter-nya menuliskan UV placeholder atau UV yang kolaps tanpa unwrap yang tepat.

Untuk memperbaikinya, lakukan salah satu hal berikut:

• Untuk mempertahankan tata letak UV Anda sendiri, unwrap kembali koordinat UV model di software 3D Anda. Sebarkan island ke seluruh ruang UV, bukan hanya di sudut kecil darinya.
• Jika Anda tidak memerlukan tata letak Anda sendiri, hilangkan enable_original_uv atau atur ke false. Meshy kemudian akan membuat tata letak UV baru. Anda akan kehilangan penempatan seam Anda, tetapi UV baru tersebut mencakup ruang yang cukup untuk menghasilkan tekstur.

model_missing_texture

Model input pada tugas Multi-Color Print tidak memiliki warna yang dapat dipecah Meshy menjadi warna cetak. Meshy membangun 3MF multiwarna dari warna-warna model, sehingga mesh putih polos tidak memiliki apa pun untuk diolah. Misalnya, pratinjau Teks ke 3D atau Gambar ke 3D yang belum pernah diberi tekstur tidak memiliki warna. Begitu pula dengan output dari Perbaiki kemampuan cetak, atau tugas Auto Split yang tidak mempertahankan tekstur.

Apa yang dianggap sebagai warna bergantung pada style yang Anda minta:

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

Meshy menolak model yang tidak memiliki tekstur warna dasar maupun warna vertex untuk kedua gaya tersebut, alih-alih membiarkan cartoon mengubahnya menjadi cetakan satu warna.

Meshy menolak sebagian besar permintaan ini sebelum membuat tugas, dengan kode 400 dan penjelasan yang sama. Anda biasanya hanya mendapatkan kode ini saat Meshy tidak dapat memeriksa input terlebih dahulu. Misalnya, Meshy memeriksa unggahan .fbx hanya setelah tugas mengonversinya.

Untuk memperbaikinya, gunakan opsi yang sesuai dengan model Anda:

• Beri tekstur pada model terlebih dahulu. Jalankan Retexture padanya, atau buat dengan tugas refine Teks ke 3D atau tugas Gambar ke 3D dengan should_texture: true. Kemudian kirim tugas tersebut sebagai input_task_id.
• Untuk model dengan warna vertex, seperti pindaian fotogrametri atau mesh yang dicat tangan, gunakan style: "cartoon", yang membaca COLOR_0.
• Untuk model yang sebagian diberi tekstur atau multi-tekstur dengan realistic, berikan UV pada setiap bagian mesh dan tekstur warna dasar tunggal yang sama. Untuk melakukannya, beri tekstur pada bagian yang tersisa, atau gabungkan tekstur-tekstur tersebut menjadi satu atlas. Anda juga dapat beralih ke style: "cartoon".

textured_split_refused

Tugas Auto Split dengan keep_texture: true tidak dapat mempertahankan tekstur model input pada bagian-bagiannya. Misalnya, model tidak memiliki UV, atau teksturnya tidak memiliki ruang untuk permukaan baru yang dihasilkan oleh potongan. Meshy akan mengembalikan kredit.

Untuk memperbaikinya, kirim ulang permintaan tanpa keep_texture, atau dengan keep_texture: false. Bagian-bagian tersebut kemudian akan kembali dengan warna polos masing-masing.

invalid_input

Input gagal dalam pemeriksaan, dan tidak ada kode yang lebih spesifik yang berlaku. message memberikan alasannya.

Contohnya:

• File model kosong atau rusak
• Varian format file yang tidak didukung, seperti file FBX ASCII atau file GLB terkompresi meshopt
• Model yang diunggah tanpa objek 3D yang valid, misalnya file yang hanya berisi armature, kamera, atau cahaya
• Konten yang tidak lolos filter keamanan

Untuk memperbaikinya, baca message untuk mengetahui masalah spesifiknya. Periksa apakah file input dan parameter Anda memenuhi persyaratan endpoint.

moderation_blocked

Filter keamanan menolak prompt atau gambar referensi Anda. Filter ini memeriksa teks dan gambar secara bersamaan.

Untuk memperbaikinya, lakukan salah satu atau kedua hal berikut:

• Ubah redaksi prompt untuk menghilangkan deskripsi yang bersifat sugestif atau sensitif.
• Ganti gambar referensi yang menampilkan konten yang mungkin diblokir oleh filter.

moderation_unavailable

Tipe: server_error. Moderation konten untuk sementara tidak tersedia, sehingga Meshy menggagalkan tugas tersebut alih-alih melewati pemeriksaan. Tidak ada yang salah dengan konten Anda.

Untuk memperbaikinya, buat tugas tersebut kembali.

timeout

Tugas melewati batas waktu di sisi server, baik untuk pemrosesan maupun untuk menunggu dalam antrean, sehingga Meshy menggagalkannya dan mengembalikan kreditnya. Beban tinggi, atau input yang terlalu kompleks untuk diselesaikan tepat waktu, dapat menyebabkan hal ini.

Ini berbeda dari timeout di kode Anda sendiri. Jika klien Anda berhenti menunggu, tugas tersebut masih berjalan. Lihat Berapa lama harus menunggu.

Untuk memperbaikinya, ikuti langkah-langkah berikut:

1. Buat tugas lagi. Timeout sering kali bersifat sementara, dan tugas baru mungkin akan berhasil.
2. Jika terus gagal, sederhanakan input Anda, misalnya dengan mengurangi detail pada gambar atau prompt Anda. Untuk input yang lebih sulit diproses, lihat image_too_complex.

queue_timeout

Tipe: timeout. Tugas menunggu terlalu lama di antrean tanpa dimulai, sehingga Meshy menggagalkannya dan mengembalikan kredit yang dikenakan untuk tugas tersebut. Input Anda bukan penyebab kesalahan ini.

Untuk memperbaikinya, buat tugas tersebut lagi.

format_conversion_failed

Meshy berhasil membuat model, tetapi konversinya ke format yang Anda minta gagal.

Untuk memperbaikinya, ikuti langkah-langkah berikut:

1. Buat tugas tersebut lagi.
2. Jika satu format terus-menerus gagal, minta format lain yang sesuai dengan kebutuhan Anda.

Praktik terbaik

• Coba ulang task yang gagal. Untuk task yang gagal dengan timeout, service_unavailable, atau server_error, buat task baru dengan exponential backoff.
• Jangan buat task baru saat permintaan Anda sendiri mengalami timeout. Task pertama mungkin masih berjalan, jadi periksa apakah task tersebut ada sebelum Anda membuat task lainnya. Lihat Berapa lama harus menunggu.
• Catat ID task. Sertakan ID tersebut saat Anda menghubungi dukungan.
• Periksa input sebelum Anda mengirimkannya. Pastikan gambar dan model memenuhi persyaratan format endpoint.
• Panggil API dari server Anda. Kode yang berjalan di browser akan mengekspos kunci API Anda kepada siapa pun yang membuka halaman tersebut.