API Creative Lab Fidget Pixel

Tukar foto kepada papan fidget seni piksel pelbagai warna yang boleh dicetak 3D dalam dua peringkat. Tugas prototaip menukar foto kepada imej seni piksel. Tugas binaan menukar imej itu kepada kepingan yang saling mengunci dalam satu fail 3MF, dan mengambil ID tugas prototaip sebagai 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 berbayar. Permintaan daripada akaun pelan percuma akan mengembalikan 402.

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

Create a Fidget Pixel prototype task

Menjana satu imej seni piksel daripada sebuah foto. Untuk membina kepingan-kepingan, hantar ID tugas ini kepada build endpoint sebagai input_task_id. Untuk medan-medan tugas ini, lihat The Fidget Pixel prototype task object.

Jika anda tidak berpuas hati dengan imej tersebut, cipta satu lagi tugas prototaip. Setiap tugas dikenakan caj secara berasingan.

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

Parameter

Name
image_url
Type
string
Diperlukan
Description
Foto yang hendak dijadikan seni piksel, sebagai URL awam atau data URI (data:image/jpeg;base64,<data imej anda yang dikodkan base64>).
Imej mestilah fail JPG, JPEG, PNG, atau WebP dengan saiz maksimum 20 MB. Meshy mengesan format daripada data imej, bukan daripada sambungan fail dalam URL. URL tanpa sambungan tetap berfungsi, dan Meshy mengikuti pengalihan semula (redirect).
Name
type
Type
string
Diperlukan
Description
Apa yang ditunjukkan oleh foto tersebut, yang menentukan gaya seni piksel. Kedua-dua gaya ini kelihatan jelas berbeza. Sebarang nilai lain mengembalikan 400.
Nilai yang tersedia:
- person: seseorang, dalam foto potret atau foto sepenuh badan. Meshy melukis sprite piksel bergaya chibi.
- other: sebarang subjek lain, contohnya haiwan peliharaan, objek, maskot, logo, atau landskap. Meshy melukis ikon piksel bergaya seni manik.
Name
name
Type
string
Description
Nama untuk tugas tersebut, sehingga 100 aksara. Nama ini dikembalikan dalam medan name tugas. Nama yang lebih panjang mengembalikan 400.

Returns

Medan result menyimpan ID tugas prototaip baharu. Dapatkan tugas atau strim tugas tersebut sehingga status menjadi SUCCEEDED. Kemudian hantar ID tersebut kepada build endpoint sebagai input_task_id.

Failure modes

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Contohnya:
- image_url atau type tiada.
- type bukan person atau other.
- Imej bukan fail JPG, JPEG, PNG, atau WebP.
- Imej terlalu kecil, melebihi 20 MB, atau melebihi bilangan piksel maksimum.
- Meshy tidak dapat memuat turun imej, contohnya kerana URL mengembalikan 404 atau tamat masa.
- Data URI bukan base64 yang sah.
- Imej ditandakan sebagai NSFW.
Mesej ralat menyatakan masalah yang ditemui. Betulkan permintaan, kemudian hantar semula.
Name
401 - Unauthorized
Description
Kunci API tiada atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Salah satu daripada perkara berikut berlaku:
- Akaun tidak mempunyai kredit yang mencukupi.
- Kunci API, ruang kerja, atau ahli telah mencapai had kreditnya.
- Akaun berada pada pelan percuma.
Semak kredit dan pelan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
Pasukan anda telah menghidupkan IP Filtering, dan Meshy menandakan imej tersebut berkaitan harta intelek pihak ketiga. Hantar imej yang anda mempunyai hak untuk digunakan.
Name
429 - Too Many Requests
Description
Salah satu had berikut telah dicapai:
- Anda menghantar lebih banyak permintaan daripada yang dibenarkan oleh had kadar anda. Tunggu beberapa saat, kemudian cuba semula. Lihat Rate limits.
- Terlalu banyak tugas anda sedang beratur atau sedang berjalan. Tunggu sehingga sebahagiannya selesai, kemudian cuba semula.
- Pada pelan tanpa had tanpa baki kredit, anda telah mencapai bilangan tugas yang boleh berjalan tanpa kredit. Tunggu satu tugas selesai, atau tambah kredit.
Name
500 - Internal Server Error
Description
Meshy mengalami ralat pelayan, contohnya kerana ia tidak dapat menjalankan pemeriksaan harta intelek ke atas imej tersebut. Meshy tidak mencipta tugas tersebut, dan memulangkan semula sebarang kredit yang telah dicaj. Cuba semula permintaan tersebut.

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

Cipta tugas pembinaan Fidget Pixel

Menjana kepingan boleh cetak 3D daripada tugas prototaip yang berjaya. Meshy mengambil sampel imej seni piksel ke atas grid dan mengurangkannya kepada paling banyak color_count warna. Setiap sel subjek menjadi kepingan yang saling berkunci, dan latar belakang tidak dicetak.

Hasilnya ialah satu fail 3MF berbilang warna, sedia untuk dicetak secara berwarna. Setiap kepingan mempunyai badan kelabu dan bahagian atas dalam warna piksel tersebut. Untuk medannya, lihat Objek tugas pembinaan Fidget Pixel.

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

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas prototaip untuk dibina. Ia mesti merupakan tugas yang dicipta oleh akaun anda dengan POST /openapi/creative-lab/fidget-pixel/v1/prototype, dengan status SUCCEEDED.
ID yang bukan salah satu tugas prototaip Fidget Pixel anda daripada API mengembalikan 404, termasuk prototaip yang dibuat dalam aplikasi web.
Name
name
Type
string
Description
Nama untuk tugas, sehingga 100 aksara. Ia dikembalikan dalam medan name tugas tersebut. Nama yang lebih panjang mengembalikan 400.

`options`

Tetapan untuk bentuk dan saiz kepingan. Setiap medan mempunyai nilai lalai, jadi hantar hanya medan yang ingin anda ubah. 0 menggunakan nilai lalai medan tersebut. Ini adalah tetapan yang sama seperti dalam aplikasi web Creative Lab. Tetapan bentuk lain adalah tetap, dan Meshy menetapkannya daripada shape dan piece_size_mm.

Name
shape
Type
string
lalai square
Description
Bentuk tapak bagi setiap kepingan. Sebarang nilai lain mengembalikan 400.
Nilai yang tersedia:
- square: kepingan segi empat sama pada grid segi empat sama
- hex: kepingan heksagon pada grid heksagon, dengan piece_size_mm ditetapkan kepada 6 atau 8
Name
grid_size
Type
integer
lalai 32
Description
Bilangan sel grid di sepanjang setiap sisi papan, 16 atau 32. Sebarang nilai lain mengembalikan 400. Grid 32 mengekalkan lebih banyak perincian. Grid 16 memberikan kepingan yang lebih sedikit dengan saiz yang sama, jadi papan menjadi kira-kira separuh lebarnya.
Name
piece_size_mm
Type
integer
lalai 8
Description
Panjang tepi setiap kepingan dalam milimeter, 6, 8, atau 10. Sebarang nilai lain mengembalikan 400. Bersama grid_size, ia menetapkan saiz papan yang dicetak. Sebagai contoh, grid 32 bagi kepingan 8 mm adalah kira-kira 26.5 cm setiap sisi.
10 tidak berfungsi dengan hex dan mengembalikan 400, kerana permukaan heksagon yang condong melampaui pada kebanyakan pencetak FDM pengguna.
Name
color_count
Type
integer
lalai 8
Description
Bilangan maksimum warna dalam palet seni piksel, dari 1 hingga 8. Nilai di luar julat mengembalikan 400. Untuk mencetak, anda memerlukan sehingga color_count tambah satu filamen, satu untuk setiap warna dan satu untuk badan kelabu.
Name
piece_height_mm
Type
integer
lalai 15
Description
Ketinggian setiap kepingan dalam milimeter, dari 10 hingga 80. Nilai di luar julat mengembalikan 400.

`output`

Tetapan untuk fail hasil.

Name
format
Type
string
lalai 3mf
Description
Format fail hasil. Sebarang nilai lain mengembalikan 400.
Nilai yang tersedia:
- 3mf: satu fail model.3mf berbilang warna, dikembalikan dalam model_urls.3mf

Pulangan

Medan result menyimpan ID tugas pembinaan baharu. Dapatkan tugas atau strim ia sehingga status adalah SUCCEEDED. Kemudian muat turun fail 3MF daripada model_urls.3mf.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Sebagai contoh:
- input_task_id hilang atau bukan ID tugas yang sah.
- Status tugas prototaip bukan SUCCEEDED. Jika masih berjalan, tunggu dan cuba semula. Jika ia gagal atau dibatalkan, cipta tugas prototaip baharu.
- Tugas prototaip berjaya tetapi tiada imej. Cipta tugas prototaip baharu.
- Medan options berada di luar nilai yang dibenarkan, sebagai contoh grid_size selain 16 atau 32.
- piece_size_mm adalah 10 dan shape adalah hex. Kepingan heksagon hanya terdapat dalam 6 dan 8 mm.
- output.format bukan 3mf.
Mesej ralat menyatakan masalah yang ditemuinya.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Salah satu daripada berikut berlaku:
- Akaun tidak mempunyai kredit yang mencukupi.
- Kunci API, ruang kerja, atau ahli telah mencapai had kreditnya.
- Akaun berada pada pelan percuma.
Semak kredit dan pelan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
Pasukan anda telah mengaktifkan IP Filtering, dan Meshy menandakan imej tugas prototaip untuk harta intelek pihak ketiga. Cipta tugas prototaip daripada imej yang anda mempunyai hak untuk menggunakannya.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugas prototaip Fidget Pixel yang dicipta oleh akaun anda dengan API. Prototaip yang dibuat dalam aplikasi web juga mengembalikan 404. Hantar ID result daripada respons penciptaan prototaip.
Name
429 - Too Many Requests
Description
Salah satu had ini telah dicapai:
- Anda menghantar lebih banyak permintaan daripada yang dibenarkan oleh had kadar anda. Tunggu beberapa saat, kemudian cuba semula. Lihat Had kadar.
- Terlalu banyak tugas anda sedang dalam baris gilir atau sedang berjalan. Tunggu sehingga sebahagiannya selesai, kemudian cuba semula.
- Pada pelan tanpa had tanpa kredit yang tinggal, anda telah mencapai bilangan tugas yang boleh berjalan tanpa kredit. Tunggu sehingga satu tugas selesai, atau tambah kredit.
Name
500 - Internal Server Error
Description
Meshy mengalami ralat pelayan, sebagai contoh kerana ia tidak dapat menjalankan semakan harta intelek pada imej tugas prototaip. Meshy tidak mencipta tugas tersebut, dan memulangkan semula sebarang kredit yang telah dicaj. Cuba semula permintaan tersebut.

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

Dapatkan tugas Fidget Pixel

Mengembalikan tugas prototaip atau build. Laluan mesti sepadan dengan peringkat tugas tersebut. Tugas build yang diminta melalui /prototype/:id akan mengembalikan 404, begitu juga tugas prototaip yang diminta melalui /build/:id.

Untuk medan-medannya, lihat Objek tugas prototaip Fidget Pixel dan Objek tugas build Fidget Pixel.

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

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Hasil Kembalian

Objek tugas prototaip atau objek tugas build, bergantung kepada peringkat dalam laluan.

Mod kegagalan

Name
400 - Bad Request
Description
id bukan ID tugas yang sah. Hantar ID result daripada respons create.
Name
403 - Forbidden
Description
Pasukan anda telah mengaktifkan IP Filtering, dan Meshy menandakan imej tugas prototaip tersebut kerana hak harta intelek pihak ketiga. Tugas build dan pasukan pada pelan Enterprise tidak akan menerima ralat ini. Cipta tugas prototaip daripada imej yang anda mempunyai hak untuk digunakan.
Name
404 - Not Found
Description
Tiada tugas Fidget Pixel dengan ID ini yang dimiliki oleh akaun anda, atau peringkat tugas tersebut tidak sepadan dengan laluan. Semak ID tersebut, dan gunakan /prototype atau /build untuk menyepadankan tugas.
Name
500 - Internal Server Error
Description
Meshy tidak dapat menjalankan semakan harta intelek. Cuba semula permintaan tersebut.

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

Padam tugas Fidget Pixel

Membatalkan tugas Fidget Pixel. Membatalkan tugas PENDING akan memulangkan kreditnya. Tugas IN_PROGRESS dibatalkan tanpa bayaran balik, kerana pekerja sudah memulakannya. Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak boleh dibatalkan.

Laluan mesti sepadan dengan peringkat tugas tersebut. Sebagai contoh, DELETE pada /prototype/:id dengan ID tugas build akan mengembalikan 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).

Parameter laluan

Name
id
Type
path
Description
ID tugas yang hendak dibatalkan.

Nilai pulangan

204 No Content dengan badan kosong.

Mod kegagalan

Name
400 - Bad Request
Description
Salah satu daripada berikut berlaku:
- id bukan ID tugas yang sah. Hantar ID result daripada respons penciptaan.
- Tugas sudah mempunyai status akhir (SUCCEEDED, FAILED, atau CANCELED), jadi ia tidak boleh dibatalkan.
Name
404 - Not Found
Description
Tiada tugas Fidget Pixel dengan ID ini yang dimiliki oleh akaun anda, atau peringkat tugas tidak sepadan dengan laluan tersebut. Semak ID tersebut, dan gunakan /prototype atau /build untuk menyepadankan tugas tersebut.

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

Alirkan tugas Fidget Pixel

Mengalirkan kemas kini tugas Fidget Pixel sebagai Server-Sent Events (SSE). Laluan tersebut mesti sepadan dengan peringkat tugas. Jika tidak, contohnya ID tugas build pada /prototype/:id/stream, aliran tersebut menghantar satu peristiwa error dengan status_code: 404 dan ditutup. Satu id yang bukan ID tugas yang sah akan berbuat perkara yang sama dengan 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=***"
  }
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Pulangan

Satu aliran objek tugas prototype atau build. Setiap peristiwa mengandungi objek tugas yang lengkap, seperti yang dipulangkan oleh Dapatkan tugas Fidget Pixel. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan outputnya masih kosong (null, [], atau {}), dan finished_at adalah null.

Jika IP Filtering menyekat hasil tugas, aliran tersebut akan menghantar satu peristiwa error sebagai gantinya, dengan status_code yang sama seperti yang akan dipulangkan oleh permintaan get.

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

Senaraikan tugasan Fidget Pixel

Mengembalikan tugasan Fidget Pixel anda bagi satu peringkat, satu halaman pada satu masa. Laluan tersebut memilih peringkat. /prototype hanya mengembalikan tugasan prototaip, dan /build hanya mengembalikan tugasan pembinaan.

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

Parameter laluan

Name
stage
Type
path
Diperlukan
Description
Peringkat yang hendak disenaraikan, prototype atau build.

Parameter pertanyaan

Name
page_num
Type
integer
lalai 1
Description
Halaman yang hendak dikembalikan, dari 1 hingga 255. 0 mengembalikan halaman pertama. Nilai di luar 0 hingga 255 akan mengembalikan 400.
Name
page_size
Type
integer
lalai 10
Description
Bilangan tugasan setiap halaman, sehingga 100. Nilai dari 101 hingga 255 mengembalikan 100 tugasan, dan 0 menggunakan nilai lalai. Nilai di luar 0 hingga 255 akan mengembalikan 400.
Name
sort_by
Type
string
lalai -created_at
Description
Susunan isihan.
Nilai yang tersedia:
- -created_at: terbaharu dahulu
- +created_at: terlama dahulu

Nilai pulangan

Satu array bagi objek tugasan prototaip atau objek tugasan pembinaan, mengikut peringkat yang dinyatakan dalam laluan.

Objek tugas prototaip Fidget Pixel

Tugas prototaip menukar foto kepada imej seni piksel. Untuk menukar imej itu kepada kepingan yang boleh dicetak 3D, hantar ID tugas ke build endpoint sebagai input_task_id.

Ciri-ciri

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
ID tugas. Jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa creative-lab-fidget-pixel-prototype.
Name
name
Type
string
Description
name yang anda hantar semasa mencipta tugas, atau "" jika anda tidak menghantarnya.
Name
status
Type
string
Description
Status tugas.
Nilai yang tersedia:
- PENDING: menunggu dalam baris gilir
- IN_PROGRESS: menjana hasil
- SUCCEEDED: muktamad, dengan hasil
- FAILED: muktamad, dengan sebab dalam task_error
- CANCELED: muktamad, tanpa hasil
Name
progress
Type
integer
Description
Peratusan kerja yang telah selesai, dari 0 hingga 100. Nilainya 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa seorang pekerja memulakan tugas, dalam milisaat Unix. null sehingga itu.
Name
finished_at
Type
timestamp
Description
Masa tugas mencapai status muktamad, dalam milisaat Unix. null sehingga itu.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix. Ia adalah 3 hari selepas finished_at, atau 3 hari selepas created_at sehingga tugas selesai. Bagi akaun Enterprise, yang menyimpan hasil API tanpa had masa, ia kira-kira 100 tahun kemudian. Lihat Pengekalan aset.
Name
preceding_tasks
Type
integer
Description
Kedudukan tugas dalam baris gilir semasa ia PENDING. 1 bermaksud ia akan bermula seterusnya. 0 selepas tugas keluar dari baris gilir, dan sentiasa 0 dalam hasil senarai.
Name
task_error
Type
object
Description
Sebab tugas gagal. null kecuali status adalah FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang dikenakan untuk tugas, selepas sebarang bayaran balik. Permintaan yang mengembalikan ralat tidak dikenakan caj. Tugas yang gagal adalah 0, kerana Meshy membayar baliknya. Membatalkan hanya membayar balik tugas semasa ia PENDING. Jika Meshy tidak dapat membaca caj tersebut, respons get atau stream akan mengecualikan medan ini, dan permintaan senarai akan mengembalikan 500. Dalam kes itu, cuba semula permintaan tersebut.
Name
image_urls
Type
array of strings
Description
URL muat turun untuk imej seni piksel. Tatasusunan ini mempunyai satu URL selepas tugas berjaya, dan kosong sehingga itu.
URL tersebut ditandatangani, jadi ambil ia tanpa header Authorization. Ia kekal sah sehingga expires_at. Mendapatkan semula tugas sebelum itu mengembalikan URL yang sama, bukan yang baru ditandatangani. URL yang telah tamat tempoh tidak boleh disegarkan semula, jadi muat turun dan simpan fail sebelum itu.

Objek tugas binaan Fidget Pixel

Tugas binaan menjana kepingan yang boleh dicetak dalam 3D daripada tugas prototaip yang berjaya. Meshy mencontohi imej seni piksel ke atas grid dan mengembalikan kepingan tersebut dalam satu fail 3MF berbilang warna.

Ciri-ciri

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
ID tugas. Jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
name yang anda hantar semasa mencipta tugas, atau "" jika anda tidak menghantarnya.
Name
status
Type
string
Description
Status tugas.
Nilai yang tersedia:
- PENDING: menunggu dalam baris gilir
- IN_PROGRESS: menjana hasil
- SUCCEEDED: muktamad, dengan hasil
- FAILED: muktamad, dengan sebab dalam task_error
- CANCELED: muktamad, tanpa hasil
Name
progress
Type
integer
Description
Peratusan kerja yang telah selesai, dari 0 hingga 100. Nilainya 0 sehingga tugas bermula dan 100 apabila berjaya.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa seorang pekerja memulakan tugas, dalam milisaat Unix. null sehingga ketika itu.
Name
finished_at
Type
timestamp
Description
Masa tugas mencapai status muktamad, dalam milisaat Unix. null sehingga ketika itu.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix. Ia adalah 3 hari selepas finished_at, atau 3 hari selepas created_at sehingga tugas selesai. Bagi akaun Enterprise, yang menyimpan hasil API tanpa had masa, ia adalah lebih kurang 100 tahun kemudian. Lihat Pengekalan aset.
Name
preceding_tasks
Type
integer
Description
Kedudukan tugas dalam baris gilir semasa ia PENDING. 1 bermaksud ia akan bermula seterusnya. 0 selepas tugas keluar dari baris gilir, dan sentiasa 0 dalam hasil senarai.
Name
task_error
Type
object
Description
Sebab tugas gagal. null kecuali status adalah FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang dicaj untuk tugas, selepas sebarang bayaran balik. Permintaan yang mengembalikan ralat tidak dicaj. Tugas yang gagal adalah 0, kerana Meshy membayar balik kreditnya. Membatalkan hanya membayar balik tugas semasa ia PENDING. Jika Meshy tidak dapat membaca caj tersebut, respons get atau stream tidak akan menyertakan medan ini, dan permintaan senarai akan mengembalikan 500. Dalam kes itu, cuba semula permintaan tersebut.
Name
model_urls
Type
object
Description
URL muat turun untuk hasil, dikunci mengikut format fail. Objek ini mempunyai satu entri, untuk output.format yang anda hantar, dan kosong sehingga tugas berjaya.
URL ini ditandatangani, jadi ambil fail tersebut tanpa header Authorization. URL ini kekal sah sehingga expires_at. Mendapatkan semula tugas sebelum itu akan mengembalikan URL yang sama, bukan yang baru ditandatangani. URL yang telah tamat tempoh tidak boleh disegarkan semula, jadi muat turun dan simpan fail tersebut sebelum itu.
- Name
  3mf
  Type
  string
  Description
  URL muat turun untuk fail 3MF berbilang warna. Setiap kepingan mempunyai badan kelabu dan bahagian atas dengan warna piksel masing-masing. Hadir apabila output.format ialah 3mf, iaitu lalai.

Contoh hujung ke hujung

Skrip cURL dan Python berikut menjalankan keseluruhan aliran. Setiap skrip mencipta tugas prototaip daripada sebuah foto dan menunggu sehingga ia berjaya. Kemudian ia mencipta tugas build, menunggu tugas tersebut, dan memuat turun fail 3MF daripada model_urls.3mf.

Skrip cURL memerlukan curl dan jq, dan skrip Python memerlukan pakej requests. Untuk menjalankan skrip, ikuti langkah-langkah berikut:

Tetapkan MESHY_API_KEY kepada kunci API anda.
Tetapkan IMAGE_PATH kepada laluan foto tempatan, atau IMAGE_URL kepada URL imej awam.
Pilihan: Untuk mempiksel subjek selain daripada manusia, tetapkan PIXEL_TYPE kepada other.
Jalankan skrip.

Tugas prototaip biasanya selesai dalam beberapa minit. Tugas build biasanya selesai dalam masa kurang seminit.

Dalam aplikasi anda, tunjukkan imej daripada image_urls kepada pengguna anda sebelum anda mencipta tugas build. Jika mereka tidak menyukainya, cipta satu lagi tugas prototaip sebaliknya. Dengan cara ini, anda hanya membelanjakan kredit build untuk imej yang mereka luluskan.

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"