Creative Lab — Collapsible Fidget API

Tukar foto sumber kepada mainan fidget boleh kuncup print-in-place: siluet subjek menjadi satu set gegelang konsentrik bersarang yang boleh kuncup rata dan meregang semula, dicetak dalam satu bahagian tanpa pemasangan.

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

Tidak seperti endpoint Creative Lab yang lain, endpoint ini tidak mempunyai pasangan peringkat prototaip/binaan — tiada calon perantaraan untuk dipilih, jadi satu tugas membawa imej sepanjang jalan hingga 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 tetapan lalai sisi pelayan yang sama.

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

Cipta Tugas Fidget Boleh Lipat

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

Setiap tugas berharga 6 kredit dan memerlukan pelan berbayar.

Parameter

  • Name
    image_url
    Type
    string
    Diperlukan
    Description

    Foto sumber untuk Meshy jadikan fidget boleh lipat. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.

    Terdapat dua cara untuk memberikan imej:

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

    Subjek dengan satu garis luar yang jelas dan tertutup berfungsi paling baik — siluet itulah yang menjadi gelang-gelang. Latar belakang yang sibuk, beberapa subjek berasingan, atau bentuk yang sangat nipis boleh meninggalkan terlalu sedikit ruang untuk dinding bersarang, dan tugas akan gagal dengan ralat tugas.

  • Name
    name
    Type
    string
    Description

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

Pulangan

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

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak boleh diterima. Sebab biasa:

    • 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.
    • 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 menggunakan pelan percuma — pencipta tugas pada endpoint ini memerlukan pelan berbayar — atau anda mempunyai kredit yang tidak mencukupi.

  • Name
    403 - Forbidden
    Description

    Imej input ditandai kerana pelanggaran 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.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"
}
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 dicapai di sini — tugas daripada endpoint Creative Lab 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

    Pengecam 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.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=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Padam Tugasan Fidget Boleh Lipat

Batalkan tugasan fidget boleh lipat. 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 sudah mencapai keadaan akhir (SUCCEEDED, FAILED, CANCELED) tidak boleh dibatalkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugasan fidget boleh lipat yang ingin dibatalkan.

Pulangan

Mengembalikan 204 No Content apabila berjaya dengan badan kosong.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Tugasan sudah berada dalam keadaan 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.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).
GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Alirkan Tugas Fidget Collapsible

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

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas fidget collapsible yang hendak dialirkan.

Kembalian

Mengembalikan strim objek tugas Collapsible Fidget sebagai Server-Sent Events. Setiap bingkai membawa objek tugas penuh untuk peringkat tersebut — bentuk yang sama seperti 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-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 PENDING frame below is abbreviated 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=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Senaraikan Tugas Fidget Boleh Lipat

Dapatkan senarai bertompokkan penomboran 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 mengikut. Nilai yang tersedia:

    • +created_at: Isih mengikut masa penciptaan dalam susunan menaik.
    • -created_at: Isih mengikut masa penciptaan dalam susunan menurun.

Pulangan

Mengembalikan senarai bertompokkan penomboran halaman bagi objek tugas fidget boleh lipat.

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

Objek Tugas Fidget Boleh Lipat (Collapsible Fidget)

Objek Tugas Fidget Boleh Lipat ialah unit kerja yang dijejaki oleh Meshy untuk menukar foto sumber menjadi model fidget boleh lipat print-in-place. Ia merupakan tugas satu peringkat: tiada prototaip untuk dirangkaikan, dan siluet perantaraan bukan sebahagian daripada respons.

Ciri-ciri

  • Name
    id
    Type
    string
    Description

    Pengecam unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun-k (k-sortable) untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya 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, ciri ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa bila tugas tersebut 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 tersebut bermula, dalam milisaat. Jika tugas belum bermula lagi, ciri ini akan menjadi null.

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa bila hasil tugas tersebut tamat tempoh, dalam milisaat.

  • 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. Wujud apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan apabila gagal).

  • Name
    model_urls
    Type
    object
    Description

    URL boleh muat 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 boleh muat turun untuk fail STL. Ini ialah bahan siap cetak — hantar terus ke slicer.

    • Name
      glb
      Type
      string
      Description

      URL boleh muat turun untuk fail GLB, untuk pratonton model dalam pemapar 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 ditiadakan sepenuhnya daripada model_urls, jadi bacalah dengan berjaga-jaga — stl ialah bahan yang dihantar 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.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=***"
  }
}