Creative Lab — API Fidget Pixel

Tukar foto sumber kepada papan fidget seni piksel pelbagai warna yang boleh dicetak dalam 3D melalui dua peringkat: prototaip mempikselkan foto anda menjadi imej seni piksel, kemudian binaan mensampel imej tersebut ke atas grid 16×16 atau 32×32 dan menukar setiap piksel menjadi kepingan segi empat atau heksagon yang saling berkunci, dihantar sebagai satu 3MF yang objeknya membawa warna masing-masing supaya slicer pelbagai filamen mencetak setiap kepingan dalam warna yang betul. Kedua-dua peringkat dihubungkan melalui input_task_id.

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

Kedua-dua endpoint POST memerlukan pelan langganan berbayar. Permintaan daripada akaun pelan percuma akan ditolak dengan 402 Payment Required.

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

Cipta Tugas Prototaip Fidget Pixel

Jana satu imej seni piksel (pixel-art) daripada foto sumber. ID tugas yang dikembalikan adalah nilai yang anda hantar sebagai input_task_id kepada endpoint build. Panggil endpoint ini sekali lagi untuk cubaan lain jika hasilnya tidak seperti yang anda mahukan — setiap panggilan dikenakan bayaran secara berasingan. Rujuk The Fidget Pixel Prototype Task Object untuk bentuk respons.

Parameter

Name
image_url
Type
string
Diperlukan
Description
Foto sumber untuk Meshy menukarkannya kepada piksel. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.
Format dikesan dengan menyahkod data imej, bukan daripada sambungan fail URL — URL tanpa sambungan, atau yang melakukan pengalihan (redirect), tetap berfungsi selagi bait tersebut boleh dinyahkod kepada format yang disokong. Pengalihan HTTP akan diikuti.
Terdapat dua cara untuk menyediakan imej:
- URL yang boleh diakses secara umum: URL yang boleh diakses daripada internet awam.
- Data URI: Data URI imej yang dikodkan base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
type
Type
string
Diperlukan
Description
Apa yang ditunjukkan oleh foto tersebut. Ini memilih gaya pemikselan, jadi pilihlah dengan teliti — kedua-dua pilihan menghasilkan keputusan yang jelas berbeza. Nilai yang tersedia:
- person — subjek adalah seorang manusia (potret atau seluruh badan). Menghasilkan sprite piksel bergaya chibi bagi subjek tersebut.
- other — apa-apa selain itu: haiwan peliharaan, objek, maskot, logo, landskap. Menghasilkan ikon piksel bergaya seni manik (bead-art) bagi subjek tersebut.
Name
name
Type
string
Description
Nama tugas pilihan untuk tujuan paparan. Maksimum 100 aksara.

Nilai Kembalian

Sifat result dalam respons mengandungi id tugas bagi tugas prototaip fidget pixel yang baru dicipta. Poll endpoint Get a Task atau langgan stream sehingga tugas mencapai status SUCCEEDED, kemudian hantar ID tersebut kepada endpoint build sebagai input_task_id.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter tiada: image_url dan type kedua-duanya diperlukan.
- Type tidak sah: type mestilah person atau other.
- Format imej tidak sah: image_url yang diberikan bukan format yang disokong (.jpg, .jpeg, .png, .webp).
- Dimensi imej di luar julat: Imej terlalu kecil, melebihi saiz fail maksimum, atau melebihi bilangan piksel maksimum.
- URL tidak dapat dicapai: image_url tidak dapat dimuat turun (404 atau timeout).
- Data URI tidak sah: Rentetan base64 tidak berbentuk betul.
- Kandungan ditanda: Imej input ditanda oleh moderation NSFW.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini, atau kunci API tersebut dimiliki oleh akaun pelan percuma.
Name
403 - Forbidden
Description
Imej input ditanda oleh moderation harta intelek (Content flagged for intellectual property violation). Hanya akaun Enterprise dengan penapisan harta intelek diaktifkan yang disekat; tiada caj dikenakan.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.
Name
500 - Internal Server Error
Description
Semakan harta intelek itu sendiri tidak dapat diselesaikan (Unable to perform intellectual property check, please try again). Akaun Enterprise dengan penapisan harta intelek diaktifkan akan gagal secara tertutup (fail closed) pada semakan ini; tiada caj dikenakan — cuba semula permintaan tersebut.

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

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

Cipta Tugas Build Fidget Pixel

Jana kepingan yang boleh dicetak dalam 3D daripada tugas prototaip yang berjaya. Build ini mengambil sampel imej pixel-art prototaip ke atas grid yang diminta, mengkuantumkannya kepada sekurang-kurangnya color_count warna, dan menjana satu kepingan berselirat bagi setiap sel grid. Hasil akhirnya ialah satu fail 3MF di mana setiap kepingan adalah objek berasingan yang ditandakan dengan warnanya, sedia untuk slicer berbilang filamen. Rujuk Objek Tugas Build Fidget Pixel untuk bentuk respons.

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas bagi tugas prototaip yang dicipta melalui endpoint OpenAPI yang sama. Prototaip mesti dicipta oleh akaun Meshy yang sama dan mesti telah mencapai SUCCEEDED.
Tugas prototaip yang dicipta melalui webapp tidak diterima — endpoint build hanya menerima tugas prototaip yang dihasilkan oleh POST /openapi/creative-lab/fidget-pixel/v1/prototype dan menolak mana-mana sumber lain dengan 404.
Name
name
Type
string
Description
Nama tugas pilihan untuk tujuan paparan. Maksimum 100 aksara.

`options`

Geometri kepingan pilihan. Setiap medan mempunyai nilai lalai — hantar hanya yang anda mahu gantikan. Ini adalah kawalan yang sama yang didedahkan oleh webapp Creative Lab; ketinggian plug, skala penutup, dan prasetel pembuatan lain diperoleh daripada shape dan piece_size_mm dan tidak didedahkan.

Name
shape
Type
string
lalai square
Description
Bentuk tapak setiap kepingan. Nilai yang tersedia:
- square (lalai) — kepingan segi empat sama pada grid segi empat sama.
- hex — kepingan heksagon pada grid heksagon. Kepingan hex tersedia dalam saiz 6 dan 8 mm sahaja.
Name
grid_size
Type
integer
lalai 32
Description
Bilangan kepingan sepanjang setiap sisi papan. Nilai yang tersedia: 16 atau 32. Grid 32 mengekalkan lebih banyak perincian; grid 16 bermakna kepingan yang lebih sedikit dan lebih besar bagi subjek yang sama.
Name
piece_size_mm
Type
integer
lalai 8
Description
Panjang tepi setiap kepingan, dalam milimeter. Nilai yang tersedia: 6, 8, atau 10. Bersama-sama dengan grid_size ini menetapkan saiz papan yang dicetak — contohnya 32 × 8 mm ≈ 26 cm setiap sisi. 10 tidak tersedia untuk shape: "hex" (permukaan hex yang condong menyebabkan overhang pada kebanyakan pencetak FDM pengguna).
Name
color_count
Type
integer
lalai 8
Description
Bilangan maksimum warna dalam palet yang imej dikuantumkan kepadanya. Julat: [1, 8]. Setiap warna menjadi satu filamen dalam slicer anda.
Name
piece_height_mm
Type
integer
lalai 15
Description
Ketinggian setiap kepingan, dalam milimeter. Julat: [10, 80].

`output`

Pemilih format wayar pilihan. Lalai kepada 3mf, yang buat masa ini merupakan satu-satunya nilai yang disokong.

Name
format
Type
string
lalai 3mf
Description
Artifak yang dikembalikan oleh build. Nilai yang tersedia:
- 3mf (lalai) — mengembalikan satu model.3mf di bawah model_urls.3mf, dengan satu objek bagi setiap kepingan dan warna kepingan dilampirkan pada setiap objek.

Pulangan

Sifat result bagi respons mengandungi id tugas bagi tugas build fidget pixel yang baru dicipta. Poll endpoint Dapatkan Tugas atau langgan strim sehingga tugas mencapai SUCCEEDED, kemudian muat turun artifak daripada model_urls.3mf.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter hilang: input_task_id diperlukan.
- UUID tidak sah: input_task_id bukan UUID yang sah.
- Induk tidak berjaya: Tugas prototaip yang dirujuk belum lagi mencapai SUCCEEDED.
- Tiada calon: Tugas prototaip berjaya tetapi tidak menghasilkan imej pixel-art; cipta prototaip baharu.
- Pilihan di luar julat: Salah satu medan options berada di luar set atau julat yang dibenarkan — contohnya options.grid_size must be 16 or 32, atau options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
- Format tidak disokong: output.format mesti 3mf.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini, atau kunci API tergolong pada akaun pelan percuma.
Name
403 - Forbidden
Description
Imej prototaip yang dirujuk telah ditandakan oleh moderation harta intelek. Hanya akaun Enterprise dengan penapisan harta intelek diaktifkan yang disekat; tiada caj dikenakan.
Name
404 - Not Found
Description
Tugas prototaip yang dirujuk tidak wujud, tergolong pada pengguna lain, atau dicipta melalui webapp (hanya tugas prototaip mod API yang boleh dirantai ke dalam build).
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.
Name
500 - Internal Server Error
Description
Keputusan harta intelek bagi prototaip yang dirujuk tidak dapat ditentukan (Unable to perform intellectual property check, please try again). Akaun Enterprise dengan penapisan harta intelek diaktifkan akan gagal secara tertutup pada semakan ini; tiada caj dikenakan — cuba semula permintaan tersebut.

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

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

Retrieve a Fidget Pixel Task

Dapatkan semula tugas prototype atau build dengan id tugas yang sah. Laluan URL mesti sepadan dengan peringkat tugas — tugas build yang diambil melalui /prototype/:id akan memulangkan 404, dan begitu juga sebaliknya.

Rujuk The Fidget Pixel Prototype Task Object dan The Fidget Pixel Build Task Object untuk bentuk respons.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas fidget pixel yang hendak diambil.

Pemulangan

Respons mengandungi objek tugas fidget pixel. Bentuknya bergantung pada peringkat mana yang diminta.

Mod Kegagalan

Name
400 - Bad Request
Description
id bukan UUID yang sah (Invalid ID).
Name
403 - Forbidden
Description
Imej tugas telah ditanda oleh moderation harta intelek. Hanya akaun Enterprise dengan penapisan harta intelek yang diaktifkan akan disekat.
Name
404 - Not Found
Description
Tugas tidak wujud, dimiliki oleh pengguna lain, atau peringkatnya tidak sepadan dengan laluan URL.
Name
500 - Internal Server Error
Description
Pemeriksaan harta intelek tidak dapat diselesaikan (Unable to perform intellectual property check, please try again); akaun Enterprise dengan penapisan harta intelek yang diaktifkan akan gagal secara tertutup. Cuba semula permintaan tersebut.

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

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

Padam Tugasan Fidget Pixel

Batalkan tugasan fidget pixel. Jika tugasan masih PENDING, kredit yang digunakan pada masa penciptaan akan dikembalikan. Tugasan yang sudah IN_PROGRESS akan dibatalkan tanpa bayaran balik (pekerja mungkin sudah menggunakan sumber). Tugasan yang telah mencapai keadaan akhir (SUCCEEDED, FAILED, CANCELED) tidak boleh dibatalkan.

Laluan URL mesti sepadan dengan peringkat tugasan tersebut — DELETE pada /prototype/:buildId mengembalikan 404.

Parameter Laluan

Name
id
Type
path
Description
Pengenal unik untuk tugasan fidget pixel yang hendak dibatalkan.

Pulangan

Mengembalikan 204 No Content apabila berjaya dengan badan yang kosong.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- ID tidak sah: id bukan UUID yang sah.
- Keadaan akhir: Tugasan sudah SUCCEEDED, FAILED atau CANCELED dan tidak boleh dibatalkan.
Name
404 - Not Found
Description
Tugasan tidak wujud, kepunyaan pengguna lain, atau peringkatnya tidak sepadan dengan laluan URL.

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

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

Strim Tugas Fidget Pixel

Strim kemas kini masa nyata untuk tugas fidget pixel melalui Server-Sent Events (SSE). Laluan URL mesti sepadan dengan peringkat tugas — membuka strim di /prototype/:buildId/stream akan menghasilkan satu event: error payload dengan status_code: 404 dan menutup strim; id yang tidak sah melakukan perkara yang sama dengan status_code: 400 (Invalid ID).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas fidget pixel yang hendak distrim.

Pemulangan

Mengembalikan strim objek tugas Fidget Pixel Prototype atau Fidget Pixel Build sebagai Server-Sent Events. Setiap bingkai membawa objek tugas penuh untuk peringkat tersebut — bentuk yang sama yang dikembalikan oleh endpoint Get — jadi semasa tugas berstatus PENDING atau IN_PROGRESS, medan output hanya belum diisi lagi (null, [] atau {}) dan finished_at adalah null.

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

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

Senaraikan Tugas Fidget Pixel

Dapatkan senarai tugas fidget pixel anda yang dinomborkan halaman untuk satu peringkat. Laluan URL memilih peringkat tersebut — /prototype mengembalikan tugas prototaip; /build mengembalikan tugas pembinaan. Tugas daripada peringkat yang lain tidak disertakan dalam mana-mana respons.

Parameter Laluan

Name
stage
Type
path
Diperlukan
Description
Sama ada prototype atau build. Koleksi ini hanya mengembalikan tugas yang peringkatnya sepadan dengan URL — mendapatkan /prototype tidak akan sesekali mengembalikan tugas pembinaan dan begitu juga sebaliknya.

Parameter Pertanyaan

Name
page_num
Type
integer
lalai 1
Description
Nombor halaman untuk penomboran halaman.
Name
page_size
Type
integer
lalai 10
Description
Had saiz halaman. Maksimum yang dibenarkan ialah 100 item.
Name
sort_by
Type
string
lalai -created_at
Description
Medan untuk diisih. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan secara menaik.
- -created_at: Isih mengikut masa penciptaan secara menurun.

Pemulangan

Mengembalikan senarai objek tugas mengikut peringkat yang dinomborkan halaman — sama ada objek tugas prototaip fidget pixel apabila menyenaraikan /prototype atau objek tugas pembinaan fidget pixel apabila menyenaraikan /build.

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

Objek Tugas Prototaip Fidget Pixel

Objek Tugas Prototaip Fidget Pixel ialah unit kerja yang dijejaki oleh Meshy untuk mempixelkan foto sumber menjadi imej seni piksel. Output peringkat ini dirantaikan ke peringkat pembinaan melalui input_task_id.

Properties

Name
id
Type
string
Description
Pengecam unik untuk tugas. Walaupun kami menggunakan UUID yang boleh disusun-k sebagai butiran pelaksanaan untuk id tugas, anda tidak patut membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas. Nilainya ialah creative-lab-fidget-pixel-prototype.
Name
name
Type
string
Description
Nama tugas yang diberikan semasa tugas dicipta. Rentetan kosong jika tiada nama diberikan.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum bermula lagi, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Cap masa apabila tugas dicipta, dalam milisaat.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
started_at
Type
timestamp
Description
Cap masa apabila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, sifat ini akan menjadi null.
Name
finished_at
Type
timestamp
Description
Cap masa apabila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi null.
Name
expires_at
Type
timestamp
Description
Cap masa apabila hasil tugas luput, dalam milisaat — 3 hari selepas tugas selesai. Akaun Enterprise mengekalkan hasil API secara berterusan (lihat Pengekalan Aset); bagi mereka, cap masa ini ditetapkan kira-kira 100 tahun ke hadapan.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Tugas yang mencapai SUCCEEDED dikenakan caj penuh untuk peringkatnya. Tugas yang tidak pernah dicipta (4xx semasa masa permintaan, termasuk penolakan moderation) tidak dikenakan caj langsung. Tugas yang mencapai FAILED mengembalikan 0 — caj tersebut dikembalikan semula. Membatalkan melalui DELETE hanya mengembalikan caj semasa tugas masih PENDING; tugas yang sudah IN_PROGRESS kekal dikenakan caj, kerana kerja tersebut telah dibelanjakan.
Name
image_urls
Type
array of strings
Description
URL yang boleh dimuat turun untuk imej seni piksel yang dijana oleh tugas prototaip ini. Buat masa ini API sentiasa mengembalikan tepat satu imej; medan ini berbentuk array supaya semakan masa hadapan boleh memaparkan pelbagai calon tanpa perubahan yang memecahkan keserasian. Kosong sehingga tugas mencapai SUCCEEDED.
Ini ialah URL yang ditandatangani: dapatkannya tanpa header Authorization. Ia kekal sah sehingga expires_at, iaitu 3 hari selepas finished_at, dan membaca semula tugas dalam tempoh tersebut mengembalikan URL yang sama persis dan bukannya URL yang baru ditandatangani. Muat turun dan simpan fail tersebut sendiri sebelum itu — tiada cara untuk menyegarkan semula pautan yang telah luput.

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

Objek Tugas Binaan Fidget Pixel

Objek Tugas Binaan Fidget Pixel ialah unit kerja yang dijejaki oleh Meshy untuk menghasilkan kepingan boleh cetak daripada tugas prototaip yang berjaya. Binaan ini mengambil sampel imej seni piksel prototaip ke atas grid yang diminta dan menerbitkan satu 3MF bertanda warna.

Ciri-ciri

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut.
Name
type
Type
string
Description
Jenis tugas. Nilainya ialah creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
Nama tugas yang diberikan semasa tugas dicipta. Rentetan kosong jika tiada nama diberikan.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas tersebut. Jika tugas belum bermula lagi, ciri ini akan bernilai 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas dicipta, dalam milisaat.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas dimulakan, dalam milisaat. null sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas selesai, dalam milisaat. null sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Cap masa bila hasil tugas tamat tempoh, dalam milisaat — 3 hari selepas tugas selesai. Akaun Enterprise menyimpan hasil API secara berterusan (lihat Pengekalan Aset); bagi mereka, cap masa ini ditetapkan kira-kira 100 tahun kemudian.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu. Hanya bermakna apabila status ialah PENDING.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Tugas yang mencapai SUCCEEDED akan dikenakan caj penuh untuk peringkatnya. Tugas yang tidak pernah dicipta (4xx semasa permintaan, termasuk penolakan moderation) tidak dikenakan caj langsung. Tugas yang mencapai FAILED memulangkan 0 — caj tersebut dikembalikan. Membatalkan melalui DELETE hanya mengembalikan caj semasa tugas masih PENDING; tugas yang sudah IN_PROGRESS kekal dikenakan caj, kerana kerja telah dilaksanakan.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk artifak yang dihasilkan, mengikut kunci format. Mengandungi tepat satu entri — format yang diminta melalui output.format permintaan binaan. Kosong sehingga tugas mencapai SUCCEEDED.
Ini ialah URL yang ditandatangani: dapatkan URL ini tanpa pengepala Authorization. URL ini kekal sah sehingga expires_at, iaitu 3 hari selepas finished_at, dan membaca semula tugas dalam tempoh tersebut akan memulangkan URL yang sama, bukan URL yang baharu ditandatangani. Muat turun dan simpan fail tersebut sendiri sebelum tempoh itu tamat — tiada cara untuk memperbaharui pautan yang sudah tamat tempoh.
- Name
  3mf
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail 3MF. Satu objek bagi setiap kepingan, masing-masing ditanda dengan warna paletnya, supaya slicer berbilang filamen menetapkan filamen mengikut warna. Hadir apabila output.format ialah 3mf (lalai).

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

End-to-End Example

Aliran lengkap: cipta prototaip daripada foto, tinjau (poll) ia sehingga SUCCEEDED, cipta binaan (build) daripadanya, tinjau binaan itu sehingga SUCCEEDED, kemudian muat turun 3MF daripada model_urls.

Prototaip biasanya siap dalam beberapa minit; binaan biasanya selesai dalam masa kurang daripada seminit. Dalam integrasi sebenar, anda akan menunjukkan entri image_urls prototaip kepada pengguna akhir dan membiarkan mereka mengesahkan (atau menjalankan semula prototaip) sebelum membelanjakan kredit untuk binaan tersebut.

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"