API Keycap Creative Lab

Foto yang akan diubah menjadi desain keycap, sebagai URL publik atau data URI (data:image/jpeg;base64,<data gambar Anda yang dienkode base64>).

Gambar harus berupa file JPG, JPEG, PNG, atau WebP berukuran maksimal 20 MB (20.000.000 byte). Setiap sisi harus berukuran minimal 32 piksel, dan gambar dapat memiliki total maksimal 178.956.970 piksel. Gambar di luar batas ini mengembalikan 400.

Meshy mendeteksi format dari data gambar, bukan dari ekstensi file di URL. URL tanpa ekstensi tetap berfungsi, dan Meshy mengikuti pengalihan HTTP. Meshy menerapkan orientasi EXIF, sehingga foto ponsel yang berputar akan muncul sesuai tampilan aslinya.

Data URI harus dienkode base64 dengan jenis gambar, seperti data:image/png;base64,..., dan gambar yang didekode harus berupa JPEG, PNG, atau WebP. Batas 20 MB berlaku untuk gambar yang sudah didekode, sehingga teks base64-nya bisa sekitar sepertiga lebih besar.

Nama untuk tugas, hingga 100 karakter. Nama ini dikembalikan pada field name tugas. Nama yang lebih panjang mengembalikan 400.

Apakah akan menghapus latar belakang dari gambar prototipe. true mengembalikan PNG RGBA transparan, sehingga Anda dapat menempatkan keycap pada latar belakang apa pun. Jika Meshy tidak dapat menghapus latar belakang, Meshy mengembalikan gambar dengan latar belakangnya, dan tugas tetap berhasil.

Desain kepala yang diubah menjadi 3D oleh proses build tetap mempertahankan latar belakangnya terlepas dari pilihan ini. Build mewarnai dasar keycap dari gambar di image_urls, tanpa latar belakangnya jika Anda mengirim true. Build mengembalikan gambar tersebut sebagai process_image_urls.composite.

Permintaan tidak dapat dijalankan. Misalnya:

• image_url tidak ada.
• Gambar bukan file JPG, JPEG, PNG, atau WebP.
• Gambar terlalu kecil, lebih dari 20 MB, atau melebihi jumlah piksel maksimum.
• Meshy tidak dapat mengunduh gambar, misalnya karena URL mengembalikan 404 atau waktu habis (timeout).
• Data URI bukan base64 yang valid.
• Gambar ditandai sebagai NSFW.

Pesan error menjelaskan masalah apa yang ditemukan. Perbaiki permintaan, lalu kirim lagi.

Kunci API tidak ada atau tidak valid. Periksa header Authorization.

Salah satu dari berikut ini berlaku:

• Akun tidak memiliki kredit yang cukup.
• Kunci API, ruang kerja, atau anggota mencapai batas kreditnya.
• Akun menggunakan paket gratis.

Periksa kredit dan paket Anda, lalu coba lagi.

Tim Anda mengaktifkan IP Filtering, dan Meshy menandai gambar tersebut karena kekayaan intelektual pihak ketiga. Kirim gambar yang hak penggunaannya Anda miliki.

Salah satu batas berikut tercapai:

• Anda mengirim lebih banyak permintaan daripada yang diizinkan oleh batas laju Anda. Tunggu beberapa detik, lalu coba lagi. Lihat Batas laju.
• Terlalu banyak tugas Anda yang sedang dalam antrean atau berjalan. Tunggu hingga beberapa selesai, lalu coba lagi.
• Pada paket tak terbatas tanpa sisa kredit, Anda mencapai jumlah tugas yang dapat berjalan tanpa kredit. Tunggu hingga sebuah tugas selesai, atau tambahkan kredit.

Meshy mengalami kesalahan server, misalnya karena moderation konten atau pemeriksaan kekayaan intelektual tidak dapat dijalankan, atau Meshy tidak dapat menyimpan gambar. Meshy tidak membuat tugas tersebut, dan mengembalikan kredit apa pun yang telah dikenakan. Coba kirim permintaan lagi.

ID tugas prototipe yang akan dibuild. ID ini harus berupa tugas yang dibuat akun Anda dengan POST /openapi/creative-lab/keycap/v1/prototype, dengan status SUCCEEDED.

ID yang bukan merupakan salah satu tugas prototipe Keycap Anda dari API akan mengembalikan 404, termasuk prototipe yang dibuat di aplikasi web.

Kandidat yang akan dibuild, dari array candidate_ids milik tugas prototipe. Nilai yang tidak ada dalam array tersebut akan mengembalikan 400.

Nama untuk tugas, hingga 100 karakter. Nama ini akan muncul kembali di kolom name milik tugas. Nama yang lebih panjang akan mengembalikan 400.

Dasar keycap untuk dibuild. Satu-satunya nilai adalah cherry-mx-1x1-r1, sebuah keycap profil Cherry MX 1u standar. Ukuran kustom tidak didukung, dan nilai lain apa pun akan mengembalikan 400.

Ukuran kepala sepanjang dimensi terpanjangnya, dalam milimeter, dari 10 hingga 40. Meshy menskalakan kepala sehingga dimensi terpanjangnya sesuai dengan nilai ini. Nilai di luar rentang akan mengembalikan 400.

Untuk nilai di atas sekitar 32.9, Meshy mungkin mengurangi ukurannya agar kepala sesuai dengan batas jejak pelindung dasar. Kepala kemudian dapat menjadi lebih kecil dari yang Anda minta. Objek tugas tidak mengembalikan ukuran yang diterapkan Meshy. Untuk memeriksanya, ukur kotak pembatas dari mesh keycap-head di dalam model.

Offset vertikal yang diterapkan pada kepala sebelum Meshy mendudukkannya pada dasar, dalam milimeter, dari -5 hingga 5. Nilai di luar rentang akan mengembalikan 400.

Permintaan tidak dapat dijalankan. Misalnya:

• input_task_id tidak ada atau bukan ID tugas yang valid.
• Status tugas prototipe bukan SUCCEEDED. Jika masih berjalan, tunggu dan coba lagi. Jika gagal atau dibatalkan, buat tugas prototipe baru.
• Tugas prototipe berhasil tetapi tidak memiliki kandidat. Buat tugas prototipe baru.
• candidate_id tidak ada, atau tidak ada dalam candidate_ids milik tugas prototipe. Kirim nilai dari array tersebut.
• Sebuah kolom dalam options berada di luar rentang, atau base_model bukan nilai yang tersedia.

Pesan error menunjukkan masalah mana yang ditemukan.

Kunci API tidak ada atau tidak valid. Periksa header Authorization.

Salah satu dari ini berlaku:

• Akun tidak memiliki cukup kredit.
• Kunci API, ruang kerja, atau anggota mencapai batas kreditnya.
• Akun berada pada paket gratis.

Periksa kredit dan paket Anda, lalu coba lagi.

input_task_id tidak cocok dengan tugas prototipe Keycap mana pun yang dibuat akun Anda dengan API. Prototipe yang dibuat di aplikasi web juga akan mengembalikan 404. Kirim ID result dari respons pembuatan prototipe.

Salah satu batas berikut tercapai:

• Anda mengirim lebih banyak permintaan daripada yang diizinkan oleh batas laju Anda. Tunggu beberapa detik, lalu coba lagi. Lihat Batas laju.
• Terlalu banyak tugas Anda yang sedang dalam antrean atau berjalan. Tunggu hingga beberapa selesai, lalu coba lagi.
• Pada paket tak terbatas tanpa sisa kredit, Anda telah mencapai jumlah tugas yang dapat berjalan tanpa kredit. Tunggu hingga sebuah tugas selesai, atau tambahkan kredit.

Meshy tidak dapat membuat tugas karena kesalahan server. Meshy mengembalikan kredit apa pun yang telah dibebankannya. Coba lagi permintaan tersebut.

ID task dari respons create.

id bukan ID task yang valid. Kirim ID result dari respons create.

Tim Anda mengaktifkan IP Filtering, dan Meshy menandai gambar task prototype tersebut karena kekayaan intelektual pihak ketiga. Task build dan tim pada paket Enterprise tidak mendapatkan error ini. Buat task prototype dari gambar yang hak penggunaannya Anda miliki.

Tidak ada task Keycap dengan ID ini yang dimiliki akun Anda, atau stage task tidak sesuai dengan path. Periksa ID-nya, dan gunakan /prototype atau /build yang sesuai dengan task tersebut.

Meshy tidak dapat menjalankan pemeriksaan kekayaan intelektual. Coba lagi permintaan tersebut.

ID task yang akan dibatalkan.

Salah satu dari hal berikut berlaku:

• id bukan ID task yang valid. Kirim ID result dari respons pembuatan.
• Task sudah memiliki status akhir (SUCCEEDED, FAILED, atau CANCELED), sehingga tidak dapat dibatalkan.

Tidak ada task Keycap dengan ID ini yang dimiliki oleh akun Anda, atau tahap task tidak cocok dengan path. Periksa ID-nya, dan gunakan /prototype atau /build yang sesuai dengan task tersebut.

Meshy mengalami kesalahan server saat membatalkan task, sehingga task mungkin sudah atau belum dibatalkan. Ambil task tersebut untuk memeriksa status-nya sebelum Anda mencoba lagi.

ID task dari respons pembuatan.

Tahap yang akan ditampilkan, prototype atau build.

Halaman yang akan dikembalikan, dari 1 hingga 255. 0 mengembalikan halaman pertama. Nilai di luar 0 hingga 255 akan mengembalikan 400.

Jumlah tugas per halaman, hingga 100. Nilai dari 101 hingga 255 akan mengembalikan 100 tugas, dan 0 menggunakan nilai default. Nilai di luar 0 hingga 255 akan mengembalikan 400.

Urutan pengurutan.

Nilai yang tersedia:

• -created_at: terbaru lebih dulu
• +created_at: terlama lebih dulu

ID tugas. Jangan bergantung pada formatnya.

Tipe tugas, selalu creative-lab-keycap-prototype.

name yang Anda kirim saat membuat tugas, atau "" jika Anda tidak mengirimkannya.

Status tugas.

Nilai yang tersedia:

• PENDING: menunggu dalam antrean
• IN_PROGRESS: menghasilkan hasil
• SUCCEEDED: final, dengan hasil
• FAILED: final, dengan alasan di task_error
• CANCELED: final, tanpa hasil

Persentase pekerjaan yang telah selesai, dari 0 hingga 100. Nilainya 0 hingga tugas dimulai dan 100 saat berhasil.

Waktu tugas dibuat, dalam milidetik Unix.

Waktu seorang worker memulai tugas, dalam milidetik Unix. null hingga saat itu.

Waktu tugas mencapai status final, dalam milidetik Unix. null hingga saat itu.

Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 3 hari setelah finished_at, atau 3 hari setelah created_at hingga tugas selesai. Untuk akun Enterprise, yang menyimpan hasil API tanpa batas waktu, nilainya sekitar 100 tahun kemudian. Lihat Retensi aset.

Posisi tugas dalam antrean selagi berstatus PENDING. 1 berarti tugas ini berikutnya yang akan dimulai. 0 setelah tugas keluar dari antrean, dan selalu 0 dalam hasil daftar.

Alasan tugas gagal. null kecuali status adalah FAILED. Lihat Kesalahan.

Jumlah kredit yang dikenakan untuk tugas, setelah pengembalian dana (jika ada). Permintaan yang mengembalikan kesalahan tidak dikenakan biaya. Tugas yang gagal bernilai 0, karena Meshy mengembalikan dananya. Membatalkan tugas hanya mengembalikan dana selagi tugas berstatus PENDING. Jika Meshy tidak dapat membaca biaya yang dikenakan, respons get atau stream akan menghilangkan field ini, dan permintaan daftar akan mengembalikan 500. Dalam kasus tersebut, coba lagi permintaannya.

URL unduhan untuk gambar keycap jadi. Array ini berisi satu URL setelah tugas berhasil, dan kosong hingga saat itu. image_urls[i] menampilkan kandidat di candidate_ids[i].

URL ini digunakan untuk ditampilkan. Build endpoint mengambil entri dari candidate_ids, bukan URL. URL ini adalah signed URL, jadi ambil tanpa header Authorization. URL tetap berlaku hingga expires_at, dan mengambil tugas kembali akan mengembalikan URL yang sama.

ID kandidat, dalam urutan yang sama dengan image_urls. Untuk membangun sebuah kandidat, kirim ID-nya sebagai candidate_id dalam permintaan build. Jangan bergantung pada format ID ini.

ID tugas. Jangan bergantung pada formatnya.

Jenis tugas, selalu creative-lab-keycap-build.

name yang Anda kirim saat membuat tugas, atau "" jika Anda tidak mengirimkannya.

Status tugas.

Nilai yang tersedia:

• PENDING: menunggu dalam antrean
• IN_PROGRESS: sedang menghasilkan hasil
• SUCCEEDED: final, dengan hasil
• FAILED: final, dengan alasan di task_error
• CANCELED: final, tanpa hasil

Persentase pekerjaan yang telah selesai, dari 0 hingga 100. Nilainya 0 hingga tugas dimulai dan 100 ketika berhasil.

Waktu tugas dibuat, dalam milidetik Unix.

Waktu sebuah worker memulai tugas, dalam milidetik Unix. null sampai saat itu.

Waktu tugas mencapai status final, dalam milidetik Unix. null sampai saat itu.

Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 3 hari setelah finished_at, atau 3 hari setelah created_at sampai tugas selesai. Untuk akun Enterprise, yang menyimpan hasil API tanpa batas waktu, nilainya sekitar 100 tahun kemudian. Lihat Retensi aset.

Posisi tugas dalam antrean selama statusnya PENDING. 1 berarti tugas ini akan dimulai berikutnya. 0 setelah tugas keluar dari antrean, dan selalu 0 dalam hasil daftar (list).

Alasan tugas gagal. null kecuali status adalah FAILED. Lihat Kesalahan.

Jumlah kredit yang dikenakan untuk tugas ini, setelah dikurangi pengembalian dana (refund) jika ada. Permintaan yang mengembalikan kesalahan tidak akan dikenakan biaya. Tugas yang gagal bernilai 0, karena Meshy mengembalikan dananya. Membatalkan tugas hanya mengembalikan dana selama tugas masih PENDING. Jika Meshy tidak dapat membaca biaya yang dikenakan, respons get atau stream akan menghilangkan field ini, dan permintaan list akan mengembalikan 500. Dalam kasus ini, coba lagi permintaan tersebut.

URL unduhan untuk model 3D. Meshy mengekspor file GLB dan bundel OBJ dalam skala dunia nyata dalam milimeter, Y-up, dengan bagian depan keycap menghadap +Z.

Model ini memiliki mesh bernama keycap-head dan keycap-base. Ketika Meshy beralih ke pengisian pola (pattern fill) untuk base, model juga memiliki mesh keycap-base-interior untuk rongga stem. Jangan asumsikan model selalu memiliki tepat dua mesh.

Ini adalah URL yang ditandatangani (signed URLs), jadi ambil tanpa header Authorization. URL ini tetap berlaku hingga expires_at, dan mengambil tugas yang sama lagi sebelum itu akan mengembalikan URL yang sama. URL yang telah kedaluwarsa tidak dapat diperbarui, jadi unduh dan simpan file-file tersebut sebelum itu terjadi.

URL unduhan untuk gambar dari langkah-langkah build, dikelompokkan berdasarkan jenisnya. Seperti model_urls, ini adalah URL yang ditandatangani (signed URLs), jadi ambil tanpa header Authorization. URL ini tetap berlaku hingga expires_at, dan mengambil tugas lagi akan mengembalikan URL yang sama.

Objek ini dapat memiliki kunci-kunci berikut:

• head_design: gambar desain dari kandidat yang dipilih, yang diubah oleh build menjadi 3D. Selalu ada.
• composite: gambar keycap jadi untuk kandidat yang dipilih, yang menjadi dasar pewarnaan base oleh build. Bisa saja tidak ada.
• base_canvas: base keycap yang telah diwarnai. Bisa saja tidak ada.

Meshy dapat menambahkan kunci baru, jadi abaikan kunci yang tidak Anda kenali.