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

Creative Lab — Collapsible Fidget API

I-convert ang isang source photo tungo sa isang print-in-place na collapsible fidget toy: ang silhouette ng subject ay nagiging isang hanay ng magkakalapat na concentric rings na kumukupas nang patag at muling lumalawak, na naka-print sa iisang piraso nang walang pangangailangang mag-assemble.

  • POST /openapi/creative-lab/fidget-collapsible/v1

Hindi tulad ng ibang mga endpoint ng Creative Lab, wala itong prototype/build stage pair — walang mga intermediate na kandidato na pagpipilian, kaya ang iisang task ang nagdadala sa larawan hanggang sa maging isang 3D model. Ang mga kontrol sa heometriya na inilalantad ng web app (laki, bilang ng layer, lapad ng gap, kapal ng dingding, lalim ng extrusion, bulge) ay hindi rin bahagi ng request: bawat task ay gumagawa gamit ang parehong mga default sa server-side.

POST/openapi/creative-lab/fidget-collapsible/v1

Create a Collapsible Fidget Task

Gumawa ng collapsible fidget model mula sa isang pinagmulang larawan. Sumangguni sa The Collapsible Fidget Task Object para sa hugis ng response.

Ang bawat task ay nagkakahalaga ng 6 credits at nangangailangan ng paid plan.

Mga Parameter

  • Name
    image_url
    Type
    string
    Kinakailangan
    Description

    Pinagmulang larawan na gagawin ni Meshy na collapsible fidget. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, .png, at .webp.

    Maximum na laki ng file: 20 MB.

    May dalawang paraan para magbigay ng larawan:

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

    Ang isang subject na may isang malinaw at sarado ang outline ang pinakamainam — ang silweta ang magiging mga singsing. Ang mga abalang background, maraming hiwalay na subject, o napakanipis na hugis ay maaaring magbigay ng kakaunting espasyo para sa nested na mga dingding, at mabibigo ang task na may task error.

  • Name
    name
    Type
    string
    Description

    Opsyonal na pangalan ng task para sa layuning pagpapakita. Pinakamataas na 100 character. Ito ay label lamang ng task; walang isinusulat sa modelo.

Mga Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong nagawang collapsible fidget task. I-poll ang Get a Task endpoint o mag-subscribe sa stream hanggang maabot ng task ang SUCCEEDED, pagkatapos ay i-download ang maprint na STL mula sa model_urls.stl (at, kung mayroon, ang GLB mula sa model_urls.glb para i-preview muna ito).

Mga Pamamaraan ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:

    • Nawawalang parameter: Kailangan ang image_url.
    • Hindi wastong format ng larawan: Ang ibinigay na image_url ay hindi suportadong format (.jpg, .jpeg, .png, .webp).
    • Laki ng larawan na wala sa sakop: Masyadong maliit ang larawan, lumampas sa maximum na laki ng file, o lumampas sa maximum na bilang ng pixel.
    • Hindi maabot na URL: Hindi ma-download ang image_url (404 o timeout).
    • Hindi wastong Data URI: Hindi tama ang pagkakaayos ng base64 string.
    • Na-flag na content: Na-flag ang input na larawan ng NSFW moderation.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Mangyaring suriin ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Alinman sa iyong account ay nasa free plan — ang paggawa ng task sa endpoint na ito ay nangangailangan ng paid plan — o kulang ang iyong mga credits.

  • Name
    403 - Forbidden
    Description

    Na-flag ang input na larawan dahil sa paglabag sa intellectual property.

  • Name
    429 - Too Many Requests
    Description

    Lumampas ka sa iyong rate limit.

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/creative-lab/fidget-collapsible/v1/:id

Kunin ang isang Collapsible Fidget Task

Kunin ang isang collapsible fidget task gamit ang isang wastong task id. Tanging ang mga task na ginawa sa pamamagitan ng endpoint na ito ang maa-access dito — ang isang task mula sa ibang Creative Lab endpoint, o isang ginawa sa web app, ay nagbabalik ng 404.

Tingnan ang The Collapsible Fidget Task Object para sa hugis ng response.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa collapsible fidget task na kukunin.

Ibinabalik

Ang response ay naglalaman ng collapsible fidget task object.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

I-delete ang Collapsible Fidget Task

Kanselahin ang isang collapsible fidget task. Kung ang task ay PENDING pa rin, ang mga credits na nagamit sa oras ng paglikha ay ire-refund. Ang mga task na IN_PROGRESS na ay kanselahin nang walang refund (maaaring ginagamit na ng worker ang mga resources). Ang mga task na nakarating na sa isang terminal state (SUCCEEDED, FAILED, CANCELED) ay hindi na maaaring kanselahin.

Mga Path Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa collapsible fidget task na kakanselahin.

Ibinabalik

Nagbabalik ng 204 No Content kapag matagumpay, na may walang laman na body.

Mga Failure Mode

  • 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, pag-aari ito ng ibang user, o hindi ito nalikha sa pamamagitan ng endpoint na ito.

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

I-stream ang Isang Collapsible Fidget Task

Mag-stream ng mga real-time na update para sa isang collapsible fidget task sa pamamagitan ng Server-Sent Events (SSE). Ang isang task na hindi umiiral, o hindi ginawa sa pamamagitan ng endpoint na ito, ay maglalabas ng iisang event: error payload na may status_code: 404 at isasara ang stream.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa collapsible fidget task na i-stream.

Ibinabalik

Nagbabalik ng stream ng mga Collapsible Fidget task object bilang Server-Sent Events. Bawat frame ay nagdadala ng buong task object para sa yugto — ang parehong hugis na ibinabalik ng Get endpoint — kaya habang ang task ay PENDING o IN_PROGRESS, ang mga output field ay hindi pa lamang napopopulate (null, [] o {}) at ang finished_at ay null.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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 PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Ilista ang Collapsible Fidget Tasks

Kunin ang isang paginated na listahan ng iyong collapsible fidget tasks. Tanging ang mga task na ginawa sa pamamagitan ng endpoint na ito ang kasama.

Query Parameters

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Numero ng pahina para sa pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

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

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    Field na gagamitin sa pag-sort. Mga magagamit na value:

    • +created_at: I-sort ayon sa oras ng paggawa sa ascending order.
    • -created_at: I-sort ayon sa oras ng paggawa sa descending order.

Returns

Nagbabalik ng paginated na listahan ng the collapsible fidget task object.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

The Collapsible Fidget Task Object

Ang Collapsible Fidget Task object ay isang work unit na sinusubaybayan ng Meshy upang gawing print-in-place na collapsible fidget model ang isang source photo. Ito ay isang single-stage task: walang prototype na maaaring i-chain mula rito, at ang intermediate silhouette ay hindi bahagi ng response.

Mga Katangian

  • Name
    id
    Type
    string
    Description

    Natatanging identifier para sa task. Bagaman gumagamit kami ng k-sortable UUID para sa task ids bilang implementation detail, hindi mo dapat ipagpalagay ang format ng id.

  • Name
    type
    Type
    string
    Description

    Uri ng task. Ang value ay creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    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.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp kung kailan ginawa ang task, sa milliseconds.

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • 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 ang value ng field na ito kung ang status 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 reference ng task_error object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (naibabalik ang credits kapag nabigo).

  • Name
    model_urls
    Type
    object
    Description

    Mga downloadable URL para sa nabuong 3D model. Napupunan kapag SUCCEEDED na ang task: laging naroroon ang stl, at ang glb ay naroroon lamang kapag nagtagumpay ang preview render.

    • Name
      stl
      Type
      string
      Description

      Downloadable URL patungo sa STL file. Ito ang printable na deliverable — direktang ipadala ito sa isang slicer.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL patungo sa GLB file, para sa pag-preview ng model sa isang 3D viewer. Ang mga kulay nito ay para lamang sa preview: walang kulay ang STL, at ang kulay ng isang naka-print na fidget ay nagmumula sa filament. Ang GLB ay best-effort: kapag hindi available ang preview render, ganap na tinatanggal ang key mula sa model_urls, kaya basahin ito nang defensive — ang stl ang deliverable at laging naroroon sa isang SUCCEEDED na task.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}