Creative Lab — Keycap API

Foto sumber yang akan diubah Meshy menjadi gambar desain keycap. Kami saat ini mendukung format .jpg, .jpeg, .png, dan .webp.

Format dideteksi dengan mendekode data gambar, bukan dari ekstensi file pada URL — URL tanpa ekstensi, atau yang melakukan redirect, tetap berfungsi selama byte-nya terdekode menjadi format yang didukung. HTTP redirect akan diikuti. Orientasi EXIF dinormalisasi, sehingga foto ponsel yang berputar digunakan sesuai tampilannya.

Batasan: minimal 32 piksel pada setiap sisi, maksimal 178.956.970 piksel secara total, dan maksimal 20.000.000 byte setelah diunduh. Untuk data URI, batasan berlaku pada byte yang sudah didekode, sehingga file sumber itu sendiri boleh mencapai ukuran tersebut — teks base64-nya sekitar sepertiga lebih besar, yang berpengaruh pada isi permintaan Anda, bukan pada batasan ini. Data URI harus mendeklarasikan tipe konten image/* dan ;base64.

Ada dua cara untuk menyediakan gambar:

• URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
• Data URI: Data URI gambar yang dikodekan base64. Contoh data URI: data:image/jpeg;base64,<data gambar Anda yang dikodekan base64>.

Nama task opsional untuk keperluan tampilan. Maksimal 100 karakter.

Jika diatur ke true, render tampilan yang dikembalikan dalam image_urls berupa PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkannya dengan latar belakang apa pun.

Ini hanya berlaku untuk render tampilan. Kandidat yang dikonsumsi oleh build endpoint tidak terpengaruh, sehingga hasil 3D-nya identik dalam kedua kasus.

Permintaan tidak dapat diterima. Penyebab umum:

• Parameter hilang: image_url wajib diisi.
• Format gambar tidak valid: image_url yang diberikan bukan format yang didukung (.jpg, .jpeg, .png, .webp).
• Dimensi gambar di luar rentang: Gambar terlalu kecil, melebihi ukuran file maksimum, atau melebihi jumlah piksel maksimum.
• URL tidak dapat dijangkau: image_url tidak dapat diunduh (404 atau timeout).
• Data URI tidak valid: String base64 tidak valid formatnya.
• Konten ditandai: Gambar input ditandai oleh moderation NSFW.

Autentikasi gagal. Silakan periksa kunci API Anda.

Akun menggunakan paket gratis (paket berbayar diperlukan untuk membuat task) atau kreditnya tidak mencukupi.

Gambar input ditandai oleh moderation kekayaan intelektual.

Anda telah melampaui batas laju Anda.

Terjadi kesalahan tak terduga di sisi server — misalnya layanan moderation konten tidak tersedia, penyiapan gambar input gagal, atau task tidak dapat dibuat. Dalam kasus ini tidak ada task yang dibuat, sehingga aman untuk mencoba lagi.

ID task dari task prototipe yang dibuat melalui endpoint OpenAPI yang sama ini. Prototipe tersebut harus dibuat oleh akun Meshy yang sama, harus telah mencapai status SUCCEEDED, dan harus telah menghasilkan setidaknya satu kandidat.

Task prototipe yang dibuat melalui webapp tidak diterima — endpoint build hanya menerima task prototipe yang dihasilkan oleh POST /openapi/creative-lab/keycap/v1/prototype dan menolak sumber lain mana pun dengan 404.

Kandidat yang akan dibangun, diambil dari array candidate_ids milik task prototipe yang berhasil. Harus termasuk dalam task tersebut; nilai lain mana pun akan ditolak dengan 400.

Nama task opsional untuk keperluan tampilan. Maksimum 100 karakter.

Dasar keycap yang akan digunakan untuk build. Saat ini satu-satunya nilai yang tersedia adalah cherry-mx-1x1-r1 — keycap 1u profil Cherry MX standar. 3–5 ukuran standar mainstream tambahan sedang direncanakan; ukuran kustom tidak didukung.

Ukuran target dari kepala yang dipahat, dalam milimeter: dimensi terpanjangnya diskalakan ke nilai ini. Rentang: [10, 40]. Nilai di atas kira-kira 32.9 dapat dikurangi agar kepala tetap sesuai dengan batas jejak (footprint) pelindung dasar, sehingga dimensi terpanjang yang dihasilkan bisa lebih kecil dari yang diminta. Nilai yang diterapkan belum ditampilkan kembali pada objek task saat ini — jika Anda perlu memastikan ukuran yang sebenarnya Anda terima, ukur kotak pembatas mesh keycap-head pada model yang diunduh.

Offset vertikal yang diterapkan pada kepala sebelum ditempatkan pada dasar, dalam milimeter. Rentang: [-5, 5].

Permintaan tidak dapat diterima. Penyebab umum:

• Parameter hilang: input_task_id dan candidate_id wajib diisi.
• UUID tidak valid: input_task_id bukan UUID yang valid.
• Induk belum berhasil: Task prototipe yang dirujuk belum mencapai SUCCEEDED.
• Tidak ada kandidat: Task prototipe berhasil tetapi tidak menghasilkan kandidat apa pun.
• Kandidat tidak dikenal: candidate_id bukan salah satu kandidat dari task input.
• Options di luar rentang: Salah satu field options berada di luar rentang yang diizinkan atau di luar kumpulan enum-nya.

Autentikasi gagal. Silakan periksa kunci API Anda.

Akun berada pada paket gratis (diperlukan paket berbayar untuk membuat task) atau kredit tidak mencukupi.

Task prototipe yang dirujuk tidak ada, dimiliki oleh pengguna lain, atau dibuat melalui webapp (hanya task prototipe mode API yang dapat dilanjutkan ke build).

Anda telah melampaui batas laju Anda.

Terjadi kesalahan sisi server yang tidak terduga — misalnya layanan moderation konten tidak tersedia, penyiapan (staging) gambar input gagal, atau task tidak dapat dibuat. Dalam kasus ini tidak ada task yang dibuat, sehingga mencoba ulang aman dilakukan.

Pengenal unik untuk tugas keycap yang akan diambil.

Pengenal unik untuk tugas keycap yang akan dibatalkan.

Tugas sudah berada pada status akhir dan tidak dapat dibatalkan.

Tugas tidak ada, milik pengguna lain, atau tahapnya tidak sesuai dengan jalur URL.

Terjadi kesalahan tak terduga di sisi server saat membatalkan. Tugas mungkin sudah atau belum dibatalkan — baca ulang untuk memastikan sebelum mencoba lagi.

Pengenal unik untuk task keycap yang akan di-stream.

Baik prototype maupun build. Koleksi ini hanya mengembalikan tugas yang tahapnya cocok dengan URL — mengambil /prototype tidak pernah mengembalikan tugas build, begitu juga sebaliknya.

Nomor halaman untuk paginasi.

Batas ukuran halaman. Maksimum yang diizinkan adalah 100 item.

Field untuk mengurutkan. Nilai yang tersedia:

• +created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
• -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.

Pengenal unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara k (k-sortable) untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

Tipe dari task. Nilainya adalah creative-lab-keycap-prototype.

Nama task yang diberikan saat task dibuat. String kosong jika tidak ada nama yang diberikan.

Status dari task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, nilai ini akan menjadi 100.

Stempel waktu saat task dibuat, dalam milidetik.

Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.

Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.

Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.

Jumlah task yang mendahului.

Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

Jumlah kredit yang dikonsumsi oleh task ini. Task yang mencapai SUCCEEDED akan dikenakan biaya penuh untuk tahapnya. Task yang tidak pernah berhasil dibuat (sebuah 4xx pada saat permintaan, termasuk penolakan moderation) tidak dikenakan biaya sama sekali. Task yang mencapai FAILED mengembalikan 0 — biaya dikembalikan (refund), termasuk pemblokiran moderation asinkron. Membatalkan melalui DELETE hanya mengembalikan biaya selama task masih PENDING; task yang sudah IN_PROGRESS tetap dikenakan biaya, karena pekerjaannya sudah dilakukan.

URL yang dapat diunduh dari render desain keycap yang sudah jadi — seperti apa tampilan kandidat sebagai keycap jadi. Menyimpan satu entri; image_urls[i] berkorespondensi dengan candidate_ids[i]. Kosong hingga task mencapai SUCCEEDED. URL ini hanya untuk tampilan; endpoint build mengonsumsi candidate_ids, bukan URL ini. Siklus hidup URL sama seperti model_urls: bertanda tangan (signed), tanpa header Authorization, berlaku hingga expires_at, dan stabil saat task dibaca ulang.

Pengenal kandidat yang bersifat opak, sejajar dengan image_urls. Kirimkan entri yang sesuai dengan desain pilihan Anda sebagai candidate_id pada permintaan build. Jangan membuat asumsi apa pun tentang format id ini.

Pengenal unik untuk task ini.

Jenis task. Nilainya adalah creative-lab-keycap-build.

Nama task yang diberikan saat task dibuat. String kosong jika tidak ada nama yang diberikan.

Status task. Kemungkinan nilainya adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, ini akan menjadi 100.

Stempel waktu saat task dibuat, dalam milidetik.

Stempel waktu saat task dimulai, dalam milidetik.

Stempel waktu saat task selesai, dalam milidetik.

Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.

Jumlah task yang mendahului. Hanya bermakna ketika status adalah PENDING.

Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

Jumlah kredit yang dikonsumsi oleh task ini. Task yang mencapai SUCCEEDED akan dikenakan biaya penuh untuk tahapannya. Task yang tidak pernah dibuat (4xx pada saat request, termasuk penolakan moderation) sama sekali tidak dikenakan biaya. Task yang mencapai FAILED mengembalikan 0 — biaya dikembalikan, termasuk blokir moderation asinkron. Membatalkan melalui DELETE hanya mengembalikan biaya selama task masih PENDING; task yang sudah IN_PROGRESS tetap dikenakan biaya, karena pekerjaannya telah digunakan.

URL yang dapat diunduh untuk artefak model yang dihasilkan. Baik bundel GLB maupun OBJ diekspor pada skala milimeter dunia nyata, Y-up, dengan bagian depan keycap menghadap +Z. Mesh diberi nama keycap-head dan keycap-base; ketika base beralih ke pola isian (pattern fill), mesh ketiga keycap-base-interior juga tersedia untuk rongga stem. Jangan berasumsi bahwa hanya ada tepat dua mesh.

Ini adalah URL yang ditandatangani (signed): ambil tanpa header Authorization. URL ini tetap valid hingga expires_at, yaitu 3 hari setelah finished_at, dan membaca ulang task dalam rentang waktu tersebut akan mengembalikan URL yang identik, bukan URL yang baru ditandatangani. Unduh dan simpan file tersebut sendiri sebelum waktu itu — tidak ada cara untuk memperbarui tautan yang sudah kedaluwarsa.

URL yang dapat diunduh untuk gambar proses perantara, dikelompokkan berdasarkan jenisnya (kind). Siklus hidup URL sama seperti model_urls: ditandatangani (signed), tanpa header Authorization, valid hingga expires_at, dan stabil ketika task dibaca ulang. Jenis yang saat ini dihasilkan:

• head_design — gambar desain kandidat terpilih yang digunakan oleh build (selalu ada).
• composite — render tampilan keycap jadi dari kandidat terpilih (ada jika tersedia).
• base_canvas — kanvas base keycap yang telah dicat (ada jika tersedia).

Perlakukan kumpulan key ini sebagai terbuka (open-ended); jenis baru dapat ditambahkan tanpa perubahan yang bersifat breaking change.