Creative Lab Keychain API

Ubah sebuah foto menjadi gantungan kunci yang dapat dicetak 3D dengan relief berwarna dalam dua tahap. Tugas prototipe menghasilkan gambar konsep berwarna dari foto tersebut. Tugas build mengubah gambar tersebut menjadi model 3D relief, dan menggunakan ID dari tugas prototipe tersebut sebagai input_task_id.

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

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

Membuat tugas prototipe Keychain

Menghasilkan satu gambar konsep berwarna dari sebuah foto. Untuk membangun model 3D, teruskan ID tugas ini ke endpoint build sebagai input_task_id. Untuk kolom-kolom tugas, lihat Objek tugas prototipe Keychain.

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

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

Prototype example

Start with a source photo, then generate the prototype image used by the keychain build stage.

Source photo used as the Creative Lab Keychain input — Prototype input

Creative Lab Keychain prototype output generated from the source photo — Prototype output

Parameter

Name
image_url
Type
string
Wajib
Description
Foto yang akan diubah menjadi gambar konsep keychain, berupa URL publik atau data URI (data:image/jpeg;base64,<data gambar Anda yang dikodekan base64>).
Gambar harus berupa file JPG, JPEG, PNG, atau WebP dengan ukuran maksimal 20 MB.
Name
name
Type
string
Description
Nama untuk tugas, hingga 100 karakter. Nama ini dikembalikan pada kolom name tugas. Nama yang lebih panjang akan mengembalikan 400.
Nama ini memberi label pada tugas di dasbor dan daftar tugas Anda, dan tidak muncul pada keychain. Untuk menambahkan nama pada keychain, gunakan name_text.
Name
name_text
Type
string
Description
Nama yang akan ditambahkan pada keychain, misalnya nama hewan peliharaan atau nama seseorang, hingga 10 karakter. Meshy menghitung karakter, bukan byte, sehingga nama berbahasa Tionghoa, Jepang, atau Korea dengan 10 karakter masih sesuai. Nama yang lebih panjang akan mengembalikan 400. Jangan sertakan jika Anda ingin keychain tanpa nama.
Nama tersebut muncul pada permukaan keychain sebagai detail berwarna datar, bukan sebagai teks yang timbul atau terukir.
Meshy memangkas spasi di sekelilingnya dan menghapus karakter format yang tidak terlihat. Objek tugas prototipe mengembalikan hasilnya sebagai name_text, sehingga Anda dapat memeriksa teks tersebut sebelum membayar untuk build.
Meshy menambahkan nama pada tahap prototipe. Build mempertahankannya, dan mengabaikan name_text yang dikirim ke endpoint build.
Jika teksnya bukan ASCII biasa, kirim isi permintaan sebagai UTF-8 dengan Content-Type: application/json; charset=utf-8. Beberapa klien HTTP, seperti Invoke-RestMethod pada Windows PowerShell, secara default mengodekan isi permintaan sebagai ISO-8859-1. Hal ini mengubah setiap karakter non-Latin menjadi ? sebelum permintaan mencapai Meshy, dan Meshy tidak bisa membedakannya dari nama yang sebenarnya ingin Anda kirim.
Name
remove_background
Type
boolean
default false
Description
Menentukan apakah akan menghapus latar belakang dari gambar prototipe. true mengembalikan PNG RGBA transparan yang mempertahankan seluruh medali, sehingga Anda dapat menempatkannya pada latar belakang apa pun. Build juga dimulai dari gambar tanpa latar belakangnya. Jika Meshy tidak dapat menghapus latar belakang, Meshy akan mengembalikan gambar beserta latar belakangnya, dan tugas tetap berhasil.
Opsi remove_background pada build bersifat terpisah.

Hasil yang Dikembalikan

Kolom result berisi ID dari tugas prototipe baru. Ambil tugas tersebut atau alirkan (stream) hingga status bernilai SUCCEEDED. Kemudian teruskan ID tersebut ke endpoint build sebagai input_task_id.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Misalnya:
- image_url tidak ada.
- Gambar bukan file JPG, JPEG, PNG, atau WebP.
- Gambar terlalu kecil, lebih dari 20 MB, atau melebihi jumlah piksel maksimum.
- Meshy tidak dapat mengunduh gambar, misalnya karena URL mengembalikan 404 atau waktu habis (timeout).
- Data URI bukan base64 yang valid.
- name_text lebih panjang dari 10 karakter. Meshy menolaknya alih-alih memperpendeknya, dan tidak membebankan biaya untuk permintaan tersebut.
- Gambar atau name_text ditandai sebagai NSFW.
Pesan error menyebutkan masalah apa yang ditemukan. Perbaiki permintaan, lalu kirim ulang.
Name
401 - Unauthorized
Description
Kunci API tidak ada atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Salah satu dari berikut berlaku:
- Akun tidak memiliki kredit yang cukup.
- Kunci API, ruang kerja, atau anggota telah mencapai batas kreditnya.
- Akun berada pada paket gratis.
Periksa kredit dan paket Anda, lalu coba lagi.
Name
403 - Forbidden
Description
Tim Anda mengaktifkan IP Filtering, dan Meshy menandai gambar tersebut terkait kekayaan intelektual pihak ketiga. Kirim gambar yang hak penggunaannya Anda miliki. Meshy hanya memeriksa kekayaan intelektual pada gambar, bukan pada name_text.
Name
429 - Too Many Requests
Description
Salah satu batas berikut tercapai:
- Anda mengirim lebih banyak permintaan daripada yang diizinkan oleh batas laju Anda. Tunggu beberapa detik, lalu coba lagi. Lihat Batas laju.
- Terlalu banyak tugas Anda yang sedang antre atau berjalan. Tunggu hingga beberapa selesai, lalu coba lagi.
- Pada paket tak terbatas tanpa sisa kredit, Anda telah mencapai jumlah tugas yang dapat berjalan tanpa kredit. Tunggu hingga sebuah tugas selesai, atau tambahkan kredit.
Name
500 - Internal Server Error
Description
Meshy mengalami kesalahan server, misalnya karena tidak dapat menjalankan pemeriksaan kekayaan intelektual pada gambar. Meshy tidak membuat tugas tersebut, dan mengembalikan kredit apa pun yang telah dibebankan. Coba kirim ulang permintaan.

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

Buat tugas build Keychain

Menghasilkan keychain yang dapat dicetak 3D dari tugas prototipe yang berhasil. Meshy mengubah gambar konsep prototipe menjadi relief depth-map, dan mengembalikan satu file model dalam format yang Anda pilih. Untuk kolom-kolom tugas ini, lihat The Keychain build task object.

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task converts the selected prototype image into a 3D-printable keychain model.

Creative Lab Keychain build model preview — Build model preview

Parameter

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas prototipe yang akan di-build. ID ini harus berupa tugas yang dibuat oleh akun Anda dengan POST /openapi/creative-lab/keychain/v1/prototype, dengan status SUCCEEDED.
ID yang bukan merupakan salah satu tugas prototipe Keychain Anda dari API akan mengembalikan 404, termasuk prototipe yang dibuat di aplikasi web.
Name
name
Type
string
Description
Nama untuk tugas, hingga 100 karakter. Nilai ini akan dikembalikan pada kolom name tugas tersebut. Nama yang lebih panjang akan mengembalikan 400.

`options`

Pengaturan opsional untuk bentuk relief. Setiap kolom memiliki nilai default, jadi kirimkan hanya kolom yang ingin Anda ubah. Nilai di luar rentang suatu kolom akan mengembalikan 400.

Name
badge_shape
Type
string
default circle
Description
Garis luar keychain saat Meshy tidak menelusurinya dari subjek. Meshy menggunakan ini saat remove_background bernilai false, atau saat tidak dapat menemukan garis luar subjek.
Nilai yang tersedia:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
default 40
Description
Panjang sisi dari kotak pembatas keychain, dalam milimeter, hingga 400. 0 menggunakan nilai default.
Name
relief_height_mm
Type
number
default 2.2
Description
Tinggi maksimum relief di atas alas, dalam milimeter, dari 0 hingga 20.
Name
relief_offset_mm
Type
number
default 0
Description
Seberapa jauh untuk menurunkan relief, dalam milimeter, dari 0 hingga 20. Meshy mengurangkannya dari tinggi relief di seluruh bagian, hingga ke alas.
Name
base_thickness_mm
Type
number
default 0.1
Description
Ketebalan pelat alas datar di belakang relief, dalam milimeter, dari 0 hingga 20.
Name
has_closed_back
Type
boolean
default true
Description
Apakah akan menutup bagian belakang keychain. false membuat bagian belakang terbuka, seperti cangkang.
Name
relief_curve
Type
string
default linear
Description
Kurva yang memetakan nilai depth-map ke tinggi relief.
Nilai yang tersedia:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
default 1.0
Description
Kekuatan kurva, hingga 10. Kurva gamma dan s-curve menggunakannya, sedangkan linear mengabaikannya. 0 menggunakan nilai default.
Name
invert_depth
Type
boolean
default false
Description
Apakah akan membalik depth map, sehingga area yang lebih gelap menjadi relief yang lebih tinggi.
Name
smoothing
Type
number
default 0.24
Description
Seberapa banyak depth map dihaluskan sebelum Meshy membangun relief, dari 0 hingga 10.
Name
relief_scale
Type
number
default 1.0
Description
Seberapa besar relief dan teksturnya diperbesar di dalam garis luar, dari titik tengah, hingga 10. Nilai di atas 1 memperbesar subjek, dan nilai di bawah 1 memperkecilnya. Ini tidak mengubah tinggi relief. 0 menggunakan nilai default.
Name
depth_threshold
Type
number
default 0.1
Description
Nilai depth-map di bawah mana Meshy menetapkan kedalaman menjadi nol, dari 0 hingga 1.
Name
remove_background
Type
boolean
default true
Description
Apakah akan menelusuri garis luar keychain dari subjek, sehingga keychain mengikuti bentuk subjek. false menggunakan garis luar badge_shape sebagai gantinya. Meshy juga menggunakan badge_shape saat tidak dapat menemukan garis luar subjek.
Ini terpisah dari parameter remove_background prototipe, yang menetapkan apakah gambar prototipe memiliki latar belakang transparan.
Name
export_resolution
Type
integer
default 512
Description
Resolusi mesh dari model yang diekspor, dari 64 hingga 512. Meshy membangun geometri dari depth map 512-piksel, sehingga mesh yang lebih halus akan menambah permukaan tanpa menambah detail. 0 menggunakan nilai default.

`output`

Opsional. Menetapkan format file yang dikembalikan oleh build.

Name
format
Type
string
default glb
Description
Format file yang dikembalikan oleh build.
Nilai yang tersedia:
- glb: satu file model.glb, di model_urls.glb
- obj: file zip berisi model.obj, model.mtl, dan texture.png, di model_urls.obj
- zip: file zip berisi setiap file yang dihasilkan Meshy, di model_urls.bundle_zip

Returns

Kolom result menyimpan ID dari tugas build yang baru. Ambil tugas atau streaming hingga status bernilai SUCCEEDED. Kemudian unduh file dari satu entri di model_urls.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Misalnya:
- input_task_id hilang atau bukan ID tugas yang valid.
- Status tugas prototipe bukan SUCCEEDED. Jika masih berjalan, tunggu dan coba lagi. Jika gagal atau dibatalkan, buat tugas prototipe baru.
- Tugas prototipe berhasil tetapi tidak memiliki gambar. Buat tugas prototipe baru.
- Kolom options berada di luar rentangnya atau bukan nilai yang tersedia.
Pesan error menunjukkan masalah apa yang ditemukan.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Salah satu dari hal berikut berlaku:
- Akun tidak memiliki cukup kredit.
- Kunci API, ruang kerja, atau anggota telah mencapai batas kreditnya.
- Akun menggunakan paket gratis.
Periksa kredit dan paket Anda, lalu coba lagi.
Name
404 - Not Found
Description
input_task_id tidak cocok dengan tugas prototipe Keychain mana pun yang dibuat akun Anda dengan API. Prototipe yang dibuat di aplikasi web juga akan mengembalikan 404. Kirim ID result dari respons pembuatan prototipe.
Name
429 - Too Many Requests
Description
Salah satu batas berikut telah tercapai:
- Anda mengirim lebih banyak permintaan daripada yang diizinkan oleh batas laju Anda. Tunggu beberapa detik, lalu coba lagi. Lihat Rate limits.
- Terlalu banyak tugas Anda yang sedang antre atau berjalan. Tunggu hingga beberapa selesai, lalu coba lagi.
- Pada paket tak terbatas tanpa sisa kredit, Anda telah mencapai jumlah tugas yang dapat berjalan tanpa kredit. Tunggu hingga satu tugas selesai, atau tambahkan kredit.

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

Mengambil tugas Keychain

Mengembalikan tugas prototype atau build. Jalur (path) harus sesuai dengan tahap tugas tersebut. Tugas build yang diminta melalui /prototype/:id akan mengembalikan 404, begitu pula tugas prototype yang diminta melalui /build/:id.

Untuk kolom-kolomnya, lihat Objek tugas prototype Keychain dan Objek tugas build Keychain.

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Parameter

Name
id
Type
path
Description
ID tugas dari respons pembuatan.

Hasil

Objek tugas prototype atau objek tugas build, sesuai dengan tahap pada jalur (path).

Mode kegagalan

Name
400 - Bad Request
Description
id bukan ID tugas yang valid. Kirim ID result dari respons pembuatan.
Name
403 - Forbidden
Description
Tim Anda mengaktifkan IP Filtering, dan Meshy menandai gambar tugas prototype tersebut karena masalah kekayaan intelektual pihak ketiga. Tugas build dan tim pada paket Enterprise tidak mengalami error ini. Buat tugas prototype dari gambar yang hak penggunaannya Anda miliki.
Name
404 - Not Found
Description
Tidak ada tugas Keychain dengan ID ini yang dimiliki akun Anda, atau tahap tugas tidak sesuai dengan jalur (path). Periksa ID-nya, dan gunakan /prototype atau /build yang sesuai dengan tugas tersebut.
Name
500 - Internal Server Error
Description
Meshy tidak dapat menjalankan pemeriksaan kekayaan intelektual. Coba lagi permintaannya.

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

Menghapus tugas Keychain

Membatalkan tugas Keychain. Membatalkan tugas PENDING akan mengembalikan kreditnya. Tugas IN_PROGRESS dibatalkan tanpa pengembalian dana, karena worker sudah mulai mengerjakannya. Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak dapat dibatalkan.

Path harus sesuai dengan tahap tugas tersebut. Misalnya, DELETE pada /prototype/:id dengan ID tugas build akan mengembalikan 404.

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

Parameter path

Name
id
Type
path
Description
ID dari tugas yang akan dibatalkan.

Returns

204 No Content dengan body kosong.

Mode kegagalan

Name
400 - Bad Request
Description
Salah satu dari berikut ini berlaku:
- id bukan ID tugas yang valid. Kirim ID result dari respons pembuatan.
- Tugas sudah memiliki status akhir (SUCCEEDED, FAILED, atau CANCELED), sehingga tidak dapat dibatalkan.
Name
404 - Not Found
Description
Tidak ada tugas Keychain dengan ID ini yang dimiliki akun Anda, atau tahap tugas tidak sesuai dengan path. Periksa ID, dan gunakan /prototype atau /build yang sesuai dengan tugas tersebut.

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

Melakukan streaming tugas Keychain

Melakukan streaming pembaruan tugas Keychain sebagai Server-Sent Events (SSE). Path harus sesuai dengan tahap tugas tersebut. Jika tidak, misalnya ID tugas build di /prototype/:id/stream, stream akan mengirim satu event error dengan status_code: 404 lalu ditutup.

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Parameter

Name
id
Type
path
Description
ID tugas dari respons pembuatan.

Returns

Sebuah stream objek tugas prototype atau build. Setiap event memiliki objek tugas lengkap, seperti yang dikembalikan oleh Get a Keychain task. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom output-nya masih kosong (null, [], atau {}), dan finished_at bernilai null.

Jika IP Filtering memblokir hasil tugas, stream akan mengirim satu event error sebagai gantinya, dengan status_code yang sama seperti yang akan dikembalikan oleh permintaan get.

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

List tugas Keychain

Mengembalikan tugas Keychain Anda untuk satu tahap, satu halaman dalam satu waktu. Path menentukan tahapnya. /prototype hanya mengembalikan tugas prototype, dan /build hanya mengembalikan tugas build.

Request

GET

/openapi/creative-lab/keychain/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Parameter path

Name
stage
Type
path
Wajib
Description
Tahap yang akan ditampilkan, prototype atau build.

Parameter query

Name
page_num
Type
integer
default 1
Description
Halaman yang akan dikembalikan, dari 1 sampai 255. 0 mengembalikan halaman pertama. Nilai di luar 0 sampai 255 akan mengembalikan 400.
Name
page_size
Type
integer
default 10
Description
Jumlah tugas per halaman, hingga 100. Nilai dari 101 sampai 255 akan mengembalikan 100 tugas, dan 0 menggunakan nilai default. Nilai di luar 0 sampai 255 akan mengembalikan 400.
Name
sort_by
Type
string
default -created_at
Description
Urutan pengurutan.
Nilai yang tersedia:
- -created_at: terbaru lebih dulu
- +created_at: terlama lebih dulu

Returns

Sebuah array berisi objek tugas prototype atau objek tugas build, sesuai dengan tahap pada path.

Objek tugas prototype Keychain

Sebuah tugas prototype menghasilkan gambar konsep berwarna dari sebuah foto. Untuk mengubah gambar tersebut menjadi model 3D, kirimkan ID tugas tersebut ke endpoint build sebagai input_task_id.

Properti

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
ID tugas. Jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, selalu creative-lab-keychain-prototype.
Name
name
Type
string
Description
name yang Anda kirim saat membuat tugas, atau "" jika Anda tidak mengirimkannya.
Name
name_text
Type
string
Description
Nama yang ditambahkan Meshy ke gantungan kunci, setelah merapikan spasi dan menghapus karakter format tak terlihat. Dihilangkan jika Anda tidak mengirim name_text. Untuk memeriksa apakah klien HTTP Anda mengenkode teks dengan benar, bandingkan dengan teks yang Anda kirim.
Name
status
Type
string
Description
Status tugas.
Nilai yang tersedia:
- PENDING: menunggu dalam antrean
- IN_PROGRESS: sedang menghasilkan hasil
- SUCCEEDED: final, dengan hasil
- FAILED: final, dengan alasan di task_error
- CANCELED: final, tanpa hasil
Name
progress
Type
integer
Description
Persentase pekerjaan yang selesai, dari 0 hingga 100. Nilainya 0 sampai tugas dimulai dan 100 ketika berhasil.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
started_at
Type
timestamp
Description
Waktu sebuah worker memulai tugas, dalam milidetik Unix. null sampai saat itu.
Name
finished_at
Type
timestamp
Description
Waktu tugas mencapai status final, dalam milidetik Unix. null sampai saat itu.
Name
expires_at
Type
timestamp
Description
Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 3 hari setelah finished_at, atau 3 hari setelah created_at sampai tugas selesai. Untuk akun Enterprise, yang menyimpan hasil API tanpa batas waktu, nilainya sekitar 100 tahun kemudian. Lihat Asset retention.
Name
preceding_tasks
Type
integer
Description
Posisi tugas dalam antrean selama statusnya PENDING. 1 berarti tugas ini akan dimulai berikutnya. 0 setelah tugas keluar dari antrean, dan selalu 0 dalam hasil daftar.
Name
task_error
Type
object
Description
Alasan tugas gagal. null kecuali status adalah FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikenakan untuk tugas, setelah dikurangi pengembalian dana jika ada. Permintaan yang mengembalikan kesalahan tidak akan dikenakan biaya. Tugas yang gagal bernilai 0, karena Meshy mengembalikan dananya. Membatalkan tugas hanya mengembalikan dana selama tugas masih PENDING. Jika Meshy tidak dapat membaca biaya yang dikenakan, respons get atau stream akan menghilangkan field ini, dan permintaan daftar akan mengembalikan 500. Dalam kasus ini, coba ulangi permintaannya.
Name
image_urls
Type
array of strings
Description
URL unduhan untuk gambar konsep. Array ini memiliki satu URL setelah tugas berhasil, dan kosong sebelum itu.

Objek tugas pembuatan (build task) Keychain

Sebuah build task menghasilkan gantungan kunci 3D dari prototype task yang berhasil (succeeded). Tugas ini mengembalikan satu file model dalam format yang Anda minta.

Properti

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Name
id
Type
string
Description
ID tugas. Jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, selalu creative-lab-keychain-build.
Name
name
Type
string
Description
name yang Anda kirim saat membuat tugas, atau "" jika Anda tidak mengirimkannya.
Name
status
Type
string
Description
Status tugas tersebut.
Nilai yang tersedia:
- PENDING: menunggu dalam antrean
- IN_PROGRESS: sedang menghasilkan hasilnya
- SUCCEEDED: final, dengan hasilnya
- FAILED: final, dengan alasan pada task_error
- CANCELED: final, tanpa hasil
Name
progress
Type
integer
Description
Persentase pekerjaan yang telah selesai, dari 0 hingga 100. Nilainya 0 sampai tugas dimulai dan 100 saat berhasil.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
started_at
Type
timestamp
Description
Waktu sebuah worker memulai tugas, dalam milidetik Unix. null sampai saat itu.
Name
finished_at
Type
timestamp
Description
Waktu tugas mencapai status final, dalam milidetik Unix. null sampai saat itu.
Name
expires_at
Type
timestamp
Description
Waktu hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 3 hari setelah finished_at, atau 3 hari setelah created_at sampai tugas selesai. Untuk akun Enterprise, yang menyimpan hasil API tanpa batas waktu, nilainya sekitar 100 tahun kemudian. Lihat Retensi aset.
Name
preceding_tasks
Type
integer
Description
Posisi tugas dalam antrean selagi berstatus PENDING. 1 berarti tugas ini akan dimulai berikutnya. 0 setelah tugas keluar dari antrean, dan selalu 0 pada hasil daftar (list).
Name
task_error
Type
object
Description
Alasan kegagalan tugas. null kecuali status adalah FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikenakan untuk tugas tersebut, setelah dikurangi pengembalian dana (refund) apa pun. Permintaan yang mengembalikan kesalahan tidak dikenakan biaya. Tugas yang gagal bernilai 0, karena Meshy mengembalikan dananya. Pembatalan hanya mengembalikan dana sebuah tugas selagi berstatus PENDING. Jika Meshy tidak dapat membaca biaya yang dikenakan, respons get atau stream akan menghilangkan field ini, dan permintaan list akan mengembalikan 500. Dalam kasus ini, coba ulangi permintaan tersebut.
Name
model_urls
Type
object
Description
URL unduhan untuk file model, dengan satu entri untuk output.format yang Anda minta. {} sampai tugas berhasil.
- Name
  glb
  Type
  string
  Description
  URL unduhan untuk file GLB. Ada ketika output.format adalah glb.
- Name
  obj
  Type
  string
  Description
  URL unduhan untuk file zip berisi model.obj, model.mtl, dan texture.png. Ada ketika output.format adalah obj.
- Name
  bundle_zip
  Type
  string
  Description
  URL unduhan untuk file zip berisi semua file yang dihasilkan Meshy. Ada ketika output.format adalah zip.