Ubah foto sumber menjadi figur 3D koleksi bergaya chibi dalam dua tahap:
prototype menghasilkan gambar konsep bergaya dari foto input Anda, lalu
build mengubah gambar konsep tersebut menjadi model 3D dengan texture. Kedua tahap
ditautkan melalui input_task_id.
Hasilkan satu gambar konsep bergaya chibi dari foto sumber. ID tugas
yang dikembalikan adalah yang Anda teruskan sebagai input_task_id ke endpoint
build. Lihat
Objek Tugas Prototipe Figur
untuk bentuk respons.
Parameter
Name
image_url
Type
string
Wajib
Description
Foto sumber untuk digayakan oleh Meshy sebagai figur chibi. 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 base64. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Nama tugas opsional untuk tujuan tampilan. Maksimum 100 karakter.
Mengembalikan
Properti result dari respons berisi id tugas dari tugas prototipe figur yang baru dibuat. Poll endpoint Dapatkan Tugas atau berlangganan ke stream hingga tugas mencapai SUCCEEDED, lalu teruskan ID tersebut ke endpoint build sebagai input_task_id.
Mode Kegagalan
Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
Parameter tidak ada: image_url wajib diisi.
Format gambar tidak valid: image_url yang disediakan 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 memiliki format yang salah.
Konten ditandai: Gambar input ditandai oleh moderation NSFW atau kekayaan intelektual.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju Anda.
Request
POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept imagecurl https://api.meshy.ai/openapi/creative-lab/figure/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":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Hasilkan figur 3D bertekstur final dari tugas prototipe yang berhasil.
Build menjalankan pipeline gambar-ke-3D yang sama seperti
Gambar ke 3D, sehingga format objek respons dan
daftar URL output sama persis. Lihat
Objek Tugas Build Figur untuk
bentuk respons.
Parameter
Name
input_task_id
Type
string
Wajib
Description
ID tugas dari tugas prototipe yang dibuat melalui endpoint OpenAPI yang sama ini. Prototipe harus dibuat dengan kunci API yang sama, harus telah mencapai SUCCEEDED, dan harus menghasilkan tepat satu gambar kandidat.
Tugas prototipe yang dibuat melalui webapp tidak diterima — endpoint build hanya menerima tugas prototipe yang dihasilkan oleh POST /openapi/creative-lab/figure/v1/prototype dan menolak sumber lain apa pun dengan 404.
Name
name
Type
string
Description
Nama tugas opsional untuk tujuan tampilan. Maksimum 100 karakter.
Mengembalikan
Properti result dari respons berisi id tugas dari tugas build figur yang baru dibuat. Poll endpoint Get a Task atau berlangganan stream hingga tugas mencapai SUCCEEDED, lalu unduh GLB bertekstur dari model_urls.glb (atau pasangan OBJ + MTL dari model_urls.obj dan model_urls.mtl jika pipeline downstream Anda lebih memilih OBJ).
Mode Kegagalan
Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
Parameter hilang: input_task_id wajib diisi.
UUID tidak valid: input_task_id bukan UUID yang valid.
Induk belum berhasil: Tugas prototipe yang dirujuk belum mencapai SUCCEEDED.
Tidak ada kandidat: Tugas prototipe berhasil tetapi tidak menghasilkan gambar kandidat.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk menjalankan tugas ini.
Name
404 - Not Found
Description
Tugas prototipe yang dirujuk tidak ada, milik pengguna lain, atau dibuat melalui webapp (hanya tugas prototipe mode API yang dapat dirangkai ke build).
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju Anda.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Response
{"result":"019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Ambil tugas prototipe atau build dengan id tugas yang valid. Jalur URL
harus cocok dengan tahap tugas — tugas build yang diambil melalui
/prototype/:id mengembalikan 404, dan sebaliknya.
Batalkan tugas figur. Jika tugas masih PENDING, kredit
yang digunakan saat pembuatan akan dikembalikan. Tugas yang sudah
IN_PROGRESS dibatalkan tanpa pengembalian dana (worker mungkin sudah
menghabiskan Sumber Daya). Tugas yang sudah mencapai status terminal
(SUCCEEDED, FAILED, CANCELED) tidak dapat dibatalkan.
Path URL harus cocok dengan tahap tugas — DELETE pada
/prototype/:buildId mengembalikan 404.
Parameter Path
Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas figur yang akan dibatalkan.
Mengembalikan
Mengembalikan 204 No Content saat berhasil dengan body kosong.
Mode Kegagalan
Name
400 - Bad Request
Description
Tugas sudah berada dalam status terminal dan tidak dapat dibatalkan.
Name
404 - Not Found
Description
Tugas tidak ada, milik pengguna yang berbeda, atau tahapnya tidak cocok dengan path URL.
Streaming pembaruan waktu nyata untuk tugas figur melalui Server-Sent Events (SSE).
Path URL harus cocok dengan tahap tugas — membuka stream di
/prototype/:buildId/stream memancarkan satu payload event: error dengan
status_code: 404 dan menutup stream.
Parameter
Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas figur yang akan di-stream.
Mengembalikan
Mengembalikan stream objek tugas Prototipe figur
atau Build figur sebagai
Server-Sent Events. Untuk tugas PENDING atau IN_PROGRESS, stream respons
hanya akan menyertakan field progress dan status yang diperlukan.
Ambil daftar tugas figur Anda yang dipaginasi untuk satu tahap. Path URL
memilih tahap — /prototype mengembalikan tugas prototype; /build
mengembalikan tugas build. Tugas dari tahap lain tidak disertakan dalam
respons mana pun.
Parameter Path
Name
stage
Type
path
Wajib
Description
Salah satu dari prototype atau build. Koleksi hanya mengembalikan tugas
yang tahapnya cocok dengan URL — mengambil /prototype tidak pernah mengembalikan
tugas build dan sebaliknya.
Parameter Query
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 50 item.
Name
sort_by
Type
string
default -created_at
Description
Field untuk pengurutan. Nilai yang tersedia:
+created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
-created_at: Urutkan berdasarkan waktu pembuatan secara menurun.
Objek Tugas Prototipe figur adalah unit kerja yang dilacak oleh Meshy untuk
menghasilkan gambar konsep bergaya chibi dari foto sumber. Output dari
tahap ini dirangkai ke tahap build
melalui input_task_id.
Properti
Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id.
Name
type
Type
string
Description
Jenis tugas. Nilainya adalah creative-lab-figure-prototype.
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, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Stempel waktu saat tugas dibuat, dalam milidetik.
Sebuah 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 tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan bernilai 0.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan bernilai 0.
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 objek task_error lengkap.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada saat status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal).
Name
image_urls
Type
array of strings
Description
URL yang dapat diunduh untuk kandidat gambar konsep yang dihasilkan oleh tugas prototipe ini. Saat ini API selalu mengembalikan tepat satu kandidat; bidang ini berupa array agar revisi mendatang dapat menampilkan beberapa kandidat tanpa perubahan yang merusak kompatibilitas.
Objek Tugas Pembuatan Figur adalah unit kerja yang dilacak oleh Meshy untuk
menghasilkan figur 3D dengan texture dari tugas prototipe yang berhasil. Ini
menjalankan pipeline gambar-ke-3D yang sama yang digunakan oleh Gambar ke 3D,
sehingga field output mencerminkan objek tugas endpoint tersebut.
Properti
Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas.
Name
type
Type
string
Description
Jenis tugas. Nilainya adalah creative-lab-figure-build.
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 menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
stempel waktu saat tugas dibuat, dalam milidetik.
Name
started_at
Type
timestamp
Description
stempel waktu saat tugas dimulai, dalam milidetik.
Name
finished_at
Type
timestamp
Description
stempel waktu saat tugas selesai, dalam milidetik.
Name
expires_at
Type
timestamp
Description
stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang mendahului. Hanya bermakna ketika status adalah PENDING.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat gagal).
Name
prompt
Type
string
Description
Selalu kosong untuk pembuatan figur. Hadir untuk kompatibilitas lintas-endpoint dengan bentuk V2ImageTo3DTaskResponse bersama yang digunakan oleh Gambar ke 3D.
Name
negative_prompt
Type
string
Description
Selalu kosong untuk pembuatan figur. Hadir untuk kompatibilitas lintas-endpoint.
Name
texture_prompt
Type
string
Description
Selalu kosong untuk pembuatan figur. Hadir untuk kompatibilitas lintas-endpoint.
Name
texture_image_url
Type
string
Description
Selalu kosong untuk pembuatan figur. Hadir untuk kompatibilitas lintas-endpoint.
Name
model_urls
Type
object
Description
URL yang dapat diunduh untuk model 3D yang dihasilkan. Pembuatan figur menghasilkan GLB bertekstur plus pasangan OBJ + MTL untuk pipeline yang lebih memilih Wavefront OBJ. Bentuk bidang sesuai dengan objek Gambar ke 3D model_urls sehingga penambahan format di masa mendatang dapat masuk tanpa perubahan yang merusak kompatibilitas.
Name
glb
Type
string
Description
URL yang dapat diunduh ke file GLB bertekstur.
Name
obj
Type
string
Description
URL yang dapat diunduh ke file Wavefront OBJ (geometri + UV).
Name
mtl
Type
string
Description
URL yang dapat diunduh ke file material MTL pendamping OBJ. Pasangkan dengan obj dan entri dari texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL yang dapat diunduh ke gambar thumbnail dari file model.
Name
texture_urls
Type
array
Description
Array objek URL tekstur yang dihasilkan oleh tugas ini. Saat ini berisi satu objek dengan peta warna dasar.
Name
base_color
Type
string
Description
URL yang dapat diunduh ke gambar peta warna dasar.