Cara Menggunakan Image to 3D Model API: Panduan Lengkap 2026

API Model Imej ke 3D menukar satu foto kepada model 3D sedia-produksi dalam beberapa saat—tanpa pemodelan manual diperlukan. Pemodelan manual setiap aset adalah perlahan dan mahal, dan untuk studio permainan, aplikasi AR, serta pasukan e-dagang, ia dengan cepat menjadi bottleneck yang melambatkan pelancaran. API model imej ke 3D Meshy menghilangkan geseran itu: hantar imej, tukarkannya kepada model 3D dalam beberapa saat, dan muat turun jejaring bertekstur penuh dalam format seperti GLB, FBX, dan OBJ. Panduan ini membimbing anda melalui keseluruhan aliran kerja—daripada mencipta kunci API hingga memuat turun model pertama anda—dengan kod salin-tampal yang boleh anda jalankan dalam beberapa minit.

Apakah API Model Imej ke 3D?

Pada terasnya, API Model Imej ke 3D ialah titik akhir REST yang dikuasakan oleh AI imej ke model 3D Meshy. Anda menghantar satu imej (JPG, JPEG, atau PNG) sebagai URL awam atau rentetan base64, dan API mengembalikan model 3D bertekstur—termasuk geometri dan tekstur warna asas—dalam format standard seperti GLB, FBX, OBJ, USDZ, STL, dan 3MF. Tambahan pilihan termasuk peta PBR, tekstur sehingga 4K, dan lakaran kecil pratonton pelbagai sudut.

Dikuasakan oleh model Meshy 6 terkini kami, API membolehkan anda mengkonfigurasi topologi dan kiraan poligon, menetapkan mod pose, dan membimbing tekstur dengan gesaan teks atau imej rujukan—sesuai untuk menjana aset untuk permainan, AR/VR, percetakan 3D, dan visualisasi produk.

Apakah yang anda perlukan untuk menggunakan API Imej ke 3D?

Anda tidak memerlukan banyak untuk mengikuti panduan ini. Pastikan anda mempunyai:

• Akaun Meshy — daftar secara percuma jika anda belum ada. Anda akan menjana kunci API anda dari papan pemuka dalam Langkah 1.

• Kunci API — digunakan untuk mengesahkan setiap permintaan. Kami akan membimbing anda mencipta satu, dan anda boleh menggunakan kunci mod ujian percuma untuk mengikuti tanpa menggunakan kredit.

• Imej input — .jpg, .jpeg, atau .png yang jelas dihoskan di URL yang boleh diakses secara awam (atau dikodkan sebagai base64). Latar belakang bersih dan subjek yang kelihatan jelas memberikan hasil terbaik.

• Cara untuk membuat permintaan HTTP — curl (digunakan dalam contoh di bawah), Postman, atau mana-mana pustaka HTTP dalam bahasa pilihan anda. Familiariti asas dengan REST API dan JSON membantu tetapi tidak diperlukan.

Itu sahaja—tiada pengalaman pemodelan 3D diperlukan. Mari kita mulakan.

Cara Menukar Imej kepada Model 3D dengan API (Panduan Langkah demi Langkah)

Langkah 1: Sediakan Tetapan API Anda

Segala yang anda perlukan untuk mula membina terletak di halaman tetapan API. Ini adalah pusat kawalan anda untuk API Meshy, dan ia mempunyai tiga bahagian utama:

• Kunci API — jana dan urus kunci yang mengesahkan permintaan anda.

• Webhook — dapatkan notifikasi secara automatik apabila tugasan anda selesai.

• Penggunaan — jejak baki kredit dan penggunaan API anda dalam masa nyata.

Mari kita lihat setiap satu.

Dapatkan Kunci API Anda

Sebelum membuat sebarang permintaan, anda memerlukan kunci API untuk mengesahkan dengan selamat. Di halaman tetapan API, klik Jana Kunci API. Setiap kunci mengikut format msy-<rentetan-rawak>.

Tip: Setelah dijana, simpan kunci API anda di tempat yang selamat (contohnya, pengurus kata laluan atau pembolehubah persekitaran). Layannya seperti kata laluan—jangan sekali-kali komitkannya ke kawalan sumber atau dedahkannya dalam kod sebelah klien.

Kunci API Mod Ujian

Semasa pembangunan dan pengujian, anda boleh menggunakan kunci API mod ujian untuk meneroka API tanpa menggunakan kredit anda:

msy_dummy_api_key_for_test_mode_12345678

Kunci khas ini mempunyai ciri-ciri berikut:

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

• Tiada kredit digunakan apabila menggunakan kunci ini.

• Semua permintaan yang sah mengembalikan hasil tugasan sampel yang sama, tanpa mengira parameter input.

• Struktur data respons sepadan dengan API pengeluaran dengan tepat.

Ini menjadikannya sempurna untuk menguji integrasi anda sebelum bertukar kepada kunci API sebenar anda.

Sediakan Webhook (Pilihan)

Menjana model 3D mengambil masa, jadi daripada mengundi API berulang kali untuk menyemak sama ada tugasan selesai, anda boleh membiarkan Meshy memberitahu anda sebaik sahaja ia selesai. Itulah kegunaan webhook.

Dalam bahagian Webhook halaman tetapan, tambah URL titik akhir di mana Meshy harus menghantar pemberitahuan peristiwa. Apabila tugasan menukar status (contohnya, apabila ia selesai atau gagal), Meshy menghantar permintaan HTTP POST ke URL anda dengan butiran tugasan dalam muatan.

Tip: Webhook adalah pendekatan yang disyorkan untuk pengeluaran. Ia mengurangkan panggilan API yang tidak perlu dan membolehkan aplikasi anda bertindak balas kepada hasil dalam masa nyata. Untuk ujian pantas, pengundian masih berfungsi dengan baik. Untuk menguji kod webhook secara setempat, halakan ke URL proksi daripada perkhidmatan seperti smee.io.

Cuba Tanpa Kod — API Playground (Pilihan)

Sudah ada Kunci API anda? Sebelum menulis sebarang kod, anda boleh menjalankan tugasan Imej ke 3D sebenar terus dalam pelayar anda.

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

1. Pengesahan — tampal Kunci API anda (msy-xxxxxxxxxx)

2. Imej — muat naik .jpg, .jpeg, atau .png dari komputer anda

3. Tekan Hantar

Playground menghantar tugasan dan mengundi hasil secara automatik. Setelah selesai, anda akan melihat pratonton model 3D dan pautan muat turun terus dalam pelayar — tiada kod diperlukan.

Tip pro: Panel permintaan/ respons mentah di sebelah kanan menunjukkan dengan tepat apa yang API hantar dan kembalikan. Anda boleh menyalin kandungan terus — ambil task_id daripada respons, dan model_urls setelah tugasan selesai. Anda akan menggunakan kedua-duanya dalam langkah seterusnya.

Langkah 2: Hantar Tugasan Imej ke 3D

Dengan kunci API anda sedia, mulakan tugasan 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 mendapat respons seperti ini:

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

Nilai result itu ialah task_id anda — simpannya. Anda akan memerlukannya dalam langkah seterusnya untuk menyemak kemajuan dan mendapatkan model anda.

Pilihan: Untuk mendapatkan notifikasi secara automatik apabila tugasan selesai, tambah medan webhook_url ke badan JSON—contohnya "webhook_url": "https://yourapp.com/webhooks/meshy". Lihat Langkah 3, Pilihan B untuk cara ia berfungsi.

Langkah 3: Dapatkan Hasil Anda

Tugasan anda tidak selesai serta-merta—Meshy memprosesnya di latar belakang. Anda mempunyai dua cara untuk mendapatkan hasil:

Pilihan A: Undi untuk Status (Paling Mudah)

Hantar permintaan GET setiap 5 saat sehingga status bertukar kepada SUCCEEDED:

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

Respons kelihatan 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 medan yang perlu diketahui:

• model_urls mengandungi pautan muat turun untuk setiap format yang dijana. Secara lalai ini termasuk glb, fbx, obj, usdz, stl, dan mtl (fail bahan yang berpasangan dengan obj).

• model_url ialah pintasan ke pautan GLB—berguna apabila GLB sahaja yang diperlukan.

• consumed_credits menunjukkan berapa banyak kredit yang digunakan oleh tugasan (ia 0 untuk tugasan yang gagal, kerana kredit dikembalikan).

• thumbnail_url sentiasa ada dan menunjuk ke lakaran kecil pandangan hadapan.

• thumbnail_urls muncul hanya apabila multi_view_thumbnails: true, dan mengandungi pandangan hadapan, kanan, belakang, dan kiri.

• alpha_thumbnail_url muncul hanya apabila alpha_thumbnail: true, dan mengandungi lakaran kecil latar belakang lutsinar.

Nilai status yang mungkin: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Pilihan B: Webhook (Disyorkan untuk Pengeluaran)

Jika anda menetapkan webhook_url dalam Langkah 2, Meshy akan POST objek tugasan yang telah selesai ke URL anda secara automatik—tiada pengundian diperlukan.

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

💡 Yang mana patut saya gunakan? Pengundian adalah baik untuk prototaip dan tugasan sekali. Gunakan webhook dalam pengeluaran — ia lebih boleh dipercayai dan menjimatkan panggilan API.

Langkah 4: Muat Turun Model 3D Anda

Setelah status adalah SUCCEEDED, ambil URL muat turun daripada model_urls dan muat turun format yang anda perlukan:

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

Bendera -o model.glb menyimpan fail ke direktori kerja semasa anda di bawah nama itu—gunakan laluan penuh (contohnya -o /path/to/model.glb) untuk menyimpannya di tempat lain.

Secara lalai, setiap tugasan mengembalikan GLB, FBX, OBJ, USDZ, STL, dan MTL (fail bahan untuk OBJ). 3MF adalah pilihan masuk—anda hanya mendapatnya apabila anda secara jelas memintanya melalui target_formats (lihat jadual parameter di bawah).

⚠️ Pautan tamat tempoh dalam 3 hari (Pelan Perusahaan mendapat pautan kekal). Muat turun dan simpan model anda dengan segera — pautan tidak akan berfungsi selepas tamat tempoh, dan anda perlu menjalankan semula tugasan.

Bersedia untuk menggunakan model ini dalam alat DCC anda? Lihat panduan Bridge to Blender—Meshy juga mempunyai jambatan untuk Unity, Unreal, Maya, dan lagi.

Bagaimana untuk mendapatkan hasil imej-ke-3D terbaik?

• Gunakan satu subjek yang kelihatan jelas. Satu objek utama, berpusat dan sepenuhnya dalam bingkai, memberikan AI rujukan paling bersih—elakkan pemandangan sibuk, pemotongan berat, dan sudut melampau.

• Utamakan latar belakang yang bersih dan tidak bersepah. Latar belakang pepejal atau ringkas membantu model memisahkan subjek dari persekitarannya.

• Gunakan pencahayaan meresap yang sekata. Bayang keras dan sorotan kuat boleh membakar butiran mengelirukan ke dalam tekstur yang dijana.

• Mulakan dengan imej resolusi tinggi dan tajam. Lebih banyak butiran masuk sama dengan lebih banyak butiran keluar—imej kabur atau resolusi rendah menghasilkan model yang lebih lembut.

Bahasa pengaturcaraan manakah yang boleh saya gunakan dengan API Imej ke 3D?

Mana-mana bahasa yang boleh membuat permintaan HTTP—anda hantar POST dengan JSON dan undi dengan GET. Pilihan biasa:

• Python — gunakan pustaka requests atau httpx

• JavaScript / TypeScript — gunakan fetch (terbina dalam) atau axios

• Go — gunakan net/http daripada pustaka standard

• cURL — bagus untuk ujian pantas dari terminal

Anda juga boleh mencari sampel kod sedia-salin untuk keempat-empat di API Playground.

Berapakah kos kredit untuk tugasan Imej ke 3D?

Kos bergantung pada versi model dan sama ada anda menjana tekstur. Persediaan lalai (meshy-6 dengan tekstur) berharga 30 kredit setiap tugasan:

Tugasan yang gagal dikembalikan secara automatik—consumed_credits mengembalikan 0. Sentiasa semak Harga untuk kadar terkini.

Apakah parameter yang diterima oleh API Imej ke 3D?

Hantar POST ke /openapi/v1/image-to-3d dengan parameter ini: Diperlukan (salah satu):

Pilihan:

Langkah seterusnya dengan API Imej ke 3D

Anda kini mempunyai aliran kerja lengkap: cipta kunci API, hantar imej, undi atau gunakan webhook untuk hasil, kemudian muat turun model anda. Empat langkah yang sama berskala dari prototaip pantas ke saluran paip pengeluaran yang menukar ribuan imej kepada aset 3D secara automatik. Ambil kunci anda dari halaman tetapan API dan hantar model pertama anda hari ini. Lebih suka bermula dari gesaan dan bukannya foto? Gunakan API Model Teks ke 3D.

Soalan Lazim

Bagaimana cara menukar imej kepada model 3D melalui API?

Hantar permintaan POST ke /openapi/v1/image-to-3d dengan image_url dan kunci API anda, kemudian undi tugasan (atau gunakan webhook) sehingga statusnya adalah SUCCEEDED. Respons mengembalikan pautan muat turun untuk model yang dijana. Aliran empat langkah penuh—kunci, hantar, dapatkan, muat turun—diliputi dalam panduan langkah demi langkah di atas.

Apakah format output (STL, GLB, OBJ) yang disokong oleh API?

Setiap tugasan mengembalikan GLB, FBX, OBJ, USDZ, STL, dan MTL secara lalai, dengan 3MF tersedia atas permintaan melalui target_formats. GLB terbaik untuk web dan AR, FBX dan OBJ untuk alat DCC dan enjin permainan, USDZ untuk AR iOS, dan STL untuk percetakan 3D.

Apakah format imej yang boleh saya muat naik?

API Imej ke 3D menyokong imej JPG, JPEG, dan PNG sehingga 100 MB—lebih besar daripada had 20 MB dalam UI Ruang Kerja Meshy. Untuk hasil yang paling tepat, gunakan PNG dengan latar belakang lutsinar atau putih bersih, yang membantu API mengasingkan subjek dan menjana model 3D berkualiti lebih tinggi.

Bolehkah saya mendapatkan model 3D bertekstur daripada API?

Ya. Tekstur diaktifkan secara lalai ("should_texture": true). Untuk menambah peta PBR (metallic, roughness, normal), tetapkan "enable_pbr": true—pada meshy-6/latest ini juga termasuk peta emission. Untuk tekstur warna asas 4K, tetapkan "hd_texture": true (disokong pada meshy-6/latest sahaja; peta PBR kekal pada 2K). Anda juga boleh mengarahkan gaya tekstur dengan texture_prompt atau texture_image_url.

Bolehkah saya menjana model 3D sedia untuk percetakan 3D (STL)?

Ya—STL dijana secara lalai, jadi penukaran imej ke STL 3D tidak memerlukan parameter tambahan: hanya ambil model_urls.stl apabila tugasan selesai. Itu menjadikan aliran kerja imej ke cetakan 3D mudah, kerana STL adalah format standard yang dijangkakan oleh slicer. Jika anda hanya mahu STL, tetapkan "target_formats": ["stl"] untuk melangkau format lain dan mengurangkan masa penjanaan.

Pelan manakah yang termasuk akses API?

Akses API tersedia pada pelan Pro, Studio, dan Enterprise—ia adalah ciri Pro dan ke atas. Pelan Starter percuma tidak termasuk akses API. Lihat Harga untuk butiran.

Berapa lama pautan muat turun sah?

Pautan muat turun sah selama 3 hari pada pelan Pro dan Studio. Pelanggan Enterprise mendapat pautan kekal. Simpan fail anda dengan segera—pautan tamat tempoh tidak boleh dipulihkan, dan anda perlu menjalankan semula tugasan.

Bolehkah saya menjalankan berbilang tugasan pada masa yang sama?

Ya, permintaan serentak disokong. Jika anda menerima ralat 429 Too Many Requests, akaun anda telah mencapai had kadar—laksanakan backoff eksponen dan cuba semula. Lihat halaman Had Kadar untuk had pelan anda.

Tugasan menunjukkan FAILED — apa yang perlu saya lakukan?

Semak task_error.message untuk puncanya. Yang biasa:

Jika isu berterusan, hubungi sokongan Meshy.