lowpoly akan dihentikan pada 30 Okt 2026. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan. Lihat semua penamatan

Creative Lab Collapsible Fidget API

Tukarkan foto menjadi mainan fidget yang boleh dilipat dan dicetak-dalam-tempat dalam satu tugas sahaja. Siluet subjek akan menjadi gelang-gelang konsentrik bersarang yang boleh dikemas rata dan diregangkan semula. Mainan ini dicetak dalam satu keping, tanpa pemasangan.

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

Berbeza daripada endpoint Creative Lab yang lain, endpoint ini tidak mempunyai peringkat prototaip dan pembinaan yang berasingan. Tiada imej calon untuk dipilih, jadi satu tugas sahaja menukarkan foto tersebut menjadi model 3D.

Permintaan ini juga tidak mempunyai tetapan geometri. Aplikasi web membenarkan anda menetapkan saiz, bilangan lapisan, lebar jurang, ketebalan dinding, kedalaman ekstrusi, dan bonjolan. Setiap tugas API menggunakan nilai lalai yang sama untuk semua tetapan tersebut.

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

Cipta tugas Collapsible Fidget

Menjana model collapsible fidget daripada sebuah foto. Untuk medan-medan tugas ini, lihat The Collapsible Fidget task object.

Setiap tugas berharga 6 kredit dan memerlukan pelan berbayar.

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parameter

  • Name
    image_url
    Type
    string
    Diperlukan
    Description

    Foto yang hendak dijadikan collapsible fidget, dalam bentuk URL awam atau data URI (data:image/jpeg;base64,<data imej anda yang dikod dalam base64>).

    Imej mestilah fail JPG, JPEG, PNG, atau WebP yang bersaiz tidak lebih daripada 20 MB.

    Siluet subjek akan menjadi cincin-cincin, jadi subjek dengan satu garis luar yang jelas dan tertutup memberikan hasil terbaik. Latar belakang yang bercelaru, beberapa subjek berasingan, atau bentuk yang terlalu nipis boleh menyebabkan kawasan yang tinggal tidak mencukupi untuk dinding bersarang. Dalam keadaan itu, tugas akan gagal.

  • Name
    name
    Type
    string
    Description

    Nama untuk tugas tersebut, sehingga 100 aksara. Ia akan dipaparkan semula dalam medan name tugas, dan Meshy tidak mengukirnya pada model tersebut. Nama yang lebih panjang akan memulangkan 400.

Pulangan

Medan result menyimpan ID tugas baharu tersebut. Dapatkan tugas atau alirkannya sehingga status menjadi SUCCEEDED. Kemudian muat turun fail STL yang boleh dicetak daripada model_urls.stl. Untuk melihat pratonton model terlebih dahulu, muat turun fail GLB daripada model_urls.glb apabila ia tersedia.

Mod kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Sebagai contoh:

    • image_url tiada.
    • 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 tersebut, contohnya kerana URL memulangkan 404 atau tamat masa.
    • Data URI bukan base64 yang sah.
    • Imej telah ditanda sebagai NSFW.

    Mesej ralat menyatakan masalah yang dikesan. Betulkan permintaan tersebut, 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 kredit.
    • 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 tersebut berkaitan hak harta intelek pihak ketiga. Hantar imej yang anda mempunyai hak untuk menggunakannya.

  • 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 dijalankan tanpa kredit. Tunggu sehingga satu tugas selesai, atau tambah kredit.
  • Name
    500 - Internal Server Error
    Description

    Meshy mengalami ralat pelayan, contohnya kerana ia tidak dapat menjalankan semakan hak harta intelek pada imej tersebut. Meshy tidak mencipta tugas tersebut, dan memulangkan semula sebarang kredit yang telah dicaj. Cuba semula permintaan tersebut.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Dapatkan tugas Collapsible Fidget

Mengembalikan tugas Collapsible Fidget. Hanya tugas yang dicipta dengan endpoint ini yang dikembalikan. Tugas daripada endpoint Creative Lab yang lain, atau yang dicipta dalam aplikasi web, mengembalikan 404.

Untuk medan-medan, lihat Objek tugas Collapsible Fidget.

Request

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

Response

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas daripada respons create.

Nilai yang dikembalikan

Objek tugas Collapsible Fidget.

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 tersebut sebagai mengandungi harta intelek pihak ketiga. Pasukan pada pelan Enterprise tidak mendapat ralat ini. Cipta tugas daripada imej yang anda mempunyai hak untuk menggunakannya.

  • Name
    404 - Not Found
    Description

    Tiada tugas Collapsible Fidget dengan ID ini yang dimiliki oleh akaun anda, atau tugas tersebut tidak dicipta dengan endpoint ini. Semak ID tersebut.

  • Name
    500 - Internal Server Error
    Description

    Meshy tidak dapat menjalankan semakan harta intelek. Cuba semula permintaan tersebut.

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Padam tugas Collapsible Fidget

Membatalkan tugas Collapsible Fidget. Membatalkan tugas PENDING akan memulangkan kreditnya. Tugas IN_PROGRESS dibatalkan tanpa bayaran balik, kerana seorang pekerja telah pun memulakannya. Tugas yang mempunyai status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak boleh dibatalkan.

Request

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

Response

// Returns 204 No Content on success (empty body).

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 create.
    • Tugas sudah mempunyai status akhir (SUCCEEDED, FAILED, atau CANCELED), jadi ia tidak boleh dibatalkan.
  • Name
    404 - Not Found
    Description

    Tiada tugas Collapsible Fidget dengan ID ini yang dimiliki oleh akaun anda, atau tugas tersebut tidak dicipta menggunakan endpoint ini. Semak ID tersebut.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Alirkan Tugas Collapsible Fidget

Mengalirkan kemas kini tugas Collapsible Fidget sebagai Server-Sent Events (SSE). Jika tugas tersebut tidak wujud atau tidak dicipta melalui endpoint ini, aliran akan menghantar satu peristiwa error dengan status_code: 404 dan kemudian ditutup.

Request

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

Response Stream

// Error event example (task not found, or not created through this endpoint)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

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

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas daripada respons create.

Nilai Pulangan

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

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

Senaraikan tugas Collapsible Fidget

Mengembalikan tugas Collapsible Fidget anda, satu halaman pada satu masa. Hanya tugas yang dicipta menggunakan endpoint ini disertakan.

Request

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

Response

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

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 mengembalikan 400.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Bilangan tugas setiap halaman, sehingga 100. Nilai dari 101 hingga 255 mengembalikan 100 tugas, dan 0 menggunakan nilai lalai. Nilai di luar 0 hingga 255 mengembalikan 400.

  • Name
    sort_by
    Type
    string
    lalai -created_at
    Description

    Susunan pengisihan.

    Nilai yang tersedia:

    • -created_at: terbaharu dahulu
    • +created_at: terlama dahulu

Nilai kembali

Satu tatasusunan objek tugas Collapsible Fidget.

Objek tugas Collapsible Fidget

Tugas Collapsible Fidget menukar foto kepada model fidget collapsible yang boleh dicetak terus (print-in-place). Ia adalah tugas satu peringkat, jadi tiada tugas prototaip untuk dirangkaikan. Respons tidak termasuk siluet yang dihasilkan oleh Meshy sepanjang proses tersebut.

Properties

Example Collapsible Fidget Task Object

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

    ID tugas. Jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, sentiasa creative-lab-fidget-collapsible.

  • 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: sedang 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. Untuk 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 daripada 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 dicas untuk tugas, selepas sebarang bayaran balik. Permintaan yang mengembalikan ralat tidak dicas. 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 mengetepikan 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 model 3D, kosong sehingga tugas berjaya. Tugas yang berjaya sentiasa mempunyai stl, dan hanya mempunyai glb jika Meshy telah menghasilkan pratonton.

    • Name
      stl
      Type
      string
      Description

      URL muat turun untuk fail STL, iaitu fail yang akan dicetak. Anda boleh membukanya terus dalam slicer.

    • Name
      glb
      Type
      string
      Description

      URL muat turun untuk fail GLB bagi pratonton model dalam penonton 3D. Warnanya hanya untuk pratonton sahaja. Fail STL tiada warna, jadi fidget yang dicetak akan mengambil warnanya daripada filamen.

      Jika Meshy tidak dapat menghasilkan pratonton, model_urls tidak mempunyai kunci glb, jadi semak kewujudan kunci tersebut sebelum anda membacanya. Tugas SUCCEEDED sentiasa mempunyai stl.