Creative Lab — Keychain API

Ubah foto sumber menjadi medali gantungan kunci yang siap dicetak 3D — sebuah relief kedalaman berwarna berbentuk lencana — dalam dua tahap: prototype menghasilkan gambar konsep berwarna dari foto input Anda, kemudian build mengubah gambar konsep tersebut menjadi model 3D relief. Kedua tahap tersebut dihubungkan melalui input_task_id.

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

Create a Keychain Prototype Task

Menghasilkan satu gambar konsep berwarna dari foto sumber. ID tugas yang dikembalikan adalah yang Anda berikan sebagai input_task_id ke endpoint build. Lihat The Keychain Prototype Task Object untuk bentuk responsnya.

Parameter

  • Name
    image_url
    Type
    string
    Wajib
    Description

    Foto sumber bagi Meshy untuk diwarnai menjadi gambar konsep siap-gantungan-kunci. Kami saat ini 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 dikodekan base64. Contoh data URI: data:image/jpeg;base64,<data gambar Anda yang dikodekan base64>.
  • Name
    name
    Type
    string
    Description

    Nama tugas opsional untuk keperluan tampilan. Maksimal 100 karakter.

    Ini memberi label pada tugas di dasbor dan daftar tugas Anda. Ini bukan yang terukir pada gantungan kunci — gunakan name_text untuk itu.

  • Name
    name_text
    Type
    string
    Description

    Teks untuk diukir pada gantungan kunci, seperti nama hewan peliharaan atau seseorang. Maksimal 10 karakter, dihitung sebagai karakter Unicode dan bukan byte, sehingga nama berbahasa Tionghoa, Jepang, atau Korea dengan 10 karakter dapat diterima. Kosongkan untuk menghasilkan gantungan kunci tanpa ukiran.

    Spasi di sekitarnya dipangkas dan karakter pemformatan yang tidak terlihat dihapus sebelum teks digunakan. Nilai hasilnya dikembalikan sebagai name_text pada prototype task object, sehingga Anda dapat memastikan dengan tepat apa yang akan diukir sebelum membayar untuk tahap build.

    Ukiran diterapkan di sini, pada tahap prototipe. Tahap build mewarisinya secara otomatis dan tidak menerima name_text miliknya sendiri.

    Ketika teks bukan ASCII biasa, kirim isi permintaan sebagai UTF-8 dan atur Content-Type: application/json; charset=utf-8. Beberapa klien HTTP — termasuk Invoke-RestMethod pada Windows PowerShell — mengkodekan isi permintaan sebagai ISO-8859-1 secara default, yang secara diam-diam mengubah setiap karakter non-Latin menjadi ? sebelum mencapai Meshy. API tidak dapat membedakannya dari ukiran yang sebenarnya Anda minta.

  • Name
    remove_background
    Type
    boolean
    default false
    Description

    Ketika disetel ke true, gambar prototipe dikembalikan sebagai PNG RGBA transparan dengan latar belakang dihapus, sehingga Anda dapat menggabungkan subjek ke latar belakang apa pun.

    Ini hanya mengontrol gambar yang dikembalikan oleh endpoint ini. Ini terpisah dari opsi build dengan nama yang sama (default true), yang mengontrol penghapusan latar belakang sebelum reliefing.

Returns

Properti result dari respons berisi id tugas dari tugas prototipe gantungan kunci yang baru dibuat. Poll endpoint Get a Task atau berlangganan stream hingga tugas mencapai SUCCEEDED, lalu berikan ID tersebut ke endpoint build sebagai input_task_id.

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 dijangkau: image_url tidak dapat diunduh (404 atau timeout).
    • Data URI tidak valid: String base64 tidak berbentuk benar.
    • Ukiran terlalu panjang: name_text lebih panjang dari 10 karakter. Permintaan ditolak alih-alih dipotong, sehingga Anda tidak akan pernah dikenakan biaya untuk gantungan kunci berukir nama yang dipersingkat.
    • Konten ditandai: Gambar input ditandai oleh moderation NSFW atau kekayaan intelektual, atau ukiran name_text ditandai oleh moderation NSFW. Ukiran hanya disaring untuk konten NSFW — penyaringan kekayaan intelektual berlaku untuk gambar.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak cukup untuk melakukan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju Anda.

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
Mulai dengan foto sumber, lalu hasilkan gambar prototipe yang digunakan oleh tahap build gantungan kunci.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain prototype output generated from the source photo
Prototype output
POST/openapi/creative-lab/keychain/v1/build

Membuat Task Build Keychain

Menghasilkan medali gantungan kunci final yang siap cetak 3D dari task prototipe yang berhasil. Build menjalankan pipeline relief depth-map pada gambar konsep berwarna dari prototipe dan menghasilkan satu artefak mesh dalam format yang Anda minta. Lihat The Keychain Build Task Object untuk bentuk respons.

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID task dari sebuah task prototipe yang dibuat melalui endpoint OpenAPI yang sama. Prototipe tersebut harus dibuat dengan kunci API yang sama, harus telah mencapai status SUCCEEDED, dan harus telah menghasilkan tepat satu gambar kandidat.

    Task prototipe yang dibuat melalui webapp tidak diterima — endpoint build hanya menerima task prototipe yang dihasilkan oleh POST /openapi/creative-lab/keychain/v1/prototype dan menolak sumber lain mana pun dengan 404.

  • Name
    name
    Type
    string
    Description

    Nama task opsional untuk keperluan tampilan. Maksimum 100 karakter.

options

Parameter penyetelan opsional untuk geometri relief. Setiap field memiliki nilai default yang wajar — kirim hanya field yang ingin Anda timpa.

  • Name
    badge_shape
    Type
    string
    default circle
    Description

    Siluet garis luar dari medali gantungan kunci. Nilai yang tersedia:

    • circle (default)
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    default 40
    Description

    Panjang sisi kotak pembatas gantungan kunci, dalam milimeter. Rentang: (0, 400].

  • Name
    relief_height_mm
    Type
    number
    default 2.2
    Description

    Tinggi maksimum relief di atas dasar, dalam milimeter. Rentang: [0, 20].

  • Name
    relief_offset_mm
    Type
    number
    default 0
    Description

    Offset vertikal yang diterapkan pada relief sebelum ekstrusi, dalam milimeter. Rentang: [0, 20].

  • Name
    base_thickness_mm
    Type
    number
    default 0.1
    Description

    Ketebalan pelat dasar rata di belakang relief, dalam milimeter. Rentang: [0, 20].

  • Name
    has_closed_back
    Type
    boolean
    default true
    Description

    Apakah bagian belakang medali disegel sebagai permukaan tertutup. Setel ke false untuk cangkang terbuka.

  • Name
    relief_curve
    Type
    string
    default linear
    Description

    Kurva transfer yang memetakan nilai depth-map ke tinggi relief. Nilai yang tersedia:

    • linear (default)
    • gamma
    • s-curve
  • Name
    curve_param
    Type
    number
    default 1.0
    Description

    Parameter bentuk untuk kurva transfer (hanya berpengaruh saat relief_curve adalah gamma). Rentang: (0, 10].

  • Name
    invert_depth
    Type
    boolean
    default false
    Description

    Membalik interpretasi depth-map sehingga area yang lebih gelap menjadi relief yang lebih tinggi.

  • Name
    smoothing
    Type
    number
    default 0.24
    Description

    Kekuatan penghalusan yang diterapkan pada depth map sebelum ekstraksi relief. Rentang: [0, 10].

  • Name
    relief_scale
    Type
    number
    default 1.0
    Description

    Pengganda skala vertikal yang diterapkan di atas relief_height_mm. Rentang: (0, 10].

  • Name
    depth_threshold
    Type
    number
    default 0.1
    Description

    Ambang batas low-pass untuk nilai depth-map; nilai di bawah ini akan dijepit ke nol. Rentang: [0, 1].

  • Name
    remove_background
    Type
    boolean
    default true
    Description

    Secara otomatis menghapus latar belakang gambar konsep prototipe sebelum proses reliefing.

    Berbeda dari parameter prototipe dengan nama yang sama (default false), yang mengatur apakah gambar prototipe itu sendiri dikembalikan dengan transparansi.

  • Name
    export_resolution
    Type
    integer
    default 512
    Description

    Resolusi mesh yang digunakan untuk ekspor. Rentang: [64, 2048].

output

Pemilih format keluaran opsional. Default ke glb.

  • Name
    format
    Type
    string
    default glb
    Description

    Bundel artefak yang dikembalikan oleh build. Nilai yang tersedia:

    • glb (default) — mengembalikan satu model.glb di bawah model_urls.glb.
    • obj — mengompres model.obj + model.mtl + texture.png menjadi zip dan mengembalikan bundel tersebut di bawah model_urls.obj.
    • zip — mengompres setiap artefak yang dihasilkan generator menjadi zip dan mengembalikan bundel tersebut di bawah model_urls.bundle_zip.

Returns

Properti result pada respons berisi id task dari task build gantungan kunci yang baru dibuat. Poll endpoint Get a Task atau berlangganan stream hingga task mencapai status SUCCEEDED, lalu unduh artefak dari satu entri di model_urls.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter yang hilang: input_task_id wajib diisi.
    • UUID tidak valid: input_task_id bukan UUID yang valid.
    • Induk belum berhasil: Task prototipe yang dirujuk belum mencapai status SUCCEEDED.
    • Tidak ada kandidat: Task prototipe berhasil tetapi tidak menghasilkan gambar kandidat.
    • Options di luar rentang: Salah satu field options berada di luar rentang atau set enum yang diizinkan.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak cukup untuk melakukan task ini.

  • Name
    404 - Not Found
    Description

    Task prototipe yang dirujuk tidak ada, milik pengguna lain, atau dibuat melalui webapp (hanya task prototipe mode API yang dapat dirangkaikan ke build).

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju Anda.

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
Task build mengubah gambar prototipe yang dipilih menjadi model gantungan kunci yang siap cetak 3D.
Creative Lab Keychain build model preview
Build model preview
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Ambil Task Keychain

Ambil task prototype atau build berdasarkan id task yang valid. Path URL harus sesuai dengan tahap task tersebut — task build yang diambil melalui /prototype/:id akan mengembalikan 404, dan sebaliknya.

Lihat The Keychain Prototype Task Object dan The Keychain Build Task Object untuk bentuk responsnya.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk task gantungan kunci yang akan diambil.

Returns

Respons berisi objek task gantungan kunci. Bentuknya bergantung pada tahap mana yang diminta.

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Delete a Keychain Task

Membatalkan tugas gantungan kunci. Jika tugas masih PENDING, kredit yang digunakan saat pembuatan akan dikembalikan. Tugas yang sudah IN_PROGRESS akan dibatalkan tanpa pengembalian kredit (worker mungkin sudah menggunakan sumber daya). Tugas yang sudah mencapai status akhir (SUCCEEDED, FAILED, CANCELED) tidak dapat dibatalkan.

Jalur URL harus sesuai dengan tahap tugas — DELETE pada /prototype/:buildId akan mengembalikan 404.

Parameter Path

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas gantungan kunci yang akan dibatalkan.

Returns

Mengembalikan 204 No Content jika berhasil dengan isi kosong.

Failure Modes

  • Name
    400 - Bad Request
    Description

    Tugas sudah berada dalam status akhir dan tidak dapat dibatalkan.

  • Name
    404 - Not Found
    Description

    Tugas tidak ada, dimiliki oleh pengguna lain, atau tahapnya tidak sesuai dengan jalur URL.

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).
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Streaming Tugas Keychain

Melakukan streaming pembaruan secara real-time untuk tugas gantungan kunci melalui Server-Sent Events (SSE). Path URL harus sesuai dengan tahap tugas — membuka stream di /prototype/:buildId/stream akan mengeluarkan satu payload event: error dengan status_code: 404 dan menutup stream tersebut.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas gantungan kunci yang akan di-streaming.

Returns

Mengembalikan stream objek tugas Keychain Prototype atau Keychain Build sebagai Server-Sent Events. Setiap frame membawa objek tugas lengkap untuk tahap tersebut — bentuk yang sama dengan yang dikembalikan oleh endpoint Get — sehingga selama tugas berstatus PENDING atau IN_PROGRESS, kolom output tersebut memang belum terisi (null, [] atau {}) dan finished_at bernilai null.

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 PENDING frame below is abbreviated 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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
GET/openapi/creative-lab/keychain/v1/(prototype|build)

List Keychain Tasks

Ambil daftar tugas gantungan kunci Anda dengan paginasi untuk satu tahap. Path URL memilih tahap — /prototype mengembalikan tugas prototype; /build mengembalikan tugas build. Tugas dari tahap lainnya tidak disertakan dalam respons mana pun.

Path Parameters

  • Name
    stage
    Type
    path
    Wajib
    Description

    Salah satu dari prototype atau build. Koleksi hanya mengembalikan tugas yang tahapnya sesuai dengan URL — mengambil /prototype tidak akan pernah mengembalikan tugas build, dan sebaliknya.

Query Parameters

  • 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 yang digunakan untuk pengurutan. Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.

Returns

Mengembalikan daftar objek tugas per-tahap dengan paginasi — baik objek tugas prototype gantungan kunci saat menampilkan daftar /prototype atau objek tugas build gantungan kunci saat menampilkan daftar /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=***"
    ]
  }
]

The Keychain Prototype Task Object

Objek Keychain Prototype Task adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan concept image berwarna dari foto sumber. Output dari tahap ini dirangkai ke tahap build melalui input_task_id.

Properties

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan secara-k (k-sortable) sebagai detail implementasi untuk id task, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis task. Nilainya adalah creative-lab-keychain-prototype.

  • Name
    name
    Type
    string
    Description

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

  • Name
    name_text
    Type
    string
    Description

    Ukiran yang diterapkan pada gantungan kunci ini, setelah dipangkas dan karakter format tidak terlihat dihapus. Tidak ada jika task dibuat tanpa name_text. Bandingkan dengan yang Anda kirim untuk memastikan teks tersebut tetap utuh setelah proses encoding klien HTTP Anda.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Progress task. Jika task belum dimulai, properti ini akan menjadi 0. Setelah task berhasil, ini akan menjadi 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat task dibuat, dalam milidetik.

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

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan menjadi 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil task berakhir masa berlakunya, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang mendahului.

    Nilai field ini hanya bermakna jika status task adalah PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

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

  • Name
    image_urls
    Type
    array of strings
    Description

    URL yang dapat diunduh untuk kandidat concept image yang dihasilkan oleh task prototype ini. Saat ini API selalu mengembalikan tepat satu kandidat; field ini berupa array agar revisi mendatang dapat menampilkan beberapa kandidat tanpa perubahan yang bersifat breaking.

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

Objek Keychain Build Task

Objek Keychain Build Task adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan mesh gantungan kunci 3D final dari sebuah prototype task yang telah berhasil. Build ini menjalankan pipeline depth-map relief pada gambar konsep dari prototype, dan mempublikasikan satu artefak mesh dalam format yang diminta oleh pemanggil.

Properties

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk task.

  • Name
    type
    Type
    string
    Description

    Jenis task. Nilainya adalah creative-lab-keychain-build.

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat task dibuat, dalam milidetik.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat task dimulai, dalam milidetik.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang mendahului. Hanya berarti saat status bernilai PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan oleh task ini. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).

  • Name
    model_urls
    Type
    object
    Description

    URL yang dapat diunduh untuk artefak yang dihasilkan, dengan kunci berdasarkan nama artefak. Selalu berisi tepat satu entri — format yang diminta melalui output.format pada permintaan build. Kunci ini sesuai dengan format yang diminta:

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk file GLB. Muncul saat output.format bernilai glb (default).

    • Name
      obj
      Type
      string
      Description

      URL yang dapat diunduh untuk bundel zip yang berisi model.obj, model.mtl, dan texture.png. Muncul saat output.format bernilai obj.

    • Name
      bundle_zip
      Type
      string
      Description

      URL yang dapat diunduh untuk bundel zip dari setiap artefak yang dihasilkan oleh generator. Muncul saat output.format bernilai zip.

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}