Creative Lab — Keycap API

Foto sumber untuk Meshy menukarkannya menjadi imej reka bentuk keycap. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.

Format dikesan dengan mengekod semula (decode) data imej, bukan daripada sambungan fail URL — URL tanpa sambungan, atau yang mengubah hala (redirect), tetap berfungsi selagi bait-bait tersebut boleh dikod semula kepada format yang disokong. Pengubahan hala HTTP akan diikuti. Orientasi EXIF dinormalisasi, jadi foto telefon yang berputar akan digunakan mengikut cara ia kelihatan.

Had: sekurang-kurangnya 32 piksel pada setiap sisi, paling banyak 178,956,970 piksel secara keseluruhan, dan paling banyak 20,000,000 bait selepas dimuat turun. Untuk Data URI, had ini terpakai kepada bait yang telah dinyahkod (decoded), jadi fail sumber itu sendiri boleh mencapai saiz tersebut — teks base64 yang kira-kira satu pertiga lebih besar itulah yang penting untuk badan permintaan (request body) anda, bukan untuk had ini. Data URI mesti mengisytiharkan jenis kandungan image/* dan ;base64.

Terdapat dua cara untuk menyediakan imej:

• URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam.
• Data URI: Data URI imej yang dikod dalam base64. Contoh Data URI: data:image/jpeg;base64,<data imej anda yang dikod base64>.

Nama tugasan pilihan untuk tujuan paparan. Maksimum 100 aksara.

Apabila ditetapkan kepada true, render paparan yang dikembalikan dalam image_urls adalah PNG RGBA lutsinar dengan latar belakang dibuang, jadi anda boleh menggabungkannya (composite) ke atas mana-mana latar belakang.

Ini hanya terpakai kepada render paparan sahaja. Calon yang digunakan oleh endpoint build tidak terjejas, jadi hasil 3D adalah sama sahaja.

Permintaan tidak boleh diterima. Punca biasa:

• Parameter hilang: image_url diperlukan.
• Format imej tidak sah: image_url yang diberikan bukan format yang disokong (.jpg, .jpeg, .png, .webp).
• Dimensi imej di luar julat: Imej terlalu kecil, melebihi saiz fail maksimum, atau melebihi bilangan piksel maksimum.
• URL tidak boleh dicapai: image_url tidak dapat dimuat turun (404 atau timeout).
• Data URI tidak sah: Rentetan base64 tidak sah bentuknya.
• Kandungan ditandai: Imej input ditandai oleh moderation NSFW.

Pengesahan gagal. Sila semak kunci API anda.

Akaun berada pada pelan percuma (pelan berbayar diperlukan untuk mencipta tugasan) atau mempunyai kredit yang tidak mencukupi.

Imej input ditandai oleh moderation harta intelek.

Anda telah melebihi had kadar anda.

Ralat sisi pelayan yang tidak dijangka berlaku — sebagai contoh perkhidmatan moderation kandungan tidak tersedia, penyediaan imej input gagal, atau tugasan tidak dapat dicipta. Tiada tugasan dicipta dalam kes ini, jadi mencuba semula adalah selamat.

ID tugas bagi tugas prototaip yang dicipta melalui endpoint OpenAPI yang sama. Prototaip mestilah dicipta oleh akaun Meshy yang sama, mesti telah mencapai SUCCEEDED, dan mesti telah menghasilkan sekurang-kurangnya satu calon.

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

Calon yang hendak dibina, diambil daripada tatasusunan candidate_ids bagi tugas prototaip yang berjaya. Mesti tergolong dalam tugas tersebut; sebarang nilai lain akan ditolak dengan 400.

Nama tugas pilihan untuk tujuan paparan. Maksimum 100 aksara.

Asas keycap untuk dibina. Pada masa ini satu-satunya nilai yang tersedia adalah cherry-mx-1x1-r1 — keycap profil Cherry MX 1u standard. 3–5 saiz standard arus perdana tambahan dirancang; saiz tersuai tidak disokong.

Saiz sasaran bagi kepala terukir, dalam milimeter: dimensi terpanjangnya diskalakan kepada nilai ini. Julat: [10, 40]. Nilai melebihi kira-kira 32.9 mungkin dikurangkan supaya kepala masih sesuai dengan had jejak lindungan asas, sehingga dimensi terpanjang yang dihasilkan boleh lebih kecil daripada yang diminta. Nilai yang digunakan tidak digambarkan semula pada objek tugas pada masa ini — jika anda perlu mengesahkan saiz yang anda terima sebenarnya, ukur kotak pembatas jejaring keycap-head dalam model yang dimuat turun.

Ofset menegak yang dikenakan pada kepala sebelum ia diletakkan pada asas, dalam milimeter. Julat: [-5, 5].

Permintaan tidak dapat diterima. Sebab-sebab biasa:

• Parameter hilang: input_task_id dan candidate_id diperlukan.
• UUID tidak sah: input_task_id bukan UUID yang sah.
• Induk belum berjaya: Tugas prototaip yang dirujuk belum mencapai SUCCEEDED.
• Tiada calon: Tugas prototaip berjaya tetapi tidak menghasilkan sebarang calon.
• Calon tidak dikenali: candidate_id bukan salah satu calon bagi tugas input.
• Options di luar julat: Salah satu medan options berada di luar julat atau set enum yang dibenarkan.

Pengesahan gagal. Sila semak kunci API anda.

Akaun berada pada pelan percuma (pelan berbayar diperlukan untuk mencipta tugas) atau mempunyai kredit yang tidak mencukupi.

Tugas prototaip yang dirujuk tidak wujud, tergolong kepada pengguna lain, atau dicipta melalui webapp (hanya tugas prototaip mod API boleh berlanjut kepada pembinaan).

Anda telah melebihi had kadar anda.

Ralat tidak dijangka pada bahagian pelayan telah berlaku — contohnya perkhidmatan moderation kandungan tidak tersedia, penyediaan (staging) imej input gagal, atau tugas tidak dapat dicipta. Tiada tugas dicipta dalam kes ini, jadi mencuba semula adalah selamat.

Pengecam unik untuk tugas keycap yang hendak diambil.

Pengenal unik untuk tugas keycap yang akan dibatalkan.

Tugas sudah berada dalam keadaan terminal dan tidak boleh dibatalkan.

Tugas tidak wujud, dimiliki oleh pengguna lain, atau peringkatnya tidak sepadan dengan laluan URL.

Ralat pelayan yang tidak dijangka berlaku semasa pembatalan. Tugas mungkin telah atau belum dibatalkan — baca semula untuk mengesahkannya sebelum mencuba semula.

Pengenal unik untuk tugas keycap yang akan di-stream.

Sama ada prototype atau build. Koleksi ini hanya mengembalikan tugasan yang peringkatnya sepadan dengan URL — mengambil /prototype tidak akan pernah mengembalikan tugasan pembinaan dan sebaliknya.

Nombor halaman untuk penomboran halaman.

Had saiz halaman. Maksimum yang dibenarkan adalah 100 item.

Medan untuk isih mengikut. Nilai yang tersedia:

• +created_at: Isih mengikut masa penciptaan secara menaik.
• -created_at: Isih mengikut masa penciptaan secara menurun.

Pengecam unik untuk tugas. Walaupun kami menggunakan UUID yang boleh disusun-k untuk id tugas sebagai butiran pelaksanaan, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.

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

Nama tugas yang diberikan semasa tugas dicipta. Rentetan kosong jika tiada nama diberikan.

Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress tugas. Jika tugas belum bermula lagi, ciri ini akan menjadi 0. Sebaik sahaja tugas berjaya, nilai ini akan menjadi 100.

Cap masa bila tugas dicipta, dalam milisaat.

Cap masa bila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, ciri ini akan menjadi 0.

Cap masa bila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, ciri ini akan menjadi 0.

Cap masa bila hasil tugas tamat tempoh, dalam milisaat.

Bilangan tugas terdahulu.

Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

Bilangan kredit yang digunakan oleh tugas ini. Tugas yang mencapai SUCCEEDED akan dikenakan caj penuh untuk peringkatnya. Tugas yang tidak pernah dicipta (4xx pada masa permintaan, termasuk penolakan moderation) tidak dikenakan sebarang caj. Tugas yang mencapai FAILED memulangkan 0 — caj tersebut dikembalikan, termasuk sekatan moderation secara tidak segerak. Membatalkan melalui DELETE hanya mengembalikan caj semasa tugas masih PENDING; tugas yang sudah IN_PROGRESS kekal dikenakan caj, kerana kerja tersebut telah dibelanjakan.

URL yang boleh dimuat turun bagi paparan reka bentuk keycap siap — rupa calon tersebut sebagai keycap yang sudah siap. Menyimpan satu entri sahaja; image_urls[i] sepadan dengan candidate_ids[i]. Kosong sehingga tugas mencapai SUCCEEDED. URL ini hanya untuk paparan sahaja; endpoint pembinaan menggunakan candidate_ids, bukan URL ini. Kitaran hayat URL yang sama seperti model_urls: ditandatangan, tiada header Authorization, sah sehingga expires_at, dan stabil apabila tugas dibaca semula.

Pengecam calon buram, selari dengan image_urls. Berikan entri yang sepadan dengan reka bentuk pilihan anda sebagai candidate_id bagi permintaan pembinaan. Jangan membuat sebarang andaian tentang format id ini.

Pengecam unik untuk tugas.

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

Nama tugas yang diberikan semasa tugas dicipta. Rentetan kosong jika tiada nama diberikan.

Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress tugas. Jika tugas belum bermula, ciri ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.

Cap masa apabila tugas dicipta, dalam milisaat.

Cap masa apabila tugas dimulakan, dalam milisaat.

Cap masa apabila tugas selesai, dalam milisaat.

Cap masa apabila hasil tugas luput, dalam milisaat.

Bilangan tugas terdahulu. Hanya bermakna apabila status ialah PENDING.

Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

Bilangan kredit yang digunakan oleh tugas ini. Tugas yang mencapai SUCCEEDED akan dikenakan jumlah penuh bagi peringkatnya. Tugas yang tidak pernah dicipta (4xx pada masa permintaan, termasuk penolakan moderation) tidak dikenakan sebarang caj. Tugas yang mencapai FAILED mengembalikan 0 — caj tersebut dikembalikan (refund), termasuk sekatan moderation yang tak segerak. Membatalkan melalui DELETE hanya mengembalikan caj semasa tugas masih PENDING; tugas yang sudah IN_PROGRESS kekal dikenakan caj, kerana kerja tersebut telah dibelanjakan.

URL yang boleh dimuat turun untuk artifak model yang dijana. Kedua-dua GLB dan bundel OBJ dieksport pada skala milimeter dunia sebenar, Y-up, dengan bahagian hadapan keycap menghadap +Z. Jejaring dinamakan keycap-head dan keycap-base; apabila dasar kembali kepada isian corak, jejaring ketiga keycap-base-interior turut hadir untuk rongga stem. Jangan andaikan tepat dua jejaring.

Ini adalah URL bertandatangan (signed URLs): dapatkannya tanpa header Authorization. Ia kekal sah sehingga expires_at, iaitu 3 hari selepas finished_at, dan membaca semula tugas dalam tempoh tersebut akan mengembalikan URL yang sama, bukannya yang baru ditandatangan. Muat turun dan simpan fail tersebut sendiri sebelum itu — tiada cara untuk menyegarkan semula pautan yang telah luput.

URL yang boleh dimuat turun untuk imej proses perantaraan, diindeks mengikut jenis. Kitaran hayat URL sama seperti model_urls: bertandatangan, tanpa header Authorization, sah sehingga expires_at, dan stabil apabila tugas dibaca semula. Jenis yang dihasilkan pada masa ini:

• head_design — imej reka bentuk kandidat yang dipilih yang digunakan oleh binaan (sentiasa hadir).
• composite — render paparan keycap siap bagi kandidat yang dipilih (hadir apabila tersedia).
• base_canvas — kanvas dasar keycap yang telah dicat (hadir apabila tersedia).

Anggap set kunci ini sebagai terbuka; jenis baharu mungkin ditambah tanpa menyebabkan perubahan yang memecahkan (breaking change).