Creative Lab — Keycap API

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

Format dideteksi dengan mendekode data gambar, bukan dari ekstensi file URL — URL tanpa ekstensi, atau yang mengarahkan ulang, berfungsi selama byte dapat didekode ke format yang didukung. Pengalihan HTTP diikuti. Orientasi EXIF dinormalisasi, sehingga foto ponsel yang diputar digunakan sesuai tampilannya.

Batasan: setidaknya 32 piksel di setiap sisi, paling banyak 178,956,970 piksel secara total, dan paling banyak 20,000,000 byte setelah diunduh. Untuk Data URI, batasan berlaku untuk byte yang didekode, sehingga file sumber itu sendiri dapat mencapai ukuran tersebut — teks base64 yang sekitar sepertiga lebih besar, yang penting untuk body permintaan Anda, bukan untuk batasan ini. Data URI harus menyatakan 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 yang dikodekan base64 dari gambar. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Nama tugas opsional untuk tujuan tampilan. Maksimal 100 karakter.

Ketika diatur ke true, render tampilan yang dikembalikan dalam image_urls adalah PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkannya ke latar belakang mana pun.

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

Permintaan tidak dapat diterima. Penyebab umum:

• Parameter hilang: image_url diperlukan.
• Format gambar tidak valid: image_url yang diberikan bukan format yang didukung (.jpg, .jpeg, .png, .webp).
• Dimensi gambar di luar jangkauan: 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 rusak.
• Konten ditandai: Gambar input ditandai oleh moderation NSFW.

Autentikasi gagal. Silakan periksa kunci API Anda.

Akun berada pada paket gratis (paket berbayar diperlukan untuk membuat tugas) atau tidak memiliki kredit yang cukup.

Gambar input ditandai oleh moderation hak kekayaan intelektual.

Anda telah melebihi batas laju Anda.

Terjadi kesalahan server yang tidak terduga — misalnya layanan moderation konten tidak tersedia, staging gambar input gagal, atau tugas tidak dapat dibuat. Tidak ada tugas yang dibuat dalam kasus ini, jadi mencoba lagi aman.

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

Tugas prototipe yang dibuat melalui webapp tidak diterima — endpoint pembuatan hanya menerima tugas prototipe yang dihasilkan oleh POST /openapi/creative-lab/keycap/v1/prototype dan menolak sumber lain dengan 404.

Kandidat untuk dibangun, diambil dari array candidate_ids dari tugas prototipe yang berhasil. Harus milik tugas tersebut; nilai lain ditolak dengan 400.

Nama tugas opsional untuk tujuan tampilan. Maksimum 100 karakter.

Dasar keycap untuk dibangun. Saat ini satu-satunya nilai yang tersedia adalah cherry-mx-1x1-r1 — profil Cherry MX standar 1u. 3–5 ukuran standar mainstream tambahan 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 sekitar 32.9 dapat dikurangi sehingga kepala masih sesuai dengan batas jejak pelindung dasar, sehingga dimensi terpanjang yang dikirimkan bisa lebih kecil dari yang diminta. Nilai yang diterapkan tidak dikembalikan pada objek tugas hari ini — jika Anda perlu mengonfirmasi ukuran yang sebenarnya Anda terima, ukur kotak pembatas dari mesh keycap-head dalam model yang diunduh.

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

Permintaan tidak dapat diterima. Penyebab umum:

• Parameter hilang: input_task_id dan candidate_id diperlukan.
• UUID tidak valid: input_task_id bukan UUID yang valid.
• Induk tidak berhasil: Tugas prototipe yang dirujuk belum mencapai SUCCEEDED.
• Tidak ada kandidat: Tugas prototipe berhasil tetapi tidak menghasilkan kandidat.
• Kandidat tidak dikenal: candidate_id bukan salah satu kandidat tugas input.
• Opsi di luar jangkauan: Salah satu bidang options berada di luar rentang yang diizinkan atau set enum.

Autentikasi gagal. Silakan periksa kunci API Anda.

Akun berada pada paket gratis (paket berbayar diperlukan untuk membuat tugas) atau tidak memiliki kredit yang cukup.

Tugas prototipe yang dirujuk tidak ada, milik pengguna lain, atau dibuat melalui webapp (hanya tugas prototipe mode API yang dapat dirantai ke pembuatan).

Anda telah melebihi batas laju Anda.

Terjadi kesalahan tak terduga di sisi server — misalnya layanan moderasi konten tidak tersedia, staging gambar input gagal, atau tugas tidak dapat dibuat. Tidak ada tugas yang dibuat dalam kasus ini, jadi mencoba lagi aman.

Pengenal unik untuk tugas keycap yang akan diambil.

Pengenal unik untuk tugas keycap yang akan dibatalkan.

Tugas sudah dalam status akhir dan tidak dapat dibatalkan.

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

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

Pengenal unik untuk tugas keycap yang akan di-stream.

Baik prototype atau build. Koleksi hanya mengembalikan tugas yang tahapnya sesuai dengan URL — mengambil /prototype tidak pernah mengembalikan tugas build dan sebaliknya.

Nomor halaman untuk paginasi.

Batas ukuran halaman. Maksimum yang diizinkan adalah 100 item.

Bidang untuk diurutkan. Nilai yang tersedia:

• +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
• -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Pengenal unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id.

Jenis tugas. Nilainya adalah creative-lab-keycap-prototype.

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

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

Kemajuan tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.

Stempel waktu saat tugas dibuat, dalam milidetik.

Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.

Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.

Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.

Jumlah tugas sebelumnya.

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

Jumlah kredit yang dikonsumsi oleh tugas ini. Tugas yang mencapai SUCCEEDED dikenakan biaya penuh untuk tahapannya. Tugas yang tidak pernah dibuat (kesalahan 4xx saat permintaan, termasuk penolakan moderasi) tidak dikenakan biaya sama sekali. Tugas yang mencapai FAILED mengembalikan 0 — biaya dikembalikan, termasuk blok moderasi asinkron. Pembatalan melalui DELETE hanya mengembalikan biaya saat tugas masih PENDING; tugas yang sudah IN_PROGRESS tetap dikenakan biaya, karena pekerjaan telah dilakukan.

URL yang dapat diunduh dari render desain keycap selesai — seperti apa kandidat terlihat sebagai keycap selesai. Memiliki satu entri; image_urls[i] sesuai dengan candidate_ids[i]. Kosong sampai tugas mencapai SUCCEEDED. URL ini hanya untuk tampilan; endpoint pembuatan mengonsumsi candidate_ids, bukan URL ini. Siklus hidup URL sama dengan model_urls: ditandatangani, tanpa header Authorization, berlaku hingga expires_at, dan stabil saat tugas dibaca ulang.

Pengenal kandidat yang tidak transparan, paralel dengan image_urls. Kirim entri yang sesuai dengan desain pilihan Anda sebagai candidate_id permintaan pembuatan. Jangan membuat asumsi apa pun tentang format id ini.

Pengenal unik untuk tugas tersebut.

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

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

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

Kemajuan dari tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, ini akan menjadi 100.

Stempel waktu saat tugas dibuat, dalam milidetik.

Stempel waktu saat tugas dimulai, dalam milidetik.

Stempel waktu saat tugas selesai, dalam milidetik.

Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.

Jumlah tugas sebelumnya. Bermakna hanya ketika status adalah PENDING.

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

Jumlah kredit yang dikonsumsi oleh tugas ini. Tugas yang mencapai SUCCEEDED dikenakan biaya penuh untuk tahapannya. Tugas yang tidak pernah dibuat (kesalahan 4xx saat permintaan, termasuk penolakan moderasi) tidak dikenakan biaya sama sekali. Tugas yang mencapai FAILED mengembalikan 0 — biaya dikembalikan, termasuk blok moderasi asinkron. Pembatalan melalui DELETE hanya mengembalikan biaya saat tugas masih PENDING; tugas yang sudah IN_PROGRESS tetap dikenakan biaya, karena pekerjaan telah dilakukan.

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 dinamai keycap-head dan keycap-base; ketika dasar kembali ke pola isian, mesh ketiga keycap-base-interior juga hadir untuk rongga batang. Jangan berasumsi hanya ada dua mesh.

Ini adalah URL yang ditandatangani: ambil tanpa header Authorization. Mereka tetap valid hingga expires_at, yaitu 3 hari setelah finished_at, dan membaca ulang tugas dalam jangka waktu tersebut mengembalikan URL yang identik daripada yang baru ditandatangani. Unduh dan simpan file sendiri sebelum itu — tidak ada cara untuk memperbarui tautan yang kedaluwarsa.

URL yang dapat diunduh untuk gambar proses antara, diindeks berdasarkan jenis. Siklus hidup URL sama seperti model_urls: ditandatangani, tanpa header Authorization, valid hingga expires_at, dan stabil saat tugas dibaca ulang. Jenis yang saat ini dihasilkan:

• head_design — gambar desain kandidat yang dipilih yang dikonsumsi oleh pembuatan (selalu ada).
• composite — render tampilan keycap selesai dari kandidat yang dipilih (ada jika tersedia).
• base_canvas — kanvas dasar keycap yang dicat (ada jika tersedia).

Perlakukan set kunci sebagai terbuka; jenis baru dapat ditambahkan tanpa perubahan yang merusak.