Ireretiro ang lowpoly sa Oct 30, 2026. Lumipat ng modelo bago ang mga petsang ito para maiwasan ang mga error sa request. Tingnan ang lahat ng deprecation

Creative Lab Keycap API

I-convert ang isang larawan sa isang full-color na custom na keycap para sa isang mechanical keyboard sa dalawang yugto. Ang isang prototype task ay bumubuo ng larawan ng tapos na keycap mula sa larawan. Ang isang build task ay ginagawang textured na 3D keycap model ang larawang iyon. Kinukuha nito ang ID ng prototype task bilang input_task_id at ang candidate ID ng larawan bilang candidate_id.

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

Parehong nangangailangan ng paid plan ang dalawang POST endpoint na ito. Ang isang request mula sa isang free-plan account ay nagbabalik ng 402.

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

Gumawa ng Keycap prototype task

Gumagawa ng isang imahe ng tapos na keycap mula sa isang larawan. Ang image_urls ng task ay naglalaman ng imahe, at ang candidate_ids ay naglalaman ng ID nito, may isang entry sa bawat isa. Kung hindi mo gusto ang disenyo, gumawa ng isa pang prototype task. Nagsisingil si Meshy para sa bawat prototype task nang hiwalay.

Para buuin ang 3D na keycap, ipasa ang ID ng task na ito sa build endpoint bilang input_task_id, kasama ang entry ng candidate_ids bilang candidate_id. Para sa mga field ng task, tingnan ang The Keycap prototype task object.

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"
}

Mga Parameter

  • Name
    image_url
    Type
    string
    Kinakailangan
    Description

    Ang larawang gagawing disenyo ng keycap, bilang isang pampublikong URL o isang data URI (data:image/jpeg;base64,<your base64-encoded image data>).

    Ang imahe ay dapat na isang JPG, JPEG, PNG, o WebP file na hindi hihigit sa 20 MB (20,000,000 bytes). Ang bawat gilid ay dapat hindi bababa sa 32 pixels, at maaaring magkaroon ang imahe ng hanggang 178,956,970 pixels sa kabuuan. Ang isang imaheng lampas sa mga limitasyong ito ay nagbabalik ng 400.

    Tinutukoy ni Meshy ang format mula sa data ng imahe, hindi mula sa extension ng file sa URL. Gumagana ang isang URL na walang extension, at sinusunod ni Meshy ang mga HTTP redirect. Inilalapat ni Meshy ang EXIF orientation, kaya ang isang pinaikot na larawan mula sa telepono ay lalabas ayon sa kung paano ito talaga nakikita.

    Ang isang data URI ay dapat base64-encoded na may image type, tulad ng data:image/png;base64,..., at ang na-decode na imahe ay dapat na JPEG, PNG, o WebP. Ang limitasyong 20 MB ay naaangkop sa na-decode na imahe, kaya ang base64 text ay maaaring humigit-kumulang isang-katlo na mas malaki.

  • Name
    name
    Type
    string
    Description

    Isang pangalan para sa task, hanggang 100 character. Babalik ito sa name field ng task. Ang mas mahabang pangalan ay nagbabalik ng 400.

  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Kung aalisin ang background mula sa prototype na imahe. Ang true ay nagbabalik ng isang transparent na RGBA PNG, para mailagay mo ang keycap sa anumang background. Kung hindi maalis ni Meshy ang background, ibinabalik nito ang imahe kasama ang background nito, at matagumpay pa rin ang task.

    Ang head design na ginagawang 3D ng build ay pananatilihin ang background nito sa alinmang paraan. Ipipinta ng build ang base ng keycap mula sa imahe sa image_urls, nang walang background kung ipinadala mo ang true. Ibabalik ng build ang imaheng iyon bilang process_image_urls.composite.

Ibinabalik

Ang result field ay naglalaman ng ID ng bagong prototype task. Kunin ang task o i-stream ito hanggang ang status ay maging SUCCEEDED. Pagkatapos, ipasa ang ID sa build endpoint bilang input_task_id, kasama ang entry mula sa candidate_ids bilang candidate_id.

Mga paraan ng pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi maaaring tumakbo ang request. Halimbawa:

    • Nawawala ang image_url.
    • Ang imahe ay hindi isang JPG, JPEG, PNG, o WebP file.
    • Masyadong maliit ang imahe, lampas sa 20 MB, o lampas sa maximum na bilang ng pixel.
    • Hindi ma-download ni Meshy ang imahe, halimbawa dahil nagbabalik ang URL ng 404 o nag-timeout.
    • Hindi valid na base64 ang data URI.
    • Na-flag ang imahe bilang NSFW.

    Sinasabi ng error message kung aling problema ang nakita nito. Ayusin ang request, pagkatapos ay ipadala itong muli.

  • Name
    401 - Unauthorized
    Description

    Nawawala o invalid ang API key. Suriin ang Authorization header.

  • Name
    402 - Payment Required
    Description

    Isa sa mga sumusunod ang naaangkop:

    • Walang sapat na credits ang account.
    • Naabot ng API key, workspace, o miyembro ang limitasyon nito sa credits.
    • Nasa free plan ang account.

    Suriin ang iyong credits at plan, pagkatapos ay subukan muli.

  • Name
    403 - Forbidden
    Description

    Naka-on ang IP Filtering ng iyong team, at na-flag ni Meshy ang imahe dahil sa intellectual property ng ibang partido. Magpadala ng imaheng may karapatan kang gamitin.

  • Name
    429 - Too Many Requests
    Description

    Isa sa mga sumusunod na limitasyon ang naabot:

    • Nagpadala ka ng mas maraming request kaysa sa pinapayagan ng iyong rate limit. Maghintay ng ilang segundo, pagkatapos ay subukan muli. Tingnan ang Rate limits.
    • Masyadong maraming task mo ang naka-queue o tumatakbo. Maghintay hanggang matapos ang ilan, pagkatapos ay subukan muli.
    • Sa isang unlimited plan na walang natitirang credits, naabot mo ang bilang ng mga task na maaaring tumakbo nang walang credits. Maghintay hanggang matapos ang isang task, o magdagdag ng credits.
  • Name
    500 - Internal Server Error
    Description

    Nakaranas si Meshy ng server error, halimbawa dahil hindi natakbo ang content moderation o ang intellectual property check, o hindi ma-store ni Meshy ang imahe. Hindi gagawa si Meshy ng task, at ire-refund ang anumang credits na sinisingil nito. Subukang muli ang request.

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

Gumawa ng Keycap build task

Bumubuo ng textured na 3D keycap mula sa isang matagumpay na prototype task at isa sa mga kandidato nito. Para sa mga field nito, tingnan ang The Keycap build task object.

Isang build task ang tumatakbo sa bawat hakbang. Bumubuo ito ng 3D model mula sa disenyo at kinukulayan ito. Pagkatapos, inilalagay at pinuputol nito ang model sa keycap base gamit ang isang calibrated na default na pose, kaya hindi mo na kailangang i-adjust ito nang manu-mano. Sa huli, isinasama-sama nito ang keycap at ini-export ang mga file. Karaniwang tumatagal ang isang build nang 3 hanggang 7 minuto.

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"
}

Mga Parameter

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang ID ng prototype task na bubuuin. Dapat itong isang task na ginawa ng iyong account gamit ang POST /openapi/creative-lab/keycap/v1/prototype, na may status na SUCCEEDED.

    Ang isang ID na hindi isa sa mga Keycap prototype task mo mula sa API ay nagbabalik ng 404, kasama na ang prototype na ginawa sa web app.

  • Name
    candidate_id
    Type
    string
    Kinakailangan
    Description

    Ang kandidatong bubuuin, mula sa candidate_ids array ng prototype task. Ang isang value na wala sa array na iyon ay nagbabalik ng 400.

  • Name
    name
    Type
    string
    Description

    Isang pangalan para sa task, hanggang 100 character. Lumalabas ito sa name field ng task. Ang mas mahabang pangalan ay nagbabalik ng 400.

options

Opsyonal na mga setting ng heometriya. May calibrated default ang bawat field, kaya ipadala lamang ang mga field na gusto mong baguhin.

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

    Ang keycap base na pagbubuhan. Ang tanging value ay cherry-mx-1x1-r1, isang standard na Cherry MX profile 1u keycap. Hindi suportado ang mga custom na sukat, at ang anumang ibang value ay nagbabalik ng 400.

  • Name
    head_size_mm
    Type
    number
    default 23
    Description

    Ang sukat ng head sa kahabaan ng pinakamahabang dimensyon nito, sa millimeters, mula 10 hanggang 40. Isinasaayos ni Meshy ang sukat ng head para tumugma ang pinakamahabang dimensyon nito sa value na ito. Ang value na labas sa saklaw ay nagbabalik ng 400.

    Para sa value na higit sa humigit-kumulang 32.9, maaaring bawasan ni Meshy ang sukat para umangkop ang head sa protective footprint limit ng base. Maaaring maging mas maliit kaysa sa hiniling mo ang head. Hindi ibinabalik ng task object ang sukat na inilapat ni Meshy. Para suriin ito, sukatin ang bounding box ng keycap-head mesh sa model.

  • Name
    vertical_offset_mm
    Type
    number
    default 0
    Description

    Ang vertical offset na ilalapat sa head bago ito ilagay ni Meshy sa base, sa millimeters, mula -5 hanggang 5. Ang value na labas sa saklaw ay nagbabalik ng 400.

Mga Ibabalik

Ang result field ang naghahawak ng ID ng bagong build task. Kunin ang task o i-stream ito hanggang maging SUCCEEDED ang status. Pagkatapos, i-download ang GLB file mula sa model_urls.glb at ang OBJ bundle mula sa model_urls.obj_zip.

Ini-export ni Meshy ang GLB file at ang OBJ bundle sa real-world scale sa millimeters. Pareho silang gumagamit ng Y-up coordinate system, kung saan ang harapan ng keycap ay nakaharap sa +Z.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi matakbo ang request. Halimbawa:

    • Nawawala ang input_task_id o hindi ito isang valid na task ID.
    • Hindi SUCCEEDED ang status ng prototype task. Kung tumatakbo pa ito, maghintay at subukang muli. Kung nabigo ito o na-cancel, gumawa ng bagong prototype task.
    • Nagtagumpay ang prototype task ngunit walang mga kandidato. Gumawa ng bagong prototype task.
    • Nawawala ang candidate_id, o wala ito sa candidate_ids ng prototype task. Magpadala ng value mula sa array na iyon.
    • Ang isang field sa options ay labas sa saklaw, o hindi available na value ang base_model.

    Sinasabi ng error message kung aling problema ang natagpuan nito.

  • Name
    401 - Unauthorized
    Description

    Nawawala o hindi valid ang API key. Suriin ang Authorization header.

  • Name
    402 - Payment Required
    Description

    Isa sa mga sumusunod ang nangyari:

    • Hindi sapat ang credits ng account.
    • Naabot ng API key, workspace, o member ang credit limit nito.
    • Nasa free plan ang account.

    Suriin ang iyong credits at plan, pagkatapos ay subukang muli.

  • Name
    404 - Not Found
    Description

    Hindi tumutugma ang input_task_id sa anumang Keycap prototype task na ginawa ng account mo gamit ang API. Ang isang prototype na ginawa sa web app ay nagbabalik din ng 404. Ipadala ang result ID mula sa tugon ng paggawa ng prototype.

  • Name
    429 - Too Many Requests
    Description

    Isa sa mga sumusunod na limitasyon ang naabot:

    • Mas maraming request ang ipinadala mo kaysa sa pinapayagan ng rate limit mo. Maghintay ng ilang segundo, pagkatapos ay subukang muli. Tingnan ang Rate limits.
    • Masyadong maraming task mo ang naka-queue o tumatakbo. Maghintay hanggang matapos ang ilan, pagkatapos ay subukang muli.
    • Sa isang unlimited plan na walang natitirang credits, naabot mo ang bilang ng mga task na maaaring tumakbo nang walang credits. Maghintay hanggang matapos ang isang task, o magdagdag ng credits.
  • Name
    500 - Internal Server Error
    Description

    Hindi nakagawa si Meshy ng task dahil sa isang server error. Ire-refund ni Meshy ang anumang credits na siningil nito. Subukang muli ang request.

GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Kunin ang isang Keycap task

Ibinabalik ang isang prototype o build task. Ang path ay dapat tumugma sa stage ng task. Ang isang build task na hiniling sa pamamagitan ng /prototype/:id ay magbabalik ng 404, at ganoon din ang isang prototype task na hiniling sa pamamagitan ng /build/:id.

Para sa mga field, tingnan ang The Keycap prototype task object at The Keycap build task object.

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=***"
  }
}

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Ang task ID mula sa create response.

Mga Ibinabalik

Ang prototype task object o ang build task object, ayon sa stage na nasa path.

Mga mode ng pagkabigo

  • Name
    400 - Bad Request
    Description

    Ang id ay hindi isang wastong task ID. Ipadala ang result ID mula sa create response.

  • Name
    403 - Forbidden
    Description

    Naka-on ang IP Filtering ng iyong team, at ni-flag ng Meshy ang imahe ng prototype task dahil sa intellectual property ng ibang partido. Hindi nakukuha ng mga build task at ng mga team sa Enterprise plan ang error na ito. Gumawa ng prototype task mula sa isang imahe na may karapatan kang gamitin.

  • Name
    404 - Not Found
    Description

    Walang Keycap task na may ID na ito na kabilang sa iyong account, o hindi tumutugma ang stage ng task sa path. Tingnan ang ID, at gamitin ang /prototype o /build para tumugma sa task.

  • Name
    500 - Internal Server Error
    Description

    Hindi na-run ng Meshy ang pagsusuri ng intellectual property. Subukan ulit ang request.

DELETE/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Mag-delete ng Keycap task

Kinakansela ang isang Keycap task. Ang pagkansela ng isang PENDING task ay nagre-refund ng mga credits nito. Ang isang IN_PROGRESS task ay kinakansela nang walang refund, dahil nagsimula na itong iproseso ng isang worker. Ang task na may final status (SUCCEEDED, FAILED, o CANCELED) ay hindi na puwedeng kanselahin.

Dapat tumugma ang path sa stage ng task. Halimbawa, ang DELETE sa /prototype/:id gamit ang ID ng isang build task ay magbabalik ng 404.

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).

Mga path parameter

  • Name
    id
    Type
    path
    Description

    Ang ID ng task na kakanselahin.

Ibinabalik

204 No Content na may walang laman na body.

Mga failure mode

  • Name
    400 - Bad Request
    Description

    Isa sa mga sumusunod ang nangyari:

    • Ang id ay hindi isang valid na task ID. Ipadala ang result ID mula sa create response.
    • Mayroon nang final status ang task (SUCCEEDED, FAILED, o CANCELED), kaya hindi na ito puwedeng kanselahin.
  • Name
    404 - Not Found
    Description

    Walang Keycap task na may ID na ito na kabilang sa iyong account, o hindi tumutugma ang stage ng task sa path. Suriin ang ID, at gamitin ang /prototype o /build para tumugma sa task.

  • Name
    500 - Internal Server Error
    Description

    Nagkaroon ng server error ang Meshy habang kinakansela ang task, kaya maaaring kanselado o hindi kanselado ang task. Kunin ang task para suriin ang status nito bago muling subukan.

GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id/stream

I-stream ang isang Keycap task

Ini-stream ang mga update ng isang Keycap task bilang Server-Sent Events (SSE). Ang path ay dapat tumugma sa stage ng task. Kung hindi, halimbawa ang ID ng isang build task sa /prototype/:id/stream, ang stream ay magpapadala ng isang error event na may status_code: 404 at magsasara.

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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
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=***"
  }
}

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Ang task ID mula sa create response.

Ibinabalik

Isang stream ng prototype o build na mga task object. Bawat event ay may buong task object, tulad ng ibinabalik ito ng Get a Keycap task. Habang ang task ay PENDING o IN_PROGRESS, ang mga output field nito ay walang laman pa rin (null, [], o {}), at ang finished_at ay null.

Kung ha-harangan ng IP Filtering ang resulta ng task, ang stream ay magpapadala ng isang error event sa halip nito, na may status_code na ibabalik sana ng isang get request.

GET/openapi/creative-lab/keycap/v1/(prototype|build)

I-list ang mga Keycap task

Ibinabalik ang iyong mga Keycap task para sa isang stage, isang page sa bawat pagkakataon. Ang path ang pumipili ng stage. Ang /prototype ay nagbabalik lamang ng mga prototype task, at ang /build ay nagbabalik lamang ng mga build task.

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 (List Prototype Tasks)

[
  {
    "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"
    ]
  }
]

Mga path parameter

  • Name
    stage
    Type
    path
    Kinakailangan
    Description

    Ang stage na ililista, prototype o build.

Mga query parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Ang page na ibabalik, mula 1 hanggang 255. Ang 0 ay nagbabalik ng unang page. Ang isang value na wala sa 0 hanggang 255 ay nagbabalik ng 400.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Bilang ng mga task bawat page, hanggang 100. Ang isang value mula 101 hanggang 255 ay nagbabalik ng 100 task, at ang 0 ay gumagamit ng default. Ang isang value na wala sa 0 hanggang 255 ay nagbabalik ng 400.

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    Ang pagkakasunod-sunod ng pag-uuri.

    Mga available na value:

    • -created_at: pinakabago muna
    • +created_at: pinakaluma muna

Ibinabalik

Isang array ng prototype task objects o build task objects, na tumutugma sa stage na nasa path.

Ang Keycap prototype task object

Ang isang prototype task ay gumagawa ng isang imahe ng natapos na keycap mula sa isang larawan. Para gawing 3D keycap ang disenyo, ipasa ang ID ng task sa build endpoint bilang input_task_id, kasama ang kaukulang candidate_ids entry nito bilang candidate_id.

Mga Properties

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"
  ]
}
  • Name
    id
    Type
    string
    Description

    Ang ID ng task. Huwag umasa sa format nito.

  • Name
    type
    Type
    string
    Description

    Ang uri ng task, palaging creative-lab-keycap-prototype.

  • Name
    name
    Type
    string
    Description

    Ang name na ipinadala mo nang ginawa mo ang task, o "" kung wala kang ipinadala.

  • Name
    status
    Type
    string
    Description

    Ang status ng task.

    Mga available na halaga:

    • PENDING: naghihintay sa pila
    • IN_PROGRESS: ginagawa ang resulta
    • SUCCEEDED: pinal, may resulta
    • FAILED: pinal, may dahilan sa task_error
    • CANCELED: pinal, walang resulta
  • Name
    progress
    Type
    integer
    Description

    Porsyento ng natapos na trabaho, mula 0 hanggang 100. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay matagumpay.

  • Name
    created_at
    Type
    timestamp
    Description

    Oras na ginawa ang task, sa Unix milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Oras na sinimulan ng isang worker ang task, sa Unix milliseconds. null hanggang mangyari iyon.

  • Name
    finished_at
    Type
    timestamp
    Description

    Oras na naabot ng task ang pinal na status, sa Unix milliseconds. null hanggang mangyari iyon.

  • Name
    expires_at
    Type
    timestamp
    Description

    Oras na mag-e-expire ang resulta ng task, sa Unix milliseconds. Ito ay 3 araw pagkatapos ng finished_at, o 3 araw pagkatapos ng created_at hanggang matapos ang task. Para sa mga Enterprise account, na nagpapanatili ng mga resulta ng API nang walang hanggan, ito ay humigit-kumulang 100 taon pagkalipas. Tingnan ang Asset retention.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang posisyon ng task sa pila habang ito ay PENDING. Ang 1 ay nangangahulugang susunod na itong magsisimula. 0 pagkatapos umalis ng task sa pila, at palaging 0 sa mga resulta ng listahan.

  • Name
    task_error
    Type
    object
    Description

    Kung bakit nabigo ang task. null maliban kung ang status ay FAILED. Tingnan ang Errors.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilang ng mga credits na sinisingil para sa task, pagkatapos ng anumang refund. Ang isang request na nagbabalik ng error ay hindi sinisingil. Ang isang nabigong task ay 0, dahil ire-refund ito ng Meshy. Ang pagkansela ay nagre-refund ng task lamang habang ito ay PENDING. Kung hindi mabasa ng Meshy ang singil, ang isang get o stream na tugon ay hindi isasama ang field, at ang isang list request ay magbabalik ng 500. Sa ganitong pagkakataon, subukan muli ang request.

  • Name
    image_urls
    Type
    array of strings
    Description

    Mga download URL para sa imahe ng natapos na keycap. Ang array ay may isang URL pagkatapos magtagumpay ang task, at walang laman hanggang mangyari iyon. Ipinapakita ng image_urls[i] ang kandidato sa candidate_ids[i].

    Ang mga URL na ito ay para sa pagpapakita. Ang build endpoint ay kumukuha ng entry mula sa candidate_ids, hindi ng URL. Ang mga ito ay signed URL, kaya kunin ang mga ito nang walang Authorization header. Nananatili itong valid hanggang expires_at, at ang muling pagkuha sa task ay nagbabalik ng parehong mga URL.

  • Name
    candidate_ids
    Type
    array of strings
    Description

    Mga ID ng mga kandidato, sa parehong pagkakasunod-sunod gaya ng image_urls. Para bumuo ng isang kandidato, ipadala ang ID nito bilang candidate_id sa build request. Huwag umasa sa format ng mga ID na ito.

Ang Keycap build task object

Ang isang build task ay bumubuo ng textured na 3D keycap mula sa isang matagumpay na prototype task at isa sa mga candidate nito. Bumubuo ito ng 3D model, kinukulayan ito, inilalagay at pinuputol ito sa keycap base, at pagkatapos ay ina-assemble at ineksport ang keycap.

Mga Property

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=***"
  }
}
  • Name
    id
    Type
    string
    Description

    Ang task ID. Huwag umasa sa format nito.

  • Name
    type
    Type
    string
    Description

    Ang uri ng task, laging creative-lab-keycap-build.

  • Name
    name
    Type
    string
    Description

    Ang name na ipinadala mo nang ginawa mo ang task, o "" kung wala kang ipinadala.

  • Name
    status
    Type
    string
    Description

    Ang status ng task.

    Mga available na value:

    • PENDING: naghihintay sa queue
    • IN_PROGRESS: bumubuo ng resulta
    • SUCCEEDED: final, may resulta
    • FAILED: final, may dahilan sa task_error
    • CANCELED: final, walang resulta
  • Name
    progress
    Type
    integer
    Description

    Porsyento ng natapos na gawain, mula 0 hanggang 100. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.

  • Name
    created_at
    Type
    timestamp
    Description

    Oras na nagawa ang task, sa Unix milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Oras na sinimulan ng worker ang task, sa Unix milliseconds. null hanggang mangyari iyon.

  • Name
    finished_at
    Type
    timestamp
    Description

    Oras na umabot ang task sa final status, sa Unix milliseconds. null hanggang mangyari iyon.

  • Name
    expires_at
    Type
    timestamp
    Description

    Oras na mag-e-expire ang resulta ng task, sa Unix milliseconds. Ito ay 3 araw pagkatapos ng finished_at, o 3 araw pagkatapos ng created_at hanggang matapos ang task. Para sa mga Enterprise account, na nagpapanatili ng mga resulta ng API nang walang katapusan, ito ay humigit-kumulang 100 taon mamaya. Tingnan ang Asset retention.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang posisyon ng task sa queue habang ito ay PENDING. Ang 1 ay nangangahulugang susunod na itong magsisimula. 0 pagkatapos umalis ang task sa queue, at laging 0 sa mga resulta ng listahan.

  • Name
    task_error
    Type
    object
    Description

    Kung bakit nabigo ang task. null maliban kung ang status ay FAILED. Tingnan ang Errors.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilang ng mga credit na sinisingil para sa task, pagkatapos ng anumang refund. Ang isang request na nagbabalik ng error ay hindi sinisingil. Ang isang nabigong task ay 0, dahil ire-refund ito ni Meshy. Ang pagkansela ay nagre-refund ng task lamang habang ito ay PENDING. Kung hindi mabasa ni Meshy ang singil, aalisin ng get o stream response ang field, at magbabalik ang list request ng 500. Sa ganitong pagkakataon, subukan muli ang request.

  • Name
    model_urls
    Type
    object
    Description

    Mga download URL para sa 3D model. Ineksport ni Meshy ang GLB file at ang OBJ bundle sa real-world scale sa millimeters, Y-up, na ang harap ng keycap ay nakaharap sa +Z.

    Ang model ay may mga mesh na pinangalanang keycap-head at keycap-base. Kapag bumalik si Meshy sa isang pattern fill para sa base, ang model ay mayroon ding keycap-base-interior na mesh para sa stem cavity. Huwag ipagpalagay na ang model ay may eksaktong dalawang mesh.

    Ito ay mga signed URL, kaya kunin ang mga ito nang walang Authorization header. Mananatili itong valid hanggang expires_at, at ang muling pagkuha ng task bago dumating ang oras na iyon ay magbabalik ng parehong mga URL. Ang isang expired URL ay hindi na mare-renew, kaya i-download at i-store ang mga file bago mag-expire ang mga ito.

    • Name
      glb
      Type
      string
      Description

      Download URL para sa textured GLB file, model.glb.

    • Name
      obj_zip
      Type
      string
      Description

      Download URL para sa OBJ bundle, isang ZIP file na may model.obj, model.mtl, at ang mga PNG texture na ginagamit ng model.mtl. Sa isang solid-color na base, ang tanging texture ay keycap-head.png. Sa isang may-pattern na base, ang ZIP file ay mayroon ding keycap-base.png.

  • Name
    process_image_urls
    Type
    object
    Description

    Mga download URL para sa mga larawan mula sa mga hakbang ng build, naka-key ayon sa uri. Tulad ng model_urls, ang mga ito ay signed URL, kaya kunin ang mga ito nang walang Authorization header. Mananatili itong valid hanggang expires_at, at ang muling pagkuha ng task ay magbabalik ng parehong mga URL.

    Maaaring magkaroon ito ng mga sumusunod na key:

    • head_design: ang design image ng napiling candidate, na ginawang 3D ng build. Palaging naroroon.
    • composite: ang larawan ng tapos na keycap para sa napiling candidate, kung saan ipininta ng build ang base. Maaaring mawala.
    • base_canvas: ang pinintahang keycap base. Maaaring mawala.

    Maaaring magdagdag si Meshy ng mga key, kaya huwag pansinin ang isang key na hindi mo nakikilala.

End-to-end example

Isinasagawa ng halimbawang ito ang buong daloy:

  1. Gumawa ng prototype task mula sa isang larawan.
  2. Kunin ang task hanggang ang status nito ay SUCCEEDED.
  3. Pumili ng kandidato mula sa candidate_ids.
  4. Gumawa ng build task gamit ang kandidatong iyon.
  5. Kunin ang build task hanggang ang status nito ay SUCCEEDED.
  6. I-download ang GLB file at ang OBJ bundle mula sa model_urls.

Pinipili ng halimbawa ang unang kandidato. Sa iyong app, ipakita ang mga entry ng image_urls sa iyong mga user at hayaan silang pumili. Ang index ng napiling larawan sa image_urls ay siya ring index ng ID nito sa candidate_ids.

Complete flow

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"