Creative Lab — Keycap API

Gawing full-color custom mechanical keyboard keycap ang isang source na larawan sa dalawang yugto: prototype na bumubuo ng "finished keycap" na disenyo mula sa iyong input na larawan. Kapag nakumpirma mo na ang render na iyon, ang build ay gagawin itong textured na 3D keycap model sa isang takbo — ang pagbuo ng white-model, awtomatikong pag-upo at pagputol sa isang naka-calibrate na default na posisyon, pag-kulay ng buong modelo, at pinal na pag-aassemble ay lahat nagaganap sa loob ng isang build na gawain. Ang dalawang yugto ay konektado sa pamamagitan ng input_task_id kasama ang candidate_id.

  • POST /openapi/creative-lab/keycap/v1/prototype
  • POST /openapi/creative-lab/keycap/v1/build

Parehong POST endpoints ay nangangailangan ng bayad na subscription plan. Ang mga kahilingan mula sa mga libreng-plan na account ay tinatanggihan na may 402 Payment Required.

POST/openapi/creative-lab/keycap/v1/prototype

Lumikha ng Keycap Prototype Task

Bumuo ng isang tapos na disenyo ng keycap mula sa source photo. Ang resulta ng task ay naglalaman ng image_urls array (ang display render ng tapos na keycap) at isang parallel na candidate_ids array; parehong may isang entry. Tawagin muli ang endpoint na ito para sa isa pang render kung ang resulta ay hindi ang nais mo — bawat tawag ay sinisingil nang hiwalay. Ibigay ang candidate_id kasama ang prototype task ID sa build endpoint. Sumangguni sa The Keycap Prototype Task Object para sa hugis ng tugon.

Mga Parameter

  • Name
    image_url
    Type
    string
    Kinakailangan
    Description

    Source photo para gawing keycap design images ng Meshy. Kasalukuyan naming sinusuportahan ang .jpg, .jpeg, .png, at .webp na mga format.

    Ang format ay natutukoy sa pamamagitan ng pag-decode ng image data, hindi mula sa file extension ng URL — ang URL na walang extension, o isa na nagre-redirect, ay gumagana basta't ang mga byte ay nade-decode sa isang suportadong format. Ang mga HTTP redirect ay sinusundan. Ang EXIF orientation ay na-normalize, kaya ang isang rotated na phone photo ay ginagamit sa paraang ito ay nakikita.

    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. Para sa isang data URI, ang limitasyon ay nalalapat sa decoded bytes, kaya ang source file mismo ay maaaring umabot sa laki na iyon — ito ay ang base64 text na humigit-kumulang isang ikatlong mas malaki, 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 upang ibigay ang imahe:

    • Publicly accessible URL: Isang URL na naa-access mula sa pampublikong internet.
    • Data URI: Isang base64-encoded data URI ng imahe. Halimbawa ng isang data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    name
    Type
    string
    Description

    Opsyonal na pangalan ng task para sa layunin ng pagpapakita. Maximum na 100 na karakter.

  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang display render na ibinalik sa image_urls ay isang transparent RGBA PNG na may tinanggal na background, kaya maaari mo itong i-composite sa anumang background.

    Ito ay nalalapat lamang sa display render. Ang candidate na kinokonsumo ng build endpoint ay hindi apektado, kaya ang 3D na resulta ay magkapareho alinman sa paraan.

Mga Ibinabalik

Ang result na property ng tugon ay naglalaman ng task id ng bagong nilikhang keycap prototype task. I-poll ang Get a Task endpoint o mag-subscribe sa stream hanggang ang task ay umabot sa SUCCEEDED, pagkatapos ay kunin ang entry mula sa candidate_ids at ipasa ito, kasama ang task ID, sa build endpoint.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Ang kahilingan ay hindi katanggap-tanggap. Karaniwang mga sanhi:

    • Nawawalang parameter: Kinakailangan ang image_url.
    • Hindi wastong format ng imahe: Ang ibinigay na image_url ay hindi isang suportadong format (.jpg, .jpeg, .png, .webp).
    • Mga sukat ng imahe na wala sa saklaw: Ang imahe ay masyadong maliit, lumampas sa maximum na laki ng file, o lumampas sa maximum na bilang ng pixel.
    • Hindi maabot na URL: Ang image_url ay hindi ma-download (404 o timeout).
    • Hindi wastong Data URI: Ang base64 string ay mali ang pagkakabuo.
    • Nilalaman na na-flag: Ang input na imahe ay na-flag ng NSFW moderation.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Ang account ay nasa libreng plano (kinakailangan ang bayad na plano upang lumikha ng mga task) o kulang sa credits.

  • Name
    403 - Forbidden
    Description

    Ang input na imahe ay na-flag ng intellectual property moderation.

  • Name
    429 - Too Many Requests
    Description

    Lumampas ka sa iyong rate limit.

  • Name
    500 - Internal Server Error
    Description

    Isang hindi inaasahang error sa server-side ang naganap — halimbawa, ang content-moderation service ay hindi magagamit, nabigo ang pag-stage ng input na imahe, o hindi maaring malikha ang task. Walang task na nalikha sa kasong ito, kaya ang pag-uulit ay ligtas.

Request

POST
/openapi/creative-lab/keycap/v1/prototype
# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}
POST/openapi/creative-lab/keycap/v1/build

Gumawa ng Keycap Build Task

Bumuo ng huling 3D keycap model na may texture mula sa isang nagtagumpay na prototype task at isa sa mga kandidato nito. Isang build task ang nagpapatakbo ng buong pipeline mula simula hanggang wakas — pagbuo ng white-model mula sa napiling disenyo, awtomatikong pag-upo at pagputol sa base ng keycap gamit ang isang nakakalibrate na default pose (hindi kailangan ng interactive adjustment), buong pag-kulay ng modelo, at huling pag-assemble at pag-export. Karaniwang tumatagal ang isang build ng 3–7 minuto, patungo sa mas mataas na dulo kapag maraming build ang sabay-sabay na tumatakbo. Sumangguni sa The Keycap Build Task Object para sa hugis ng tugon.

Mga Parameter

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang task ID ng isang prototype task na ginawa sa pamamagitan ng parehong OpenAPI endpoint na ito. Ang prototype ay dapat na ginawa ng parehong Meshy account, dapat ay umabot sa SUCCEEDED, at dapat ay nakagawa ng hindi bababa sa isang kandidato.

    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.

  • Name
    candidate_id
    Type
    string
    Kinakailangan
    Description

    Ang kandidatong itatayo, kinuha mula sa candidate_ids array ng nagtagumpay na prototype task. Dapat ay kabilang sa task na iyon; anumang ibang halaga ay tinatanggihan gamit ang 400.

  • Name
    name
    Type
    string
    Description

    Opsyonal na pangalan ng task para sa layunin ng pagpapakita. Maximum na 100 karakter.

options

Opsyonal na pag-tune ng heometriya. Ang bawat field ay may nakakalibrate na default — ipadala lamang ang mga nais mong baguhin.

  • Name
    base_model
    Type
    string
    default cherry-mx-1x1-r1
    Description

    Ang base ng keycap na itatayo. Sa kasalukuyan, ang tanging magagamit na halaga ay cherry-mx-1x1-r1 — isang standard na Cherry MX profile 1u keycap. 3–5 karagdagang mainstream standard sizes ang pinaplano; hindi sinusuportahan ang mga custom sizes.

  • Name
    head_size_mm
    Type
    number
    default 23
    Description

    Target na laki ng inukit na ulo, sa milimetro: ang pinakamahabang sukat nito ay iskalado sa halagang ito. Saklaw: [10, 40]. Ang mga halagang lampas sa humigit-kumulang 32.9 ay maaaring bawasan upang ang ulo ay magkasya pa rin sa limitasyon ng proteksiyon na footprint ng base, kaya ang ibinigay na pinakamahabang sukat ay maaaring mas maliit kaysa sa hiniling. Ang inilapat na halaga ay hindi ibinabalik sa task object ngayon — kung kailangan mong kumpirmahin ang laki na aktwal mong natanggap, sukatin ang bounding box ng keycap-head mesh sa na-download na modelo.

  • Name
    vertical_offset_mm
    Type
    number
    default 0
    Description

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

Mga Ibinabalik

Ang result na property ng tugon ay naglalaman ng task id ng bagong likhang keycap build task. I-poll ang Get a Task endpoint o mag-subscribe sa stream hanggang ang task ay umabot sa SUCCEEDED, pagkatapos ay i-download ang mga artifact mula sa model_urls.glb at model_urls.obj_zip.

Ang parehong GLB at OBJ bundle ay na-export sa real-world millimeter scale, na may Y-up na coordinate system at ang harap ng keycap ay nakaharap sa +Z.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Ang kahilingan ay hindi katanggap-tanggap. Karaniwang mga sanhi:

    • Nawawalang parameter: input_task_id at candidate_id ay kinakailangan.
    • Invalid UUID: Ang input_task_id ay hindi isang wastong UUID.
    • Parent not succeeded: Ang tinutukoy na prototype task ay hindi pa umabot sa SUCCEEDED.
    • No candidates: Ang prototype task ay nagtagumpay ngunit walang nagawang mga kandidato.
    • Unknown candidate: candidate_id ay hindi isa sa mga kandidato ng input task.
    • Options out of range: Isa sa mga field ng options ay lumampas sa pinapayagang saklaw o enum set.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Ang account ay nasa libreng plano (kailangan ng bayad na plano upang makagawa ng mga task) o kulang sa credits.

  • Name
    404 - Not Found
    Description

    Ang tinutukoy na prototype task ay hindi umiiral, kabilang sa ibang user, o ginawa sa pamamagitan ng webapp (tanging API-mode prototype tasks ang nagcha-chain sa build).

  • Name
    429 - Too Many Requests
    Description

    Naabot mo na ang iyong rate limit.

  • Name
    500 - Internal Server Error
    Description

    Isang hindi inaasahang error sa server-side ang naganap — halimbawa, ang content-moderation service ay hindi magagamit, nabigo ang pag-stage ng input image, o hindi nagawa ang task. Walang task na nagawa sa kasong ito, kaya ligtas na subukang muli.

Request

POST
/openapi/creative-lab/keycap/v1/build
# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}
GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Kunin ang isang Keycap Task

Kunin ang isang prototype o build task gamit ang isang valid na task id. Ang URL path ay dapat tumugma sa yugto ng task — ang isang build task na kinuha sa pamamagitan ng /prototype/:id ay magbabalik ng 404, at kabaligtaran.

Sumangguni sa The Keycap Prototype Task Object at The Keycap Build Task Object para sa mga hugis ng tugon.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging pagkakakilanlan para sa keycap task na kukunin.

Mga Ibinabalik

Ang tugon ay naglalaman ng keycap task object. Ang hugis ay nakadepende kung aling yugto ang hiniling.

Request

GET
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}
DELETE/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Burahin ang isang Keycap Task

Kanselahin ang isang keycap task. Kung ang task ay nasa PENDING pa, ang credits na nagamit sa paglikha ay ibabalik. Ang mga task na nasa IN_PROGRESS na ay kinansela nang walang refund (maaaring ginagamit na ng worker ang resources). Ang mga task na nakarating na sa terminal state (SUCCEEDED, FAILED, CANCELED) ay hindi na maaaring kanselahin.

Ang URL path ay dapat tumugma sa yugto ng task — ang DELETE sa /prototype/:buildId ay magbabalik ng 404.

Mga Parameter ng Path

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa keycap task na kakanselahin.

Mga Ibinabalik

Nagbabalik ng 204 No Content sa tagumpay na may walang laman na katawan.

Mga Paraan ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Ang task ay nasa terminal state na at hindi na maaaring kanselahin.

  • Name
    404 - Not Found
    Description

    Ang task ay hindi umiiral, pagmamay-ari ng ibang user, o ang yugto nito ay hindi tumutugma sa URL path.

  • Name
    500 - Internal Server Error
    Description

    Isang hindi inaasahang error sa server-side ang naganap habang kinansela. Ang task ay maaaring nakansela o hindi — basahin muli ito upang makumpirma bago subukang muli.

Request

DELETE
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id/stream

I-stream ang isang Keycap Task

I-stream ang mga real-time na update para sa isang keycap task sa pamamagitan ng Server-Sent Events (SSE). Ang URL path ay dapat tumugma sa yugto ng task — ang pagbubukas ng stream sa /prototype/:buildId/stream ay maglalabas ng isang event: error payload na may status_code: 404 at isasara ang stream.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa keycap task na i-stream.

Mga Ibinabalik

Nagbabalik ng stream ng mga Keycap Prototype o Keycap Build task objects bilang Server-Sent Events. Para sa mga PENDING o IN_PROGRESS na tasks, ang response stream ay maglalaman lamang ng kinakailangang progress at status na mga field.

Request

GET
/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***"
  }
}
GET/openapi/creative-lab/keycap/v1/(prototype|build)

Listahan ng Mga Gawain sa Keycap

Kunin ang isang listahan ng iyong mga gawain sa keycap para sa isang yugto na may pagination. Ang URL path ay pumipili ng yugto — /prototype ay nagbabalik ng mga gawain sa prototype; /build ay nagbabalik ng mga gawain sa build. Ang mga gawain mula sa ibang yugto ay hindi kasama sa alinmang tugon.

Mga Parameter ng Path

  • Name
    stage
    Type
    path
    Kinakailangan
    Description

    Alinman sa prototype o build. Ang koleksyon ay nagbabalik lamang ng mga gawain na ang yugto ay tumutugma sa URL — ang pagkuha ng /prototype ay hindi kailanman nagbabalik ng mga gawain sa build at kabaligtaran.

Mga Parameter ng Query

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Numero ng pahina para sa pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Limitasyon ng laki ng pahina. Ang maximum na pinapayagan ay 100 na item.

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    Patlang na gagamitin para sa pag-uuri. Mga magagamit na halaga:

    • +created_at: Uriin ayon sa oras ng paglikha sa pataas na pagkakasunod.
    • -created_at: Uriin ayon sa oras ng paglikha sa pababang pagkakasunod.

Mga Ibinabalik

Nagbabalik ng isang listahan ng mga bagay ng gawain sa bawat yugto na may pagination — alinman ang bagay ng gawain sa keycap prototype kapag naglilista ng /prototype o ang bagay ng gawain sa keycap build kapag naglilista ng /build.

Request

GET
/openapi/creative-lab/keycap/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (Listahan ng Mga Gawain sa Prototype)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

Ang Keycap Prototype Task Object

Ang Keycap Prototype Task object ay isang yunit ng trabaho na sinusubaybayan ng Meshy upang makabuo ng isang natapos na disenyo ng keycap na imahe mula sa isang source photo. Ang output ng yugtong ito ay nakakadena sa ang build stage sa pamamagitan ng input_task_id at candidate_id.

Mga Katangian

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

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

  • Name
    name
    Type
    string
    Description

    Ang pangalan ng task na ibinigay noong nilikha ang task. Walang laman na string kung walang pangalan na ibinigay.

  • Name
    status
    Type
    string
    Description

    Katayuan ng task. Ang mga posibleng halaga ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp kung kailan nilikha ang task, sa milliseconds.

    Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, alinsunod sa RFC 3339 na pamantayan. Halimbawa, Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng mga timestamp sa Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang bilang ng mga naunang task.

    Ang halaga ng field na ito ay makabuluhan lamang kung ang katayuan ng task ay PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng mga credits na nagamit ng task na ito. Ang isang task na umabot sa SUCCEEDED ay sinisingil ng buong halaga para sa yugto nito. Ang isang task na hindi kailanman nalikha (isang 4xx sa oras ng kahilingan, kabilang ang isang moderation rejection) ay hindi sinisingil. Ang isang task na umabot sa FAILED ay nagbabalik ng 0 — ang singil ay ibinabalik, kabilang ang isang asynchronous moderation block. Ang pagkansela sa pamamagitan ng DELETE ay nagbabalik lamang habang ang task ay PENDING; ang isang task na IN_PROGRESS na ay nananatiling sinisingil, dahil ang trabaho ay nagastos na.

  • Name
    image_urls
    Type
    array of strings
    Description

    Downloadable URL ng natapos na disenyo ng keycap render — kung ano ang hitsura ng kandidato bilang isang natapos na keycap. May hawak na isang entry; image_urls[i] ay tumutugma sa candidate_ids[i]. Walang laman hanggang ang task ay umabot sa SUCCEEDED. Ang URL ay para sa display lamang; ang build endpoint ay kumokonsumo ng candidate_ids, hindi ang mga URL na ito. Parehong lifecycle ng URL tulad ng model_urls: signed, walang Authorization header, balido hanggang expires_at, at matatag kapag ang task ay muling binasa.

  • Name
    candidate_ids
    Type
    array of strings
    Description

    Opaque candidate identifiers, parallel sa image_urls. Ipasok ang entry na tumutugma sa iyong napiling disenyo bilang candidate_id ng build request. Huwag gumawa ng anumang mga palagay tungkol sa format ng mga id na ito.

Example Keycap Prototype Task Object

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Ang Objek ng Keycap Build Task

Ang Keycap Build Task object ay isang yunit ng trabaho na sinusubaybayan ng Meshy upang makabuo ng panghuling textured 3D keycap mula sa isang nagtagumpay na prototype task at isang napiling kandidato. Ang isang solong build ay nagpapatakbo ng buong pipeline — pagbuo ng white-model, awtomatikong pag-upo at pagputol, pagkulay, pag-assemble, at pag-export.

Mga Katangian

  • Name
    id
    Type
    string
    Description

    Natatanging pagkakakilanlan para sa task.

  • Name
    type
    Type
    string
    Description

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

  • Name
    name
    Type
    string
    Description

    Ang pangalan ng task na ibinigay noong nilikha ang task. Walang laman na string kung walang ibinigay na pangalan.

  • Name
    status
    Type
    string
    Description

    Katayuan ng task. Ang mga posibleng halaga ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Pag-unlad ng task. Kung ang task ay hindi pa nasisimulan, ang katangiang ito ay magiging 0. Kapag ang task ay nagtagumpay na, ito ay magiging 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp kung kailan nilikha ang task, sa milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp kung kailan sinimulan ang task, sa milliseconds.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp kung kailan natapos ang task, sa milliseconds.

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

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

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng credits na nagamit ng task na ito. Ang isang task na umabot sa SUCCEEDED ay sinisingil ng buong halaga para sa yugto nito. Ang isang task na hindi kailanman nalikha (isang 4xx sa oras ng kahilingan, kabilang ang pagtanggi sa moderation) ay hindi sinisingil. Ang isang task na umabot sa FAILED ay nagbabalik ng 0 — ang singil ay ibinabalik, kabilang ang isang asynchronous na block ng moderation. Ang pagkansela sa pamamagitan ng DELETE ay nagre-refund lamang habang ang task ay nasa PENDING; ang isang task na nasa IN_PROGRESS ay nananatiling sinisingil, dahil ang trabaho ay nagastos na.

  • Name
    model_urls
    Type
    object
    Description

    Mga maida-download na URL para sa mga nalikhang model artifacts. Ang parehong GLB at OBJ bundle ay na-export sa real-world millimeter scale, Y-up, na nakaharap ang harap ng keycap 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.

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

    • Name
      glb
      Type
      string
      Description

      Maida-download na URL sa panghuling textured model.glb.

    • Name
      obj_zip
      Type
      string
      Description

      Maida-download na URL sa isang zip bundle na naglalaman ng model.obj, model.mtl, at ang texture PNGs na talagang tinutukoy ng MTL nito. Ang isang solid-color base ay naglalaman lamang ng keycap-head.png; ang isang patterned base ay naglalaman din ng keycap-base.png.

  • Name
    process_image_urls
    Type
    object
    Description

    Mga maida-download na URL para sa mga intermediate process images, na naka-key sa pamamagitan ng uri. Parehong lifecycle ng URL gaya ng model_urls: signed, walang Authorization header, balido hanggang expires_at, at matatag kapag muling binasa ang task. Kasalukuyang mga uri na inilalabas:

    • head_design — ang disenyo ng imahe ng napiling kandidato na kinonsumo ng build (palaging naroroon).
    • composite — ang finished-keycap display render ng napiling kandidato (naroroon kapag magagamit).
    • base_canvas — ang pininturahang keycap-base canvas (naroroon kapag magagamit).

    Ituring ang key set bilang open-ended; maaaring idagdag ang mga bagong uri nang walang breaking change.

Example Keycap Build Task Object

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

End-to-End Example

Ang kumpletong daloy: lumikha ng prototype mula sa isang larawan, i-poll ito hanggang SUCCEEDED, pumili ng kandidato mula sa candidate_ids, lumikha ng build gamit ang kandidatong iyon, i-poll ang build hanggang SUCCEEDED, pagkatapos ay i-download ang GLB at ang OBJ bundle mula sa model_urls.

Ang halimbawa ay pumipili ng unang kandidato sa pamamagitan ng programa. Sa isang tunay na integrasyon, ipapakita mo ang image_urls na entry sa end user at hayaan silang pumili; ang napiling index ay tumutugma 1:1 sa candidate_ids.

Kumpletong daloy

POST
/openapi/creative-lab/keycap/v1
#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi

BASE="https://api.meshy.ai/openapi/creative-lab/keycap/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"image_url":"data:%s;base64,' "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  printf '{"image_url":"%s"}' "$IMAGE_URL" >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the design render
poll prototype "$PROTO_ID"

# 3. Pick a candidate (first one here; show image_urls to a user in production)
CANDIDATE_ID=$(api GET "$BASE/prototype/$PROTO_ID" | jq -r '.candidate_ids[0]')

# 4. Create the build task
jq -n --arg p "$PROTO_ID" --arg c "$CANDIDATE_ID" \
  '{input_task_id: $p, candidate_id: $c}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 5. Wait for the model (a build usually takes 3-7 minutes)
poll build "$BUILD_ID"

# 6. Download the artifacts. These are signed URLs: no Authorization header,
#    and they stay valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o keycap.glb "$(jq -r '.model_urls.glb' <<<"$TASK")"
curl --silent --show-error --fail --max-time 900 \
  -o keycap-obj.zip "$(jq -r '.model_urls.obj_zip' <<<"$TASK")"
echo "Done: keycap.glb + keycap-obj.zip"