Creative Lab — Collapsible Fidget API

Ubah foto sumber menjadi mainan fidget collapsible yang siap dicetak langsung: siluet subjek menjadi serangkaian cincin konsentris bersarang yang dapat dikempeskan rata dan direntangkan kembali, dicetak dalam satu bagian tanpa perlu perakitan.

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

Berbeda dari endpoint Creative Lab lainnya, endpoint ini tidak memiliki pasangan tahap prototype/build — tidak ada kandidat perantara untuk dipilih, sehingga satu task membawa gambar tersebut hingga menjadi model 3D. Kontrol geometri yang diekspos oleh aplikasi web (ukuran, jumlah layer, lebar celah, ketebalan dinding, kedalaman ekstrusi, tonjolan) juga bukan bagian dari request: setiap task dibuat dengan nilai bawaan (default) dari sisi server yang sama.

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

Membuat Collapsible Fidget Task

Menghasilkan model collapsible fidget dari foto sumber. Lihat The Collapsible Fidget Task Object untuk bentuk responsnya.

Setiap task menghabiskan 6 kredit dan memerlukan paket berbayar.

Parameter

  • Name
    image_url
    Type
    string
    Wajib
    Description

    Foto sumber untuk diubah Meshy menjadi collapsible fidget. Saat ini kami mendukung format .jpg, .jpeg, .png, dan .webp.

    Ada dua cara untuk menyediakan gambar:

    • URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
    • Data URI: Data URI gambar yang dienkode dalam base64. Contoh data URI: data:image/jpeg;base64,<data gambar terenkode base64 Anda>.

    Subjek dengan satu garis luar yang jelas dan tertutup akan memberikan hasil terbaik — siluet inilah yang akan menjadi cincin-cincinnya. Latar belakang yang ramai, beberapa subjek terpisah, atau bentuk yang sangat tipis dapat menyisakan terlalu sedikit area untuk dinding bertingkat, dan task akan gagal dengan error task.

  • Name
    name
    Type
    string
    Description

    Nama task opsional untuk keperluan tampilan. Maksimum 100 karakter. Ini hanyalah label task; tidak ada apa pun yang terukir pada model.

Returns

Properti result pada respons berisi id task collapsible fidget yang baru dibuat. Poll endpoint Get a Task atau berlangganan stream hingga task mencapai status SUCCEEDED, lalu unduh STL yang dapat dicetak dari model_urls.stl (dan, jika tersedia, GLB dari model_urls.glb untuk mempratinjaunya terlebih dahulu).

Failure Modes

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: image_url wajib diisi.
    • Format gambar tidak valid: image_url yang diberikan bukan format yang didukung (.jpg, .jpeg, .png, .webp).
    • Dimensi gambar di luar rentang: Gambar terlalu kecil, melebihi ukuran file maksimum, atau melebihi jumlah piksel maksimum.
    • URL tidak dapat diakses: image_url tidak dapat diunduh (404 atau timeout).
    • Data URI tidak valid: String base64 tidak terbentuk dengan benar.
    • Konten ditandai: Gambar input ditandai oleh moderation NSFW.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Akun Anda menggunakan paket gratis — pembuatan task pada endpoint ini memerlukan paket berbayar — atau kredit Anda tidak cukup.

  • Name
    403 - Forbidden
    Description

    Gambar input ditandai karena pelanggaran hak kekayaan intelektual.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju 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

Mengambil Task Fidget Collapsible

Ambil task fidget collapsible menggunakan id task yang valid. Hanya task yang dibuat melalui endpoint ini yang dapat diakses di sini — task dari endpoint Creative Lab lain, atau yang dibuat di aplikasi web, akan mengembalikan 404.

Lihat The Collapsible Fidget Task Object untuk bentuk responsnya.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk task fidget collapsible yang akan diambil.

Returns

Respons berisi objek task fidget collapsible.

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

Hapus Tugas Collapsible Fidget

Batalkan tugas collapsible fidget. Jika tugas masih PENDING, kredit yang terpakai saat pembuatan akan dikembalikan. Tugas yang sudah IN_PROGRESS akan dibatalkan tanpa pengembalian dana (worker mungkin sudah menggunakan sumber daya). Tugas yang sudah mencapai status akhir (SUCCEEDED, FAILED, CANCELED) tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas collapsible fidget yang akan dibatalkan.

Returns

Mengembalikan 204 No Content jika berhasil dengan isi kosong.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Tugas sudah berada pada status akhir dan tidak dapat dibatalkan.

  • Name
    404 - Not Found
    Description

    Tugas tidak ada, milik pengguna lain, atau tidak dibuat 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

Streaming Tugas Collapsible Fidget

Melakukan streaming pembaruan secara real-time untuk tugas collapsible fidget melalui Server-Sent Events (SSE). Tugas yang tidak ada, atau tidak dibuat melalui endpoint ini, akan mengeluarkan satu event: error payload dengan status_code: 404 dan menutup stream.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas collapsible fidget yang akan di-streaming.

Returns

Mengembalikan sebuah stream objek tugas Collapsible Fidget sebagai Server-Sent Events. Setiap frame membawa objek tugas lengkap untuk tahap tersebut — bentuk yang sama seperti yang dikembalikan oleh endpoint Get — jadi selama tugas berstatus PENDING atau IN_PROGRESS, field output-nya sekadar belum terisi (null, [] atau {}) dan finished_at bernilai 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

Daftar Tugas Collapsible Fidget

Ambil daftar tugas collapsible fidget Anda dengan paginasi. Hanya tugas yang dibuat melalui endpoint ini yang disertakan.

Parameter Kueri

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman untuk paginasi.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Batas ukuran halaman. Maksimum yang diizinkan adalah 100 item.

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    Kolom untuk mengurutkan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara ascending.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara descending.

Mengembalikan

Mengembalikan daftar dengan paginasi dari objek tugas collapsible fidget.

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 Bisa Dilipat (Collapsible Fidget)

Objek Tugas Collapsible Fidget adalah unit kerja yang dilacak oleh Meshy untuk mengubah foto sumber menjadi model fidget yang bisa dilipat dan dicetak langsung (print-in-place). Ini adalah tugas satu tahap: tidak ada prototipe untuk dirangkai, dan siluet perantara bukan bagian dari respons.

Properti

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan k-sortable UUID untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Tipe tugas. Nilainya adalah creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    Nama tugas yang diberikan saat tugas dibuat. String kosong jika tidak ada nama yang diberikan.

  • Name
    status
    Type
    string
    Description

    Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas. Jika tugas belum dimulai, properti ini akan bernilai 0. Setelah tugas berhasil, nilainya akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dibuat, dalam milidetik.

    Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 pukul 12:00:00 GMT direpresentasikan sebagai 1693569600000. Hal ini berlaku untuk semua stempel waktu di Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan bernilai null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas yang mendahului.

    Nilai bidang ini hanya bermakna jika status tugas adalah PENDING.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang terpakai oleh tugas ini. Muncul saat status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal).

  • Name
    model_urls
    Type
    object
    Description

    URL yang dapat diunduh untuk model 3D yang dihasilkan. Terisi setelah tugas SUCCEEDED: stl selalu ada, glb hanya ada saat rendering pratinjau berhasil.

    • Name
      stl
      Type
      string
      Description

      URL yang dapat diunduh untuk file STL. Ini adalah hasil akhir yang dapat dicetak — kirim langsung ke slicer.

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk file GLB, untuk melihat pratinjau model di penampil 3D. Warnanya hanya untuk pratinjau: STL tidak membawa informasi warna, dan fidget yang dicetak mengambil warnanya dari filamen. GLB bersifat best-effort: saat rendering pratinjau tidak tersedia, kunci tersebut dihilangkan sepenuhnya dari model_urls, jadi baca dengan hati-hati — stl adalah hasil akhir dan selalu ada 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=***"
  }
}