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

API Keycap Creative Lab

Tukarkan foto kepada keycap tersuai berwarna penuh untuk papan kekunci mekanikal dalam dua peringkat. Tugas prototaip menjana imej keycap siap daripada foto tersebut. Tugas binaan menukar imej itu kepada model keycap 3D bertekstur. Ia mengambil ID tugas prototaip sebagai input_task_id dan ID calon imej sebagai candidate_id.

  • POST /openapi/creative-lab/keycap/v1/prototype
  • POST /openapi/creative-lab/keycap/v1/build

Kedua-dua endpoint POST memerlukan pelan berbayar. Permintaan daripada akaun pelan percuma mengembalikan 402.

POST/openapi/creative-lab/keycap/v1/prototype

Create a Keycap prototype task

Menjana satu imej keycap siap daripada foto. Medan image_urls tugas menyimpan imej tersebut, dan candidate_ids menyimpan ID-nya, dengan satu entri bagi setiap satu. Jika anda tidak berpuas hati dengan reka bentuk itu, buat tugas prototaip lain. Meshy mengenakan caj bagi setiap tugas prototaip secara berasingan.

Untuk membina keycap 3D, hantar ID tugas ini ke endpoint bina sebagai input_task_id, dengan entri candidate_ids sebagai candidate_id. Untuk medan tugas tersebut, lihat Objek tugas prototaip Keycap.

Request

POST
/openapi/creative-lab/keycap/v1/prototype
# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/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>"
  }'

Response

{
  "result": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

Parameter

  • Name
    image_url
    Type
    string
    Diperlukan
    Description

    Foto yang hendak dijadikan reka bentuk keycap, sebagai URL awam atau data URI (data:image/jpeg;base64,<your base64-encoded image data>).

    Imej tersebut mestilah fail JPG, JPEG, PNG, atau WebP yang tidak melebihi 20 MB (20,000,000 bait). Setiap sisi mestilah sekurang-kurangnya 32 piksel, dan imej boleh mempunyai sebanyak-banyaknya 178,956,970 piksel secara keseluruhan. Imej di luar had ini mengembalikan 400.

    Meshy mengesan format daripada data imej, bukan daripada sambungan fail dalam URL. URL tanpa sambungan tetap berfungsi, dan Meshy mengikut pengalihan (redirect) HTTP. Meshy menggunakan orientasi EXIF, jadi foto telefon yang berputar akan terhasil seperti rupanya yang sebenar.

    Data URI mestilah dikodkan base64 dengan jenis imej, seperti data:image/png;base64,..., dan imej yang dinyahkod mestilah JPEG, PNG, atau WebP. Had 20 MB dikenakan pada imej yang dinyahkod, jadi teks base64 boleh menjadi kira-kira satu pertiga lebih besar.

  • 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.

  • Name
    remove_background
    Type
    boolean
    lalai false
    Description

    Sama ada untuk mengeluarkan latar belakang daripada imej prototaip. true mengembalikan PNG RGBA telus, supaya anda boleh meletakkan keycap tersebut pada sebarang latar belakang. Jika Meshy tidak dapat mengeluarkan latar belakang, ia mengembalikan imej dengan latar belakangnya, dan tugas tetap berjaya.

    Reka bentuk kepala yang ditukar oleh binaan kepada 3D mengekalkan latar belakangnya dalam kedua-dua keadaan. Binaan mengecat tapak keycap daripada imej dalam image_urls, tanpa latar belakangnya jika anda menghantar true. Binaan mengembalikan imej tersebut sebagai process_image_urls.composite.

Pulangan

Medan result menyimpan ID tugas prototaip yang baharu. Dapatkan tugas atau strim tugas tersebut sehingga status adalah SUCCEEDED. Kemudian hantar ID tersebut ke endpoint bina sebagai input_task_id, dengan entri daripada candidate_ids sebagai candidate_id.

Mod kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Contohnya:

    • image_url tiada.
    • Imej tersebut bukan fail JPG, JPEG, PNG, atau WebP.
    • Imej tersebut 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 tersebut ditandai 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 pengepala 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 menandai imej tersebut kerana 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 Had kadar.
    • Terlalu banyak tugas anda yang 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 sehingga satu tugas selesai, atau tambah kredit.
  • Name
    500 - Internal Server Error
    Description

    Meshy mengalami ralat pelayan, contohnya kerana moderation kandungan atau semakan harta intelek tidak dapat dijalankan, atau Meshy tidak dapat menyimpan imej tersebut. Meshy tidak mencipta tugas tersebut, dan memulangkan semula sebarang kredit yang telah dikenakan. Cuba semula permintaan tersebut.

POST/openapi/creative-lab/keycap/v1/build

Cipta tugas pembinaan Keycap

Menjana keycap 3D bertekstur daripada tugas prototaip yang berjaya dan salah satu daripada calonnya. Untuk medannya, lihat The Keycap build task object.

Satu tugas pembinaan menjalankan setiap langkah. Ia menjana model 3D daripada reka bentuk dan mewarnakannya. Kemudian ia mendudukkan dan memotong model tersebut ke atas asas keycap dalam kedudukan lalai yang dikalibrasi, supaya anda tidak perlu melaraskannya secara manual. Akhir sekali, ia memasang keycap tersebut dan mengeksport fail-fail tersebut. Satu pembinaan biasanya mengambil masa 3 hingga 7 minit.

Request

POST
/openapi/creative-lab/keycap/v1/build
# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}

Parameter

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID tugas prototaip untuk dibina. Ia mestilah tugas yang dicipta oleh akaun anda menggunakan POST /openapi/creative-lab/keycap/v1/prototype, dengan status SUCCEEDED.

    ID yang bukan salah satu tugas prototaip Keycap anda daripada API akan mengembalikan 404, termasuk prototaip yang dibuat dalam aplikasi web.

  • Name
    candidate_id
    Type
    string
    Diperlukan
    Description

    Calon untuk dibina, daripada tatasusunan candidate_ids tugas prototaip tersebut. Nilai yang tidak terdapat dalam tatasusunan itu akan mengembalikan 400.

  • Name
    name
    Type
    string
    Description

    Nama untuk tugas tersebut, sehingga 100 aksara. Ia akan dikembalikan dalam medan name tugas tersebut. Nama yang lebih panjang akan mengembalikan 400.

options

Tetapan geometri pilihan. Setiap medan mempunyai nilai lalai yang dikalibrasi, jadi hantar hanya medan yang anda ingin ubah.

  • Name
    base_model
    Type
    string
    lalai cherry-mx-1x1-r1
    Description

    Asas keycap untuk dibina. Satu-satunya nilai ialah cherry-mx-1x1-r1, iaitu keycap profil Cherry MX 1u piawai. Saiz tersuai tidak disokong, dan sebarang nilai lain akan mengembalikan 400.

  • Name
    head_size_mm
    Type
    number
    lalai 23
    Description

    Saiz kepala mengikut dimensi terpanjangnya, dalam milimeter, daripada 10 hingga 40. Meshy menskalakan kepala tersebut supaya dimensi terpanjangnya sepadan dengan nilai ini. Nilai di luar julat akan mengembalikan 400.

    Untuk nilai melebihi kira-kira 32.9, Meshy mungkin mengurangkan saiz supaya kepala tersebut muat dalam had jejak perlindungan asas tersebut. Kepala itu kemudiannya mungkin keluar lebih kecil daripada yang anda minta. Objek tugas tidak mengembalikan saiz yang digunakan oleh Meshy. Untuk menyemaknya, ukur kotak pembatas jejaring keycap-head dalam model tersebut.

  • Name
    vertical_offset_mm
    Type
    number
    lalai 0
    Description

    Ofset menegak untuk dikenakan pada kepala sebelum Meshy mendudukkannya pada asas, dalam milimeter, daripada -5 hingga 5. Nilai di luar julat akan mengembalikan 400.

Pemulangan

Medan result menyimpan ID tugas pembinaan baharu. Dapatkan tugas tersebut atau strim tugas tersebut sehingga status ialah SUCCEEDED. Kemudian muat turun fail GLB daripada model_urls.glb dan bungkusan OBJ daripada model_urls.obj_zip.

Meshy mengeksport fail GLB dan bungkusan OBJ pada skala dunia sebenar dalam milimeter. Kedua-duanya menggunakan sistem koordinat Y-ke-atas, dengan bahagian hadapan keycap menghadap +Z.

Mod kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat dijalankan. Contohnya:

    • input_task_id tiada atau bukan ID tugas yang sah.
    • Status tugas prototaip bukan SUCCEEDED. Jika ia masih berjalan, tunggu dan cuba semula. Jika ia gagal atau dibatalkan, cipta tugas prototaip baharu.
    • Tugas prototaip berjaya tetapi tiada calon. Cipta tugas prototaip baharu.
    • candidate_id tiada, atau tidak terdapat dalam candidate_ids tugas prototaip tersebut. Hantar nilai daripada tatasusunan itu.
    • Satu medan dalam options berada di luar julat, atau base_model bukan nilai yang tersedia.

    Mesej ralat menyatakan masalah yang dijumpainya.

  • 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
    404 - Not Found
    Description

    input_task_id tidak sepadan dengan mana-mana tugas prototaip Keycap yang dicipta oleh akaun anda menggunakan API. Prototaip yang dibuat dalam aplikasi web juga akan mengembalikan 404. Hantar ID result daripada respons cipta prototaip.

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

    Meshy tidak dapat mencipta tugas tersebut kerana ralat pelayan. Meshy akan mengembalikan semula sebarang kredit yang telah dicaj. Cuba semula permintaan tersebut.

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

Dapatkan tugas Keycap

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

Untuk medan-medan, lihat The Keycap prototype task object dan The Keycap build task object.

Request

GET
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas daripada respons create.

Pulangan

Objek tugas prototype atau objek tugas build, yang sepadan dengan 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 prototype tersebut kerana hak harta intelek pihak ketiga. Tugas build dan pasukan pada pelan Enterprise tidak mendapat ralat ini. Cipta tugas prototype daripada imej yang anda mempunyai hak untuk menggunakannya.

  • Name
    404 - Not Found
    Description

    Tiada tugas Keycap dengan ID ini yang dimiliki oleh akaun anda, atau peringkat tugas tidak sepadan dengan laluan. Semak ID, dan gunakan /prototype atau /build untuk memadankan tugas tersebut.

  • Name
    500 - Internal Server Error
    Description

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

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

Padam tugas Keycap

Membatalkan tugas Keycap. Membatalkan tugas PENDING akan memulangkan kreditnya. Tugas IN_PROGRESS dibatalkan tanpa bayaran balik, kerana pekerja sudah pun memulakannya. Tugas yang mempunyai status muktamad (SUCCEEDED, FAILED, atau CANCELED) tidak boleh dibatalkan.

Laluan tersebut mesti sepadan dengan peringkat tugas. Sebagai contoh, DELETE pada /prototype/:id dengan ID tugas build akan memulangkan 404.

Request

DELETE
/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -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 tersebut sudah mempunyai status muktamad (SUCCEEDED, FAILED, atau CANCELED), jadi ia tidak boleh dibatalkan.
  • Name
    404 - Not Found
    Description

    Tiada tugas Keycap dengan ID ini yang tergolong dalam akaun anda, atau peringkat tugas tidak sepadan dengan laluan. Semak ID, dan gunakan /prototype atau /build untuk memadankan tugas tersebut.

  • Name
    500 - Internal Server Error
    Description

    Meshy menemui ralat pelayan semasa membatalkan tugas, jadi tugas tersebut mungkin dibatalkan atau mungkin tidak. Dapatkan tugas tersebut untuk menyemak status-nya sebelum anda mencuba semula.

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

Alirkan tugas Keycap

Mengalirkan kemas kini tugas Keycap sebagai Server-Sent Events (SSE). Laluan mesti sepadan dengan peringkat tugas tersebut. Jika tidak, contohnya ID tugas build pada /prototype/:id/stream, strim tersebut menghantar satu peristiwa error dengan status_code: 404 dan ditutup.

Request

GET
/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/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; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***"
  }
}

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas daripada respons create.

Nilai Pulangan

Satu strim objek tugas prototype atau build. Setiap peristiwa mengandungi objek tugas penuh, sepertimana yang dipulangkan oleh Get a Keycap task. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan outputnya masih kosong (null, [], atau {}), dan finished_at adalah null.

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

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

Senaraikan tugas Keycap

Mengembalikan tugas Keycap anda bagi satu peringkat, satu halaman pada satu masa. Laluan (path) memilih peringkat tersebut. /prototype hanya mengembalikan tugas prototaip, dan /build hanya mengembalikan tugas pembinaan.

Request

GET
/openapi/creative-lab/keycap/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

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 julat 0 hingga 255 akan 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 julat 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

Mengembalikan

Satu tatasusunan objek tugas prototaip atau objek tugas pembinaan, yang sepadan dengan peringkat dalam laluan.

Objek tugas prototaip Keycap

Tugas prototaip menghasilkan satu imej keycap siap daripada sebuah foto. Untuk menukar reka bentuk itu kepada keycap 3D, hantar ID tugas tersebut kepada endpoint build sebagai input_task_id, dengan entri candidate_ids-nya sebagai candidate_id.

Sifat

Example Keycap Prototype Task Object

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}
  • Name
    id
    Type
    string
    Description

    ID tugas. Jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, sentiasa creative-lab-keycap-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: 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 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 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 tersebut, selepas sebarang bayaran balik. Permintaan yang mengembalikan ralat tidak dicaj. Tugas yang gagal adalah 0, kerana Meshy membayarnya balik. Membatalkan tugas hanya membayar balik semasa ia PENDING. Jika Meshy tidak dapat membaca caj tersebut, respons get atau stream akan meninggalkan medan tersebut, dan permintaan senarai akan mengembalikan 500. Dalam kes itu, cuba lagi permintaan tersebut.

  • Name
    image_urls
    Type
    array of strings
    Description

    URL muat turun untuk imej keycap siap. Tatasusunan ini mempunyai satu URL selepas tugas berjaya, dan kosong sehingga itu. image_urls[i] menunjukkan calon dalam candidate_ids[i].

    URL ini adalah untuk paparan. Endpoint build mengambil entri daripada candidate_ids, bukan URL. Ia adalah URL bertandatangan, jadi ambillah tanpa header Authorization. Ia kekal sah sehingga expires_at, dan mendapatkan semula tugas tersebut mengembalikan URL yang sama.

  • Name
    candidate_ids
    Type
    array of strings
    Description

    ID calon, dalam susunan yang sama seperti image_urls. Untuk membina satu calon, hantar ID-nya sebagai candidate_id dalam permintaan build. Jangan bergantung pada format ID ini.

Objek tugas pembinaan Keycap

Tugas pembinaan menghasilkan keycap 3D bertekstur daripada tugas prototaip yang berjaya dan salah satu calonnya. Ia menghasilkan model 3D, mewarnakannya, memasangkan dan memotongnya pada asas keycap, kemudian memasang dan mengeksport keycap tersebut.

Ciri-ciri

Example Keycap Build Task Object

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

    ID tugas. Jangan bergantung pada formatnya.

  • Name
    type
    Type
    string
    Description

    Jenis tugas, sentiasa creative-lab-keycap-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 siap, 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 luput, 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 secara berkekalan, ia adalah 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 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 dikenakan bagi 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 meninggalkan medan tersebut, 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. Meshy mengeksport fail GLB dan bungkusan OBJ pada skala dunia sebenar dalam milimeter, Y-ke-atas, dengan bahagian depan keycap menghadap +Z.

    Model ini mempunyai jejaring bernama keycap-head dan keycap-base. Apabila Meshy beralih kepada pengisian corak untuk asas, model juga mempunyai jejaring keycap-base-interior untuk rongga stem. Jangan anggap model mempunyai tepat dua jejaring.

    Ini adalah URL yang ditandatangani, jadi dapatkannya tanpa header Authorization. Ia kekal sah sehingga expires_at, dan mendapatkan tugas tersebut semula sebelum itu akan mengembalikan URL yang sama. URL yang telah luput tidak boleh diperbaharui, jadi muat turun dan simpan fail sebelum itu.

    • Name
      glb
      Type
      string
      Description

      URL muat turun untuk fail GLB bertekstur, model.glb.

    • Name
      obj_zip
      Type
      string
      Description

      URL muat turun untuk bungkusan OBJ, satu fail ZIP dengan model.obj, model.mtl, dan tekstur PNG yang digunakan oleh model.mtl. Dengan asas berwarna pepejal, satu-satunya tekstur ialah keycap-head.png. Dengan asas bercorak, fail ZIP juga mempunyai keycap-base.png.

  • Name
    process_image_urls
    Type
    object
    Description

    URL muat turun untuk imej daripada langkah-langkah pembinaan, dikunci mengikut jenis. Seperti model_urls, ia adalah URL yang ditandatangani, jadi dapatkannya tanpa header Authorization. Ia kekal sah sehingga expires_at, dan mendapatkan tugas tersebut semula akan mengembalikan URL yang sama.

    Ia boleh mempunyai kunci-kunci ini:

    • head_design: imej reka bentuk calon yang dipilih, yang pembinaan ini jadikan 3D. Sentiasa hadir.
    • composite: imej keycap siap untuk calon yang dipilih, yang menjadi sumber pengecatan asas oleh pembinaan ini. Mungkin tiada.
    • base_canvas: asas keycap yang telah dicat. Mungkin tiada.

    Meshy mungkin menambah kunci, jadi abaikan kunci yang anda tidak kenali.

End-to-end example

Contoh ini menjalankan keseluruhan aliran:

  1. Cipta tugas prototaip daripada foto.
  2. Dapatkan tugas sehingga status-nya adalah SUCCEEDED.
  3. Pilih calon daripada candidate_ids.
  4. Cipta tugas bina (build) dengan calon tersebut.
  5. Dapatkan tugas bina sehingga status-nya adalah SUCCEEDED.
  6. Muat turun fail GLB dan pakej OBJ daripada model_urls.

Contoh ini memilih calon pertama. Dalam aplikasi anda, tunjukkan entri image_urls kepada pengguna anda dan biarkan mereka memilih. Indeks imej yang dipilih dalam image_urls adalah indeks ID-nya dalam candidate_ids.

Complete flow

POST
/openapi/creative-lab/keycap/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://...
: "${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

BASE="https://api.meshy.ai/openapi/creative-lab/keycap/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 '{"image_url":"data:%s;base64,' "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  printf '{"image_url":"%s"}' "$IMAGE_URL" >"$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 design render
poll prototype "$PROTO_ID"

# 3. Pick a candidate (first one here; show image_urls to a user in production)
CANDIDATE_ID=$(api GET "$BASE/prototype/$PROTO_ID" | jq -r '.candidate_ids[0]')

# 4. Create the build task
jq -n --arg p "$PROTO_ID" --arg c "$CANDIDATE_ID" \
  '{input_task_id: $p, candidate_id: $c}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 5. Wait for the model (a build usually takes 3-7 minutes)
poll build "$BUILD_ID"

# 6. Download the artifacts. These are signed URLs: no Authorization header,
#    and they stay valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o keycap.glb "$(jq -r '.model_urls.glb' <<<"$TASK")"
curl --silent --show-error --fail --max-time 900 \
  -o keycap-obj.zip "$(jq -r '.model_urls.obj_zip' <<<"$TASK")"
echo "Done: keycap.glb + keycap-obj.zip"