Creative Lab Fidget Pixel API

Gawing multi-color, 3D-printable na pixel-art fidget board ang isang larawan sa dalawang yugto. Ginagawang pixel-art na imahe ng isang prototype task ang larawan. Ginagawang magkakaugnay na mga piraso sa iisang 3MF file ng isang build task ang imaheng iyon, at ginagamit ang ID ng prototype task bilang input_task_id.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

Kailangan ng parehong POST endpoint ang isang bayad na plano. Ibinabalik ang 402 para sa isang request mula sa isang account na nasa free plan.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Gumawa ng Fidget Pixel prototype task

Gumagawa ng isang pixel-art na larawan mula sa isang litrato. Para buuin ang mga piraso, ipasa ang ID ng task na ito sa build endpoint bilang input_task_id. Para sa mga field ng task, tingnan ang The Fidget Pixel prototype task object.

Kung hindi mo nagustuhan ang larawan, gumawa ng isa pang prototype task. Sinisingil nang hiwalay ang bawat task.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Mga Parameter

Name
image_url
Type
string
Kinakailangan
Description
Ang litratong gagawing pixel art, bilang isang pampublikong URL o isang data URI (data:image/jpeg;base64,<your base64-encoded image data>).
Dapat ang larawan ay isang JPG, JPEG, PNG, o WebP na file na hindi hihigit sa 20 MB. Tinutukoy ng Meshy ang format mula sa data ng larawan, hindi mula sa extension ng file sa URL. Gagana ang URL na walang extension, at sinusunod ng Meshy ang mga redirect.
Name
type
Type
string
Kinakailangan
Description
Ang nilalaman ng litrato, na nagtatakda ng pixel-art style. Malinaw na magkaiba ang dalawang style. Ang anumang ibang value ay magbabalik ng 400.
Mga available na value:
- person: isang tao, sa isang portrait o full-body na litrato. Gumuguhit ang Meshy ng chibi-style na pixel sprite.
- other: anumang ibang paksa, halimbawa isang alagang hayop, isang bagay, isang mascot, isang logo, o isang tanawin. Gumuguhit ang Meshy ng bead-art style na pixel icon.
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 magbabalik ng 400.

Mga Ibinabalik

Hawak ng result field ang ID ng bagong prototype task. Kunin ang task o i-stream ito hanggang ang status ay SUCCEEDED. Pagkatapos, ipasa ang ID sa build endpoint bilang input_task_id.

Mga mode ng kabiguan

Name
400 - Bad Request
Description
Hindi maaaring tumakbo ang request. Halimbawa:
- Nawawala ang image_url o type.
- Ang type ay hindi person o other.
- Ang larawan ay hindi isang JPG, JPEG, PNG, o WebP na file.
- Masyadong maliit ang larawan, lampas sa 20 MB, o lampas sa maximum na bilang ng pixel.
- Hindi ma-download ng Meshy ang larawan, halimbawa dahil nagbabalik ang URL ng 404 o nag-timeout.
- Hindi valid na base64 ang data URI.
- Na-flag ang larawan bilang NSFW.
Sinasabi ng error message kung aling problema ang nahanap nito. Ayusin ang request, pagkatapos ay ipadala itong muli.
Name
401 - Unauthorized
Description
Nawawala o invalid ang API key. Tingnan ang Authorization header.
Name
402 - Payment Required
Description
Isa sa mga ito ang naaangkop:
- Hindi sapat ang credits ng account.
- Naabot ng API key, workspace, o miyembro ang limitasyon ng credit nito.
- Nasa free plan ang account.
Tingnan ang iyong credits at plan, pagkatapos ay subukan ulit.
Name
403 - Forbidden
Description
Naka-on ang IP Filtering ng iyong team, at na-flag ng Meshy ang larawan dahil sa intellectual property ng third-party. Magpadala ng larawan na may karapatan kang gamitin.
Name
429 - Too Many Requests
Description
Naabot ang isa sa mga limitasyong ito:
- Nagpadala ka ng mas maraming request kaysa sa pinapayagan ng iyong rate limit. Maghintay ng ilang segundo, pagkatapos ay subukan ulit. Tingnan ang Rate limits.
- Masyadong maraming task mo ang naka-queue o tumatakbo. Maghintay hanggang matapos ang ilan, pagkatapos ay subukan ulit.
- Sa isang unlimited plan na walang natitirang credits, naabot mo na 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
Nagkaroon ng server error ang Meshy, halimbawa dahil hindi nito napatakbo ang intellectual property check sa larawan. Hindi gumagawa ang Meshy ng task, at ibinabalik ang anumang credits na sinisingil nito. Subukan ulit ang request.

POST/openapi/creative-lab/fidget-pixel/v1/build

Gumawa ng Fidget Pixel build task

Bumubuo ng mga 3D-printable na piraso mula sa isang matagumpay na prototype task. Sina-sample ni Meshy ang pixel-art na imahe papunta sa grid at binabawasan ito sa hindi hihigit sa color_count na kulay. Ang bawat cell ng subject ay nagiging isang magkakaugnay na piraso, at ang background ay hindi na-print.

Ang resulta ay isang solong multi-color 3MF file, handa nang i-print nang may kulay. Ang bawat piraso ay may kulay-abong katawan at isang tuktok na may kulay ng kaukulang pixel nito. Para sa mga field nito, tingnan ang The Fidget Pixel build task object.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng prototype task na i-build. Dapat itong isang task na ginawa ng iyong account gamit ang POST /openapi/creative-lab/fidget-pixel/v1/prototype, na may status na SUCCEEDED.
Ang isang ID na hindi kabilang sa iyong mga Fidget Pixel prototype task mula sa API ay nagbabalik ng 404, kasama na ang prototype na ginawa sa web app.
Name
name
Type
string
Description
Isang pangalan para sa task, hanggang 100 character. Babalik ito sa name field ng task. Ang isang mas mahabang pangalan ay nagbabalik ng 400.

`options`

Mga setting para sa hugis at laki ng mga piraso. Ang bawat field ay may default, kaya ipadala lamang ang mga field na gusto mong baguhin. Ang 0 ay gumagamit ng default ng field. Ito ang mga parehong setting tulad ng sa Creative Lab web app. Ang ibang mga setting ng hugis ay naka-fix, at itinatakda ito ni Meshy batay sa shape at piece_size_mm.

Name
shape
Type
string
default square
Description
Ang footprint ng bawat piraso. Anumang ibang value ay nagbabalik ng 400.
Mga available na value:
- square: mga parisukat na piraso sa isang parisukat na grid
- hex: mga hexagonal na piraso sa isang hexagonal na grid, kasama ang piece_size_mm na nakatakda sa 6 o 8
Name
grid_size
Type
integer
default 32
Description
Ang bilang ng mga grid cell sa bawat gilid ng board, 16 o 32. Anumang ibang value ay nagbabalik ng 400. Ang 32 na grid ay nagpapanatili ng mas maraming detalye. Ang 16 na grid ay nagbibigay ng mas kaunting piraso na may parehong laki, kaya ang board ay halos kalahati ang lapad.
Name
piece_size_mm
Type
integer
default 8
Description
Ang haba ng gilid ng bawat piraso sa millimeters, 6, 8, o 10. Anumang ibang value ay nagbabalik ng 400. Kasama ang grid_size, itinatakda nito ang laki ng naka-print na board. Halimbawa, ang isang 32 na grid ng 8 mm na mga piraso ay humigit-kumulang 26.5 cm bawat gilid.
Ang 10 ay hindi gumagana sa hex at nagbabalik ng 400, dahil ang pahilis na hex na mukha ay nag-o-overhang sa karamihan ng consumer FDM printer.
Name
color_count
Type
integer
default 8
Description
Ang pinakamataas na bilang ng kulay sa pixel-art palette, mula 1 hanggang 8. Ang value na labas sa range ay nagbabalik ng 400. Para makapag-print, kailangan mo ng hanggang color_count plus isang filament, isa para sa bawat kulay at isa para sa mga kulay-abong katawan.
Name
piece_height_mm
Type
integer
default 15
Description
Ang taas ng bawat piraso sa millimeters, mula 10 hanggang 80. Ang value na labas sa range ay nagbabalik ng 400.

`output`

Mga setting para sa result file.

Name
format
Type
string
default 3mf
Description
Ang file format ng resulta. Anumang ibang value ay nagbabalik ng 400.
Mga available na value:
- 3mf: isang multi-color na model.3mf file, ibinabalik sa model_urls.3mf

Ibinabalik

Ang result field ay naglalaman ng ID ng bagong build task. Kunin ang task o i-stream ito hanggang ang status ay maging SUCCEEDED. Pagkatapos, i-download ang 3MF file mula sa model_urls.3mf.

Mga paraan ng pagkabigo

Name
400 - Bad Request
Description
Hindi maaaring tumakbo ang request. Halimbawa:
- Nawawala ang input_task_id o hindi ito valid na task ID.
- Ang status ng prototype task ay hindi SUCCEEDED. Kung tumatakbo pa ito, maghintay at subukan muli. Kung nabigo ito o kinansela, gumawa ng bagong prototype task.
- Matagumpay ang prototype task ngunit walang imahe. Gumawa ng bagong prototype task.
- Ang isang options field ay labas sa mga pinapayagang value, halimbawa isang grid_size na hindi 16 o 32.
- Ang piece_size_mm ay 10 at ang shape ay hex. Ang mga hex na piraso ay available lamang sa 6 at 8 mm.
- Ang output.format ay hindi 3mf.
Sinasabi ng error message kung aling problema ang natagpuan nito.
Name
401 - Unauthorized
Description
Nawawala o invalid ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Isa sa mga ito ang naaangkop:
- Hindi sapat ang credits ng account.
- Naabot ng API key, workspace, o member ang kanyang credit limit.
- 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 ng prototype task dahil sa third-party intellectual property. Gumawa ng prototype task mula sa isang imaheng may karapatan kang gamitin.
Name
404 - Not Found
Description
Ang input_task_id ay hindi tumutugma sa anumang Fidget Pixel prototype task na ginawa ng iyong account gamit ang API. Ang 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 limitasyong ito ang naabot:
- Nagpadala ka ng higit pang mga 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 nito maisagawa ang intellectual property check sa imahe ng prototype task. Hindi gumagawa si Meshy ng task, at ibinabalik ang anumang credits na siningil nito. Subukan muli ang request.

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

Kunin ang Fidget Pixel task

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

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

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

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

Mga mode ng pagkabigo

Name
400 - Bad Request
Description
Ang id ay hindi valid na task ID. Ipadala ang result ID mula sa create response.
Name
403 - Forbidden
Description
Naka-on ang IP Filtering ng iyong team, at na-flag ng Meshy ang larawan ng prototype task dahil sa intellectual property ng third-party. Ang mga build task at mga team sa Enterprise plan ay hindi nakakatanggap ng error na ito. Gumawa ng prototype task mula sa isang larawan na may karapatan kang gamitin.
Name
404 - Not Found
Description
Walang Fidget Pixel task na may ID na ito na kabilang sa iyong account, o ang stage ng task ay hindi tumutugma sa path. Tingnan ang ID, at gamitin ang /prototype o /build upang itugma ang task.
Name
500 - Internal Server Error
Description
Hindi nagawa ng Meshy na patakbuhin ang pagsusuri ng intellectual property. Subukan muli ang request.

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

Mag-delete ng Fidget Pixel task

Kinakansela ang isang Fidget Pixel task. Ang pagkansela sa 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 isang task na may final na status (SUCCEEDED, FAILED, o CANCELED) ay hindi na maaaring kanselahin.

Ang path ay dapat tumugma 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/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -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 mode ng kabiguan

Name
400 - Bad Request
Description
Isa sa mga sumusunod ang naaangkop:
- Hindi valid na task ID ang id. Ipadala ang result ID mula sa create response.
- Mayroon nang final na status ang task (SUCCEEDED, FAILED, o CANCELED), kaya hindi na ito maaaring kanselahin.
Name
404 - Not Found
Description
Walang Fidget Pixel task na may ID na ito na kabilang sa account mo, o hindi tumutugma ang stage ng task sa path. Suriin ang ID, at gamitin ang /prototype o /build upang itugma sa task.

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

I-stream ang isang Fidget Pixel na task

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

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/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 for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Isang stream ng mga prototype o build na task object. Ang bawat event ay naglalaman ng buong task object, tulad ng ibinabalik ng Kunin ang isang Fidget Pixel na task. Habang ang task ay PENDING o IN_PROGRESS, ang mga output field nito ay bakante pa rin (null, [], o {}), at ang finished_at ay null.

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

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

I-list ang mga Fidget Pixel task

Ibinabalik ang iyong mga Fidget Pixel task para sa isang stage, isang page sa bawat pagkuha. 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/fidget-pixel/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

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 mga prototype task object o mga build task object, ayon sa stage na nasa path.

Ang Fidget Pixel prototype task object

Ang isang prototype task ay nagko-convert ng isang larawan papunta sa isang pixel-art na imahe. Para gawing 3D-printable pieces ang imahe, ipasa ang ID ng task sa build endpoint bilang input_task_id.

Properties

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Name
id
Type
string
Description
Ang task ID. Huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging creative-lab-fidget-pixel-prototype.
Name
name
Type
string
Description
Ang name na ipinadala mo nang likhain 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: ginagawa ang resulta
- SUCCEEDED: pangwakas, mayroong resulta
- FAILED: pangwakas, nasa task_error ang dahilan
- CANCELED: pangwakas, 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 nilikha ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras na sinimulan ng isang worker ang task, sa Unix milliseconds. null hanggang doon.
Name
finished_at
Type
timestamp
Description
Oras na naabot ng task ang pangwakas na status, sa Unix milliseconds. null hanggang doon.
Name
expires_at
Type
timestamp
Description
Oras na mag-e-expire ang resulta ng task, sa Unix milliseconds. Ito ay 3 araw matapos ang finished_at, o 3 araw matapos ang 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 mamaya. Tingnan ang Asset retention.
Name
preceding_tasks
Type
integer
Description
Posisyon ng task sa queue habang ito ay PENDING. Ang 1 ay nangangahulugang susunod na itong magsisimula. 0 matapos umalis ng task sa queue, at palaging 0 sa mga resulta ng listahan.
Name
task_error
Type
object
Description
Dahilan 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 siningil para sa task, matapos ang 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, ang isang get o stream na tugon ay inaalis ang field, at ang isang list request ay nagbabalik ng 500. Sa ganitong pagkakataon, subukan muli ang request.
Name
image_urls
Type
array of strings
Description
Mga URL para sa pag-download ng pixel-art na imahe. Ang array ay may isang URL matapos magtagumpay ang task, at walang laman hanggang doon.
Ang mga URL ay naka-sign, kaya kunin ang mga ito nang walang Authorization header. Mananatili itong valid hanggang sa expires_at. Ang muling pagkuha sa task bago mangyari iyon ay nagbabalik ng parehong mga URL, hindi bagong naka-sign. Ang isang na-expire na URL ay hindi na mare-refresh, kaya i-download at itago ang mga file bago mangyari iyon.

Ang object ng build task ng Fidget Pixel

Ang isang build task ay bumubuo ng mga 3D-printable na piraso mula sa isang matagumpay na prototype task. Sine-sample ng Meshy ang pixel-art na imahe papunta sa grid at ibinabalik ang mga piraso sa iisang multi-color na 3MF file.

Mga Property

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?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-fidget-pixel-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: ginagawa ang resulta
- SUCCEEDED: huli na, mayroong resulta
- FAILED: huli na, nasa task_error ang dahilan
- CANCELED: huli na, walang resulta
Name
progress
Type
integer
Description
Porsyento ng natapos na gawain, mula 0 hanggang 100. Ito ay 0 hanggang hindi pa nagsisimula ang task at 100 kapag ito'y nagtagumpay.
Name
created_at
Type
timestamp
Description
Oras nang ginawa ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras nang sinimulan ng isang worker ang task, sa Unix milliseconds. null hanggang mangyari iyon.
Name
finished_at
Type
timestamp
Description
Oras nang umabot ang task sa huling status, sa Unix milliseconds. null hanggang mangyari iyon.
Name
expires_at
Type
timestamp
Description
Oras kung kailan 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 walang hanggang nagtatago ng mga resulta ng API, ito'y mga 100 taon pa mula ngayon. Tingnan ang Asset retention.
Name
preceding_tasks
Type
integer
Description
Ang posisyon ng task sa queue habang ito'y PENDING. Ang 1 ay nangangahulugang ito na ang susunod na magsisimula. 0 kapag umalis na 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, matapos ang 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'y PENDING. Kung hindi mabasa ng Meshy ang singil, hindi isinasama ng get o stream na tugon ang field na ito, at ang isang list request ay nagbabalik ng 500. Sa ganitong pagkakataon, subukan muli ang request.
Name
model_urls
Type
object
Description
Mga URL ng pag-download para sa resulta, naka-key ayon sa format ng file. Ang object ay may isang entry, para sa output.format na ipinadala mo, at ito'y walang laman hanggang magtagumpay ang task.
Ang mga URL ay naka-sign, kaya kunin ang mga ito nang walang Authorization header. Mananatili itong wasto hanggang sa expires_at. Ang pagkuha ulit ng task bago mangyari iyon ay nagbabalik ng parehong mga URL, hindi bagong naka-sign na mga ito. Ang isang URL na nag-expire na ay hindi na maaaring i-refresh, kaya i-download at itago ang mga file bago mangyari iyon.
- Name
  3mf
  Type
  string
  Description
  URL ng pag-download para sa multi-color na 3MF file. Ang bawat piraso ay may kulay-abong katawan at isang tuktok na kulay ng kaukulang pixel nito. Naroroon kapag ang output.format ay 3mf, na siyang default.

Halimbawang end-to-end

Ang mga sumusunod na cURL at Python na script ay nagpapatakbo ng buong flow. Ang bawat script ay gumagawa ng prototype task mula sa isang larawan at naghihintay para dito na magtagumpay. Pagkatapos, gumagawa ito ng build task, naghihintay para sa task na iyon, at nagda-download ng 3MF file mula sa model_urls.3mf.

Kailangan ng cURL script ang curl at jq, at kailangan ng Python script ang requests package. Upang patakbuhin ang isang script, sundin ang mga hakbang na ito:

Itakda ang MESHY_API_KEY sa iyong API key.
Itakda ang IMAGE_PATH sa path ng isang lokal na larawan, o ang IMAGE_URL sa isang pampublikong image URL.
Opsyonal: Upang i-pixelize ang isang subject na hindi tao, itakda ang PIXEL_TYPE sa other.
Patakbuhin ang script.

Karaniwang natatapos ang isang prototype task sa loob ng ilang minuto. Karaniwang natatapos ang isang build task sa mas mababa sa isang minuto.

Sa iyong app, ipakita ang larawan mula sa image_urls sa iyong user bago ka gumawa ng build task. Kung hindi nila ito magustuhan, gumawa na lang ng isa pang prototype task. Sa ganitong paraan, gumagastos ka lang ng build credits sa isang larawang aprubado nila.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/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://...
#   export PIXEL_TYPE=person                  # or: other
: "${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
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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 '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$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 pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"