Creative Lab — Keycap API

Ang pinagmulang larawan na gagamitin ng Meshy para gawing mga imahe ng disenyo ng keycap. Sinusuportahan namin sa kasalukuyan ang mga format na .jpg, .jpeg, .png, at .webp.

Ang format ay tinutukoy sa pamamagitan ng pag-decode sa datos ng larawan, hindi mula sa file extension ng URL — isang URL na walang extension, o isa na nagre-redirect, ay gagana hangga't ang mga byte ay nade-decode sa isang suportadong format. Sinusunod ang mga HTTP redirect. Ang EXIF orientation ay pinapantay, kaya ang isang naikot na larawan mula sa telepono ay ginagamit sa paraang tama ang pagkakalapat nito.

Mga limitasyon: hindi bababa sa 32 pixels sa bawat gilid, hindi hihigit sa 178,956,970 pixels sa kabuuan, at hindi hihigit sa 20,000,000 bytes kapag na-download na. Para sa isang data URI, ang limitasyon ay nalalapat sa mga na-decode na byte, kaya maaaring umabot ang mismong source file sa laking iyon — ang base64 text ang mas malaki nang halos isang-katlo, na mahalaga para sa iyong request body, hindi para sa limitasyong ito. Ang isang data URI ay dapat magdeklara ng image/* content type at ;base64.

May dalawang paraan para maglagay ng larawan:

• Publicly accessible URL: Isang URL na naaabot mula sa pampublikong internet.
• Data URI: Isang base64-encoded na data URI ng larawan. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Opsyonal na pangalan ng task para sa layuning display. Pinakamataas na 100 karakter.

Kapag naka-set sa true, ang display render na ibinabalik sa image_urls ay isang transparent RGBA PNG na inalis ang background, kaya maaari mo itong i-composite sa anumang background.

Nalalapat lamang ito sa display render. Ang candidate na ginagamit ng build endpoint ay hindi apektado, kaya magkapareho ang 3D na resulta sa alinmang paraan.

Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:

• Missing parameter: Kinakailangan ang image_url.
• Invalid image format: Ang ibinigay na image_url ay hindi isang suportadong format (.jpg, .jpeg, .png, .webp).
• Image dimensions out of range: Masyadong maliit ang larawan, lumalampas sa pinakamataas na sukat ng file, o lumalampas sa pinakamataas na bilang ng pixel.
• Unreachable URL: Hindi ma-download ang image_url (404 o timeout).
• Invalid Data URI: Malformed ang base64 string.
• Content flagged: Na-flag ang input na larawan ng NSFW moderation.

Nabigo ang authentication. Pakisuri ang iyong API key.

Nasa free plan ang account (kinakailangan ang paid plan para makagawa ng mga task) o kulang ang credits.

Na-flag ang input na larawan ng intellectual property moderation.

Lumampas ka sa iyong rate limit.

Nagkaroon ng hindi inaasahang error sa panig ng server — halimbawa, hindi available ang serbisyo ng content-moderation, nabigo ang pag-stage ng input na larawan, o hindi nagawa ang task. Walang task na nagawa sa kasong ito, kaya ligtas ang pag-retry.

Ang task ID ng isang prototype task na ginawa sa parehong OpenAPI endpoint na ito. Ang prototype ay dapat nagawa ng parehong Meshy account, dapat naabot na ang SUCCEEDED, at dapat nakagawa ng kahit isang candidate.

Ang mga prototype task na ginawa sa pamamagitan ng webapp ay hindi tinatanggap — ang build endpoint ay tumatanggap lamang ng mga prototype task na ginawa ng POST /openapi/creative-lab/keycap/v1/prototype at tinatanggihan ang anumang ibang pinagmulan gamit ang 404.

Ang candidate na bubuuin, kinuha mula sa candidate_ids array ng matagumpay na prototype task. Dapat kabilang ito sa task na iyon; anumang ibang halaga ay tatanggihan gamit ang 400.

Opsyonal na pangalan ng task para sa layuning pagpapakita. Maximum na 100 na character.

Ang keycap base na pagbabatayan ng build. Sa kasalukuyan, ang tanging magagamit na halaga ay cherry-mx-1x1-r1 — isang standard na Cherry MX profile 1u keycap. May balak na 3–5 karagdagang mainstream na standard na sukat; hindi suportado ang mga custom na sukat.

Target na sukat ng inukit na ulo, sa milimetro: ang pinakamahabang dimensyon nito ay isinasukat sa halagang ito. Saklaw: [10, 40]. Ang mga halagang mas mataas sa humigit-kumulang 32.9 ay maaaring bawasan upang umangkop pa rin ang ulo sa hangganan ng protective footprint ng base, kaya maaaring mas maliit ang naihatid na pinakamahabang dimensyon kaysa sa hiniling. Ang inilapat na halaga ay hindi pa nirereflect ngayon sa task object — kung kailangan mong kumpirmahin ang aktwal na natanggap na sukat, sukatin ang bounding box ng keycap-head mesh sa na-download na modelo.

Vertical offset na inilalapat sa ulo bago ito iupo sa base, sa milimetro. Saklaw: [-5, 5].

Hindi katanggap-tanggap ang request. Karaniwang sanhi:

• Kulang na parameter: kinakailangan ang input_task_id at candidate_id.
• Di-wastong UUID: Ang input_task_id ay hindi isang wastong UUID.
• Hindi pa matagumpay ang parent: Ang tinutukoy na prototype task ay hindi pa naabot ang SUCCEEDED.
• Walang candidate: Nagtagumpay ang prototype task ngunit walang nagawang candidate.
• Hindi kilalang candidate: Ang candidate_id ay hindi isa sa mga candidate ng input task.
• Options na labas sa saklaw: Isa sa mga field ng options ay lumabas sa pinapayagang saklaw o enum set nito.

Nabigo ang authentication. Pakisuri ang iyong API key.

Nasa free plan ang account (kinakailangan ng paid plan upang makagawa ng mga task) o kulang ang credits.

Ang tinutukoy na prototype task ay hindi umiiral, pag-aari ng ibang user, o ginawa sa pamamagitan ng webapp (mga prototype task lamang na nasa API mode ang maaaring kumonekta sa build).

Lumampas ka na sa iyong rate limit.

May naganap na hindi inaasahang error sa panig ng server — halimbawa, hindi available ang content-moderation service, nabigo ang pag-stage ng input image, o hindi nagawa ang task. Walang task na nagawa sa kasong ito, kaya ligtas ang muling pagsubok.

Natatanging identifier para sa keycap task na kukunin.

Natatanging identifier para sa keycap task na kakanselahin.

Nasa terminal state na ang task at hindi na ito maaaring kanselahin.

Hindi umiiral ang task, pag-aari ito ng ibang user, o hindi tumutugma ang stage nito sa URL path.

May naganap na hindi inaasahang server-side na error habang kinakansela. Maaaring nakansela na o hindi pa ang task — basahin muli ito upang kumpirmahin bago mag-retry.

Natatanging identifier para sa keycap task na i-stream.

prototype o build. Ang collection ay nagbabalik lamang ng mga task na ang stage ay tumutugma sa URL — ang pagkuha ng /prototype ay hinding-hindi nagbabalik ng mga build task at vice versa.

Numero ng page para sa pagination.

Limitasyon sa laki ng page. Ang pinakamataas na pinapayagan ay 100 items.

Field na gagamiting batayan sa pag-sort. Mga available na value:

• +created_at: Isaayos ayon sa oras ng paglikha nang ascending order.
• -created_at: Isaayos ayon sa oras ng paglikha nang descending order.

Natatanging identifier para sa task. Bagaman gumagamit kami ng k-sortable UUID para sa mga task id bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.

Uri ng task. Ang value ay creative-lab-keycap-prototype.

Ang pangalan ng task na ibinigay noong likhain ang task. Empty string kung walang pangalang ibinigay.

Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.

Timestamp kung kailan nalikha ang task, sa milliseconds.

Timestamp kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.

Timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay magiging 0.

Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.

Ang bilang ng mga naunang task.

Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.

Ang bilang ng credits na nagamit ng task na ito. Ang isang task na umabot sa SUCCEEDED ay sinisingil ng buong halaga para sa kanyang stage. Ang isang task na hindi kailanman nalikha (isang 4xx sa oras ng request, kabilang ang isang moderation rejection) ay hindi sinisingil ng anuman. Ang isang task na umabot sa FAILED ay nagbabalik ng 0 — ang singil ay ire-refund, kabilang ang isang asynchronous moderation block. Ang pagkansela sa pamamagitan ng DELETE ay nagre-refund lamang habang ang task ay PENDING pa; ang isang task na IN_PROGRESS na ay mananatiling sisingilin, dahil nagamit na ang trabaho.

Nada-download na URL ng finished-keycap design render — kung ano ang itsura ng candidate bilang isang tapos na keycap. May iisang entry lamang; ang image_urls[i] ay tumutugma sa candidate_ids[i]. Walang laman hanggang umabot ang task sa SUCCEEDED. Ang URL ay para lamang sa pagpapakita; ang build endpoint ay gumagamit ng candidate_ids, hindi ng mga URL na ito. Kaparehong URL lifecycle ng model_urls: naka-sign, walang Authorization header, balido hanggang expires_at, at matatag kapag binasa ulit ang task.

Mga opaque candidate identifier, kaparalel ng image_urls. Ipasa ang entry na tumutugma sa iyong napiling disenyo bilang candidate_id ng build request. Huwag gumawa ng anumang palagay tungkol sa format ng mga id na ito.

Natatanging identifier para sa task.

Uri ng task. Ang value ay creative-lab-keycap-build.

Ang pangalan ng task na ibinigay noong ginawa ang task. Blangkong string kung walang ibinigay na pangalan.

Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Ang progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.

Timestamp ng paglikha ng task, sa milliseconds.

Timestamp ng pagsisimula ng task, sa milliseconds.

Timestamp ng pagkatapos ng task, sa milliseconds.

Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.

Ang bilang ng mga naunang task. May kahulugan lamang kapag ang status ay PENDING.

Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.

Ang bilang ng credits na nagamit ng task na ito. Ang task na umabot sa SUCCEEDED ay sisingilin ng buong halaga para sa kanyang stage. Ang task na hindi kailanman nagawa (isang 4xx sa oras ng request, kabilang ang pagtanggi ng moderation) ay hindi sinisingil. Ang task na umabot sa FAILED ay nagbabalik ng 0 — ang singil ay ire-refund, kabilang ang asynchronous na moderation block. Ang pagkansela sa pamamagitan ng DELETE ay nagre-refund lamang habang ang task ay PENDING pa; ang task na IN_PROGRESS na ay mananatiling sisingilin, dahil nagamit na ang trabaho.

Mga URL na maaaring i-download para sa mga nabuong model artifact. Parehong ang GLB at ang OBJ bundle ay na-export sa real-world millimeter scale, Y-up, na ang harapan ng keycap ay nakaharap sa +Z. Ang mga mesh ay pinangalanang keycap-head at keycap-base; kapag ang base ay bumalik sa isang pattern fill, isang ikatlong mesh na keycap-base-interior ay naroroon din para sa stem cavity. Huwag ipagpalagay na eksaktong dalawang mesh lamang mayroon.

Ito ay mga signed URL: kunin ang mga ito nang walang header na Authorization. Mananatili silang valid hanggang sa expires_at, na 3 araw pagkatapos ng finished_at, at ang muling pagbasa sa task sa loob ng window na iyon ay nagbabalik ng eksaktong parehong URL sa halip na isang bagong signed na URL. I-download at i-store mo mismo ang mga file bago iyon — walang paraan upang i-refresh ang isang expired na link.

Mga URL na maaaring i-download para sa mga intermediate na process image, naka-key ayon sa uri. Kaparehong URL lifecycle ng model_urls: signed, walang header na Authorization, valid hanggang expires_at, at stable kapag muling binasa ang task. Kasalukuyang inilalabas na mga uri:

• head_design — ang design image ng piniling candidate na ginamit ng build (laging naroroon).
• composite — ang finished-keycap display render ng piniling candidate (naroroon kapag available).
• base_canvas — ang pininturahang keycap-base canvas (naroroon kapag available).

Ituring na open-ended ang key set na ito; maaaring magdagdag ng mga bagong uri nang walang breaking change.