Panduan Lengkap Menggunakan Image to 3D Model API 2026

API Gambar ke Model 3D mengubah satu foto menjadi model 3D siap produksi dalam hitungan detik—tanpa perlu pemodelan manual. Memodelkan setiap aset secara manual itu lambat dan mahal, dan bagi studio game, aplikasi AR, serta tim e-commerce, hal ini dengan cepat menjadi hambatan yang menunda peluncuran. API gambar-ke-model-3D Meshy menghilangkan hambatan itu: kirim gambar, ubah menjadi model 3D dalam hitungan detik, dan unduh jaring bertekstur penuh dalam format seperti GLB, FBX, dan OBJ. Panduan ini memandu Anda melalui seluruh alur kerja—dari membuat kunci API hingga mengunduh model pertama Anda—dengan kode siap salin yang bisa Anda jalankan dalam hitungan menit.

Apa itu API Gambar ke Model 3D?

Pada intinya, API Gambar ke Model 3D adalah titik akhir REST yang didukung oleh AI gambar ke model 3D Meshy. Anda mengirim satu gambar (JPG, JPEG, atau PNG) sebagai URL publik atau string base64, dan API mengembalikan model 3D bertekstur—termasuk geometri dan tekstur warna dasar—dalam format standar seperti GLB, FBX, OBJ, USDZ, STL, dan 3MF. Pengaya opsional termasuk peta PBR, tekstur hingga 4K, dan thumbnail pratinjau multi-sudut.

Didukung oleh model Meshy 6 terbaru kami, API ini memungkinkan Anda mengonfigurasi topologi dan jumlah poligon, mengatur mode pose, serta memandu tekstur dengan perintah teks atau gambar referensi—ideal untuk menghasilkan aset untuk game, AR/VR, pencetakan 3D, dan visualisasi produk.

Apa yang Anda butuhkan untuk menggunakan API Gambar ke 3D?

Anda tidak perlu banyak hal untuk mengikuti panduan ini. Pastikan Anda memiliki:

• Akun Meshy — daftar gratis jika Anda belum memilikinya. Anda akan membuat kunci API dari dasbor di Langkah 1.

• Kunci API — digunakan untuk mengautentikasi setiap permintaan. Kami akan memandu Anda membuatnya, dan Anda dapat menggunakan kunci mode uji coba gratis untuk mengikuti tanpa menghabiskan kredit.

• Gambar masukan — .jpg, .jpeg, atau .png yang jelas yang dihosting di URL yang dapat diakses publik (atau dikodekan sebagai base64). Latar belakang yang bersih dan subjek yang terlihat jelas memberikan hasil terbaik.

• Cara untuk membuat permintaan HTTP — curl (digunakan dalam contoh di bawah), Postman, atau pustaka HTTP apa pun dalam bahasa pilihan Anda. Keakraban dasar dengan REST API dan JSON membantu tetapi tidak wajib.

Itu saja—tidak perlu pengalaman pemodelan 3D. Mari kita mulai.

Cara Mengonversi Gambar menjadi Model 3D dengan API (Panduan Langkah-demi-Langkah)

Langkah 1: Siapkan Pengaturan API Anda

Semua yang Anda butuhkan untuk mulai membangun ada di halaman pengaturan API. Ini adalah pusat kendali Anda untuk API Meshy, dan memiliki tiga bagian utama:

• Kunci API — buat dan kelola kunci yang mengautentikasi permintaan Anda.

• Webhook — dapatkan notifikasi secara otomatis saat tugas Anda selesai.

• Penggunaan — lacak sisa saldo kredit dan konsumsi API Anda secara real-time.

Mari kita bahas satu per satu.

Dapatkan Kunci API Anda

Sebelum membuat permintaan apa pun, Anda memerlukan kunci API untuk mengautentikasi dengan aman. Di halaman pengaturan API, klik Buat Kunci API. Setiap kunci mengikuti format msy-<string-acak>.

Tip: Setelah dibuat, simpan kunci API Anda di tempat yang aman (misalnya, pengelola kata sandi atau variabel lingkungan). Perlakukan seperti kata sandi—jangan pernah menyimpannya di kontrol sumber atau mengeksposnya di kode sisi klien.

Kunci API Mode Uji Coba

Selama pengembangan dan pengujian, Anda dapat menggunakan kunci API mode uji coba untuk menjelajahi API tanpa menghabiskan kredit Anda:

msy_dummy_api_key_for_test_mode_12345678

Kunci khusus ini memiliki karakteristik berikut:

• Dapat digunakan untuk membuat permintaan ke semua titik akhir API Meshy.

• Tidak ada kredit yang digunakan saat menggunakan kunci ini.

• Semua permintaan yang valid mengembalikan hasil tugas sampel yang sama, terlepas dari parameter masukan.

• Struktur data respons sama persis dengan API produksi.

Ini membuatnya sempurna untuk menguji integrasi Anda sebelum beralih ke kunci API asli Anda.

Siapkan Webhook (Opsional)

Menghasilkan model 3D membutuhkan waktu, jadi alih-alih terus-menerus melakukan polling ke API untuk memeriksa apakah suatu tugas selesai, Anda dapat membiarkan Meshy memberi tahu Anda saat tugas selesai. Itulah gunanya webhook.

Di bagian Webhook pada halaman pengaturan, tambahkan URL titik akhir tempat Meshy harus mengirim notifikasi peristiwa. Saat suatu tugas berubah status (misalnya, saat selesai atau gagal), Meshy mengirimkan permintaan HTTP POST ke URL Anda dengan detail tugas di payload.

Tip: Webhook adalah pendekatan yang direkomendasikan untuk produksi. Mereka mengurangi panggilan API yang tidak perlu dan memungkinkan aplikasi Anda bereaksi terhadap hasil secara real-time. Untuk pengujian cepat, polling tetap berfungsi dengan baik. Untuk menguji kode webhook secara lokal, arahkan ke URL proxy dari layanan seperti smee.io.

Coba Tanpa Kode — API Playground (Opsional)

Sudah memiliki Kunci API? Sebelum menulis kode apa pun, Anda dapat menjalankan tugas Gambar ke 3D nyata langsung di browser Anda.

Buka meshy.ai/api-playground, pilih Gambar ke 3D dari panel kiri, dan isi tiga hal:

1. Otorisasi — tempel Kunci API Anda (msy-xxxxxxxxxx)

2. Gambar — unggah .jpg, .jpeg, atau .png dari komputer Anda

3. Tekan Kirim

Playground mengirimkan tugas dan melakukan polling hasil secara otomatis. Setelah selesai, Anda akan melihat pratinjau model 3D dan tautan unduhan langsung di browser — tanpa perlu kode.

Pro tip: Panel permintaan/respons mentah di sebelah kanan menunjukkan dengan tepat apa yang dikirim dan dikembalikan oleh API. Anda dapat menyalin kontennya secara langsung — ambil task_id dari respons, dan model_urls setelah tugas selesai. Anda akan menggunakan keduanya di langkah selanjutnya.

Langkah 2: Kirim Tugas Gambar ke 3D

Dengan kunci API Anda siap, mulailah tugas dengan satu permintaan POST:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Anda akan mendapatkan respons seperti ini:

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

Nilai result itu adalah task_id Anda — simpan. Anda akan membutuhkannya di langkah berikutnya untuk memeriksa kemajuan dan mengambil model Anda.

Opsional: Untuk mendapatkan notifikasi otomatis saat tugas selesai, tambahkan bidang webhook_url ke badan JSON—misalnya "webhook_url": "https://yourapp.com/webhooks/meshy". Lihat Langkah 3, Opsi B untuk cara kerjanya.

Langkah 3: Dapatkan Hasil Anda

Tugas Anda tidak selesai secara instan—Meshy memprosesnya di latar belakang. Anda memiliki dua cara untuk mendapatkan hasilnya:

Opsi A: Polling untuk Status (Paling Sederhana)

Kirim permintaan GET setiap 5 detik hingga status berubah menjadi SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

Responsnya terlihat seperti ini:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Beberapa bidang yang perlu diketahui:

• model_urls berisi tautan unduhan untuk setiap format yang dihasilkan. Secara default ini termasuk glb, fbx, obj, usdz, stl, dan mtl (file material yang berpasangan dengan obj).

• model_url adalah pintasan ke tautan GLB—berguna saat Anda hanya membutuhkan GLB.

• consumed_credits menunjukkan berapa banyak kredit yang digunakan tugas (nilainya 0 untuk tugas yang gagal, karena kredit dikembalikan).

• thumbnail_url selalu ada dan menunjuk ke thumbnail tampak depan.

• thumbnail_urls hanya muncul saat multi_view_thumbnails: true, dan berisi tampak depan, kanan, belakang, dan kiri.

• alpha_thumbnail_url hanya muncul saat alpha_thumbnail: true, dan berisi thumbnail dengan latar belakang transparan.

Kemungkinan nilai status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Opsi B: Webhook (Direkomendasikan untuk Produksi)

Jika Anda menyetel webhook_url di Langkah 2, Meshy akan mengirimkan objek tugas yang selesai ke URL Anda secara otomatis—tanpa perlu polling.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Yang mana yang harus saya gunakan? Polling baik untuk pembuatan prototipe dan tugas satu kali. Gunakan webhook di produksi — lebih andal dan menghemat panggilan API.

Langkah 4: Unduh Model 3D Anda

Setelah status menjadi SUCCEEDED, ambil URL unduhan dari model_urls dan unduh format yang Anda butuhkan:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Bendera -o model.glb menyimpan file ke direktori kerja Anda saat ini dengan nama itu—gunakan jalur lengkap (mis. -o /path/to/model.glb) untuk menyimpannya di tempat lain.

Secara default, setiap tugas mengembalikan GLB, FBX, OBJ, USDZ, STL, dan MTL (file material untuk OBJ). 3MF bersifat opt-in—Anda hanya mendapatkannya saat secara eksplisit memintanya melalui target_formats (lihat tabel parameter di bawah).

⚠️ Tautan kedaluwarsa dalam 3 hari (Paket Perusahaan mendapatkan tautan permanen). Unduh dan simpan model Anda segera — tautan tidak akan berfungsi setelah kedaluwarsa, dan Anda harus menjalankan ulang tugas.

Siap menggunakan model ini di alat DCC Anda? Lihat panduan Bridge ke Blender—Meshy juga memiliki bridge untuk Unity, Unreal, Maya, dan lainnya.

Bagaimana cara mendapatkan hasil gambar-ke-3D terbaik?

• Gunakan satu subjek yang terlihat jelas. Satu objek utama, terpusat dan sepenuhnya dalam bingkai, memberikan referensi paling bersih bagi AI—hindari pemandangan yang sibuk, pemotongan berat, dan sudut ekstrem.

• Pilih latar belakang yang bersih dan tidak berantakan. Latar belakang yang solid atau sederhana membantu model memisahkan subjek dari lingkungannya.

• Gunakan pencahayaan yang merata dan menyebar. Bayangan keras dan sorotan kuat dapat memanggang detail yang menyesatkan ke dalam tekstur yang dihasilkan.

• Mulailah dengan gambar beresolusi tinggi dan tajam. Lebih banyak detail masuk sama dengan lebih banyak detail keluar—input buram atau resolusi rendah menghasilkan model yang lebih lunak.

Bahasa pemrograman apa yang dapat saya gunakan dengan API Gambar ke 3D?

Bahasa apa pun yang dapat membuat permintaan HTTP—Anda mengirim POST dengan JSON dan melakukan polling dengan GET. Opsi umum:

• Python — gunakan pustaka requests atau httpx

• JavaScript / TypeScript — gunakan fetch (bawaan) atau axios

• Go — gunakan net/http dari pustaka standar

• cURL — bagus untuk pengujian cepat dari terminal

Anda juga dapat menemukan contoh kode siap salin untuk keempatnya di API Playground.

Berapa banyak kredit yang diperlukan untuk tugas Gambar ke 3D?

Biaya tergantung pada versi model dan apakah Anda menghasilkan tekstur. Pengaturan default (meshy-6 dengan tekstur) membutuhkan biaya 30 kredit per tugas:

Tugas yang gagal akan dikembalikan secara otomatis—consumed_credits mengembalikan 0. Selalu periksa Harga untuk tarif terbaru.

Parameter apa yang diterima oleh API Gambar ke 3D?

Kirim POST ke /openapi/v1/image-to-3d dengan parameter berikut: Wajib (salah satu):

Opsional:

Langkah selanjutnya dengan API Gambar ke 3D

Anda sekarang memiliki alur kerja lengkap: buat kunci API, kirim gambar, polling atau gunakan webhook untuk hasilnya, lalu unduh model Anda. Empat langkah yang sama dapat diskalakan dari prototipe cepat ke jalur produksi yang secara otomatis mengubah ribuan gambar menjadi aset 3D. Ambil kunci Anda dari halaman pengaturan API dan kirim model pertama Anda hari ini. Lebih suka memulai dari perintah daripada foto? Gunakan API Teks ke Model 3D.

Pertanyaan yang Sering Diajukan

Bagaimana cara mengonversi gambar menjadi model 3D melalui API?

Kirim permintaan POST ke /openapi/v1/image-to-3d dengan image_url dan kunci API Anda, lalu polling tugas (atau gunakan webhook) hingga status-nya menjadi SUCCEEDED. Respons mengembalikan tautan unduhan untuk model yang dihasilkan. Alur empat langkah penuh—kunci, kirim, ambil, unduh—dicakup dalam panduan langkah-demi-langkah di atas.

Format keluaran (STL, GLB, OBJ) apa yang didukung API?

Setiap tugas mengembalikan GLB, FBX, OBJ, USDZ, STL, dan MTL secara default, dengan 3MF tersedia berdasarkan permintaan melalui target_formats. GLB terbaik untuk web dan AR, FBX dan OBJ untuk alat DCC dan mesin game, USDZ untuk AR iOS, dan STL untuk pencetakan 3D.

Format gambar apa yang dapat saya unggah?

API Gambar ke 3D mendukung gambar JPG, JPEG, dan PNG hingga 100 MB—lebih besar dari batas 20 MB di antarmuka Ruang Kerja Meshy. Untuk hasil yang paling akurat, gunakan PNG dengan latar belakang transparan atau putih bersih, yang membantu API mengisolasi subjek dan menghasilkan model 3D berkualitas lebih tinggi.

Bisakah saya mendapatkan model 3D bertekstur dari API?

Ya. Tekstur diaktifkan secara default ("should_texture": true). Untuk menambahkan peta PBR (metalik, kekasaran, normal), setel "enable_pbr": true—pada meshy-6/latest ini juga menyertakan peta emisi. Untuk tekstur warna dasar 4K, setel "hd_texture": true (hanya didukung pada meshy-6/latest; peta PBR tetap 2K). Anda juga dapat mengarahkan gaya tekstur dengan texture_prompt atau texture_image_url.

Bisakah saya menghasilkan model 3D yang siap untuk pencetakan 3D (STL)?

Ya—STL dihasilkan secara default, jadi konversi gambar ke 3D STL tidak memerlukan parameter tambahan: cukup ambil model_urls.stl saat tugas selesai. Itu membuat alur kerja gambar ke cetak 3D menjadi sederhana, karena STL adalah format standar yang diharapkan oleh slicer. Jika Anda hanya menginginkan STL, setel "target_formats": ["stl"] untuk melewati format lain dan mempersingkat waktu pembuatan.

Paket mana yang menyertakan akses API?

Akses API tersedia di paket Pro, Studio, dan Enterprise—ini adalah fitur Pro-ke-atas. Paket Starter gratis tidak menyertakan akses API. Lihat Harga untuk detailnya.

Berapa lama tautan unduhan berlaku?

Tautan unduhan berlaku selama 3 hari pada paket Pro dan Studio. Pelanggan Perusahaan mendapatkan tautan permanen. Simpan file Anda segera—tautan yang kedaluwarsa tidak dapat dipulihkan, dan Anda harus menjalankan ulang tugas.

Bisakah saya menjalankan beberapa tugas secara bersamaan?

Ya, permintaan bersamaan didukung. Jika Anda mendapatkan kesalahan 429 Too Many Requests, akun Anda telah mencapai batas kecepatan—terapkan backoff eksponensial dan coba lagi. Lihat halaman Batas Kecepatan untuk batas paket Anda.

Tugas menunjukkan FAILED — apa yang harus saya lakukan?

Periksa task_error.message untuk penyebabnya. Yang umum:

Jika masalah berlanjut, hubungi dukungan Meshy.