Creative Lab — API Fidget Boleh Lipat

Tukarkan foto sumber kepada mainan fidget boleh lipat cetak-di-tempat: siluet subjek menjadi satu set gelang sepusat bersarang yang boleh dimampatkan rata dan direntang semula, dicetak dalam satu bahagian tanpa pemasangan.

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

Berbeza dengan endpoint Creative Lab yang lain, endpoint ini tidak mempunyai pasangan peringkat prototaip/binaan — tidak ada calon perantaraan untuk dipilih, jadi satu tugas membawa imej terus sehingga menjadi model 3D. Kawalan geometri yang didedahkan oleh aplikasi web (saiz, bilangan lapisan, lebar jurang, ketebalan dinding, kedalaman ekstrusi, bonjolan) juga bukan sebahagian daripada permintaan: setiap tugas dibina dengan nilai lalai sisi pelayan yang sama.

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

Cipta Tugasan Fidget Boleh Kuncup

Jana model fidget boleh kuncup daripada foto sumber. Rujuk The Collapsible Fidget Task Object untuk bentuk respons.

Setiap tugasan berkos 6 kredit dan memerlukan pelan berbayar.

Parameter

  • Name
    image_url
    Type
    string
    Diperlukan
    Description

    Foto sumber untuk Meshy tukar menjadi fidget boleh kuncup. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.

    Terdapat dua cara untuk menyediakan imej:

    • URL yang boleh diakses secara umum: Satu URL yang dapat diakses daripada internet awam.
    • Data URI: Satu data URI imej yang dikodkan base64. Contoh data URI: data:image/jpeg;base64,<data imej anda yang dikodkan base64>.

    Subjek dengan satu garis luar yang jelas dan tertutup memberikan hasil terbaik — siluet itulah yang menjadi gelang-gelang. Latar belakang yang sibuk, beberapa subjek berasingan, atau bentuk yang sangat nipis boleh menyisakan terlalu sedikit ruang untuk dinding bersarang, dan tugasan itu akan gagal dengan ralat tugasan.

  • Name
    name
    Type
    string
    Description

    Nama tugasan pilihan untuk tujuan paparan. Maksimum 100 aksara. Ini hanyalah label tugasan; tiada apa-apa yang diukir pada model.

Pulangan

Sifat result bagi respons mengandungi id tugasan bagi tugasan fidget boleh kuncup yang baru dicipta. Poll endpoint Get a Task atau langgan stream sehingga tugasan mencapai SUCCEEDED, kemudian muat turun STL yang boleh dicetak daripada model_urls.stl (dan, apabila ada, GLB daripada model_urls.glb untuk pratonton dahulu).

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak diterima. Sebab lazim:

    • Parameter hilang: image_url diperlukan.
    • Format imej tidak sah: image_url yang diberikan bukan format yang disokong (.jpg, .jpeg, .png, .webp).
    • Dimensi imej 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 sah bentuknya.
    • Kandungan ditandai: Imej input ditandai oleh moderation NSFW.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Sama ada akaun anda berada pada pelan percuma — penciptaan tugasan pada endpoint ini memerlukan pelan berbayar — atau kredit anda tidak mencukupi.

  • Name
    403 - Forbidden
    Description

    Imej input ditandai kerana melanggar hak harta intelek.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar anda.

Request

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

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/creative-lab/fidget-collapsible/v1/:id

Dapatkan Semula Tugas Fidget Boleh Lipat

Dapatkan semula tugas fidget boleh lipat dengan id tugas yang sah. Hanya tugas yang dicipta melalui endpoint ini boleh diakses di sini — tugas daripada endpoint Creative Lab yang lain, atau yang dicipta dalam aplikasi web, akan mengembalikan 404.

Rujuk Objek Tugas Fidget Boleh Lipat untuk bentuk respons.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas fidget boleh lipat yang hendak didapatkan semula.

Pulangan

Respons mengandungi objek tugas fidget boleh lipat.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Padam Tugasan Fidget Collapsible

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

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugasan fidget collapsible yang hendak dibatalkan.

Nilai Pulangan

Mengembalikan 204 No Content apabila berjaya dengan badan yang kosong.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Tugasan sudah berada dalam status akhir dan tidak boleh dibatalkan.

  • Name
    404 - Not Found
    Description

    Tugasan tidak wujud, dimiliki oleh pengguna lain, atau tidak dicipta melalui endpoint ini.

Request

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

Response

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

Alirkan Tugas Fidget Boleh Kuncup

Alirkan kemas kini masa nyata untuk tugas fidget boleh kuncup melalui Server-Sent Events (SSE). Tugas yang tidak wujud, atau tidak dicipta melalui endpoint ini, akan menghantar satu event: error payload dengan status_code: 404 dan menutup strim tersebut.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas fidget boleh kuncup yang akan dialirkan.

Pulangan

Mengembalikan strim objek tugas Fidget Boleh Kuncup sebagai Server-Sent Events. Untuk tugas berstatus PENDING atau IN_PROGRESS, strim respons hanya akan merangkumi medan progress dan status yang diperlukan.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.cn/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Senaraikan Tugas Fidget Boleh Lipat

Dapatkan senarai bertunda halaman bagi tugas fidget boleh lipat anda. Hanya tugas yang dicipta melalui endpoint ini disertakan.

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

Memulangkan senarai bertunda halaman bagi objek tugas fidget boleh lipat.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

The Collapsible Fidget Task Object

Objek Collapsible Fidget Task ialah unit kerja yang dijejaki oleh Meshy untuk menukar foto sumber kepada model fidget boleh dilipat yang boleh dicetak terus (print-in-place). Ia adalah tugas satu peringkat: tiada prototaip untuk dirangkaikan, dan siluet perantaraan bukan sebahagian daripada respons.

Properties

  • Name
    id
    Type
    string
    Description

    Pengenal unik untuk tugas. Walaupun kami menggunakan UUID yang boleh diisih-k (k-sortable) sebagai butiran pelaksanaan bagi id tugas, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas. Nilainya ialah creative-lab-fidget-collapsible.

  • 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 bila 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 bila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, sifat ini akan menjadi null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa bila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa bila hasil tugas akan luput, dalam milisaat.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas yang mendahului.

    Nilai medan ini hanya bermakna jika status tugas ialah PENDING.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugas yang gagal. Lihat Errors untuk rujukan penuh objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugas ini. Wujud apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan semula apabila gagal).

  • Name
    model_urls
    Type
    object
    Description

    URL yang boleh dimuat turun untuk model 3D yang dijana. Diisi setelah tugas SUCCEEDED: stl sentiasa hadir, glb hanya apabila render pratonton berjaya.

    • Name
      stl
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail STL. Ini adalah hasil kerja yang boleh dicetak — hantar terus ke slicer.

    • Name
      glb
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail GLB, untuk melihat pratonton model dalam penonton 3D. Warnanya hanya untuk pratonton sahaja: STL tidak membawa warna, dan fidget yang dicetak mengambil warnanya daripada filamen. GLB adalah usaha terbaik (best-effort): apabila render pratonton tidak tersedia, kunci tersebut ditinggalkan sepenuhnya daripada model_urls, jadi bacalah secara berhati-hati — stl ialah hasil kerja dan sentiasa hadir pada tugas SUCCEEDED.

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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}