Retexture API adalah fitur yang memungkinkan Anda untuk mengintegrasikan kemampuan retexturing AI dari Meshy ke dalam aplikasi Anda sendiri. Dalam bagian ini, Anda akan menemukan semua informasi yang Anda butuhkan untuk memulai dengan API ini.
Endpoint ini memungkinkan Anda membuat task Retexture baru. Lihat
The Retexture Task Object untuk melihat
properti apa saja yang termasuk dalam objek task Retexture.
Parameter
Hanya salah satu dari input_task_id atau model_url yang wajib. Jika keduanya diberikan, input_task_id akan diprioritaskan.
Name
input_task_id
Type
string
Wajib
Description
ID dari task Image to 3D atau Text to 3D yang telah selesai yang ingin Anda retexture.
Task ini harus merupakan salah satu dari task berikut: Text to 3D Preview, Text to 3D Refine, Image to 3D atau Remesh. Selain itu, task tersebut harus memiliki status SUCCEEDED.
Name
model_url
Type
string
Wajib
Description
Berikan model 3D untuk diberi tekstur oleh Meshy. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl.
Ada dua cara untuk menyediakan model:
URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
Data URI: Data URI model yang dienkode base64. Gunakan MIME type application/octet-stream. Contoh: data:application/octet-stream;base64,<your base64-encoded model data>.
Tepat satu input gaya wajib diisi: text_style_prompt, image_style_url, atau multiview_image_urls. multiview_image_urls tidak dapat digabungkan dengan salah satu dari dua lainnya; jika text_style_prompt dan image_style_url sama-sama diberikan, image_style_url akan diprioritaskan.
Name
text_style_prompt
Type
string
Wajib
Description
Deskripsikan gaya tekstur objek yang diinginkan menggunakan teks. Maksimal 800 karakter.
Name
image_style_url
Type
string
Wajib
Description
Berikan gambar 2d untuk memandu proses pemberian tekstur. Saat ini kami mendukung format .jpg, .jpeg, dan .png.
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>
Pemberian tekstur berbasis gambar mungkin tidak bekerja secara optimal jika terdapat perbedaan geometri yang signifikan antara aset asli dan gambar yang diunggah.
Name
multiview_image_urls
Type
string[]
Wajib
Description
Berikan 1 hingga 4 gambar yang menunjukkan objek yang sama dari sudut pandang berbeda untuk memandu pemberian tekstur. Gambar pertama adalah tampilan utama (depan); urutan tampilan lainnya (kiri, belakang, kanan) tidak menjadi masalah.
Setiap elemen menerima format yang sama dengan image_style_url (URL yang dapat diakses publik atau data URI base64, .jpg/.jpeg/.png).
Memerlukan ai_model: "meshy-7" secara eksplisit.
Name
ai_model
Type
string
default latest
Description
ID model AI yang digunakan untuk retexture. Nilai yang tersedia: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
default false
Description
Pertahankan tata letak UV model yang sudah ada, alih-alih membuat yang baru.
Jika Anda melakukan retexture pada model yang dihasilkan oleh Meshy (melalui input_task_id, atau model_url yang mengarah ke output Meshy), atur ini ke true untuk menggunakan kembali tata letak UV yang telah dioptimalkan.
Jika Anda melakukan retexture pada model pihak ketiga yang Anda unggah, atur true jika model tersebut sudah memiliki UV yang bagus dan ingin dipertahankan, atau biarkan false agar Meshy melakukan unwrap UV baru (paling cocok untuk model yang tidak memiliki pemetaan UV yang tepat).
Name
enable_pbr
Type
boolean
default false
Description
Hasilkan peta PBR (metallic, roughness, normal) selain warna dasar. Peta emisi juga disertakan saat ai_model adalah meshy-6, kecuali pada texture_resolution: 8k. meshy-7 dan latest tidak menghasilkan peta emisi.
Name
texture_resolution
Type
string
default 2k
Description
Resolusi tekstur warna dasar. Salah satu dari 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap lebih banyak detail permukaan.
4k dan 8k memerlukan ai_modelmeshy-6, meshy-7 atau latest. Pada 8k, tidak ada peta emisi yang dihasilkan.
Name
hd_texture
Type
boolean
⚠ usang
default false
Description
Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Jika keduanya diatur, texture_resolution akan diprioritaskan.
Name
remove_lighting
Type
boolean
default true
Description
Menghapus highlight dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih yang bekerja lebih baik pada pengaturan pencahayaan kustom.
Hanya didukung saat ai_model adalah meshy-6.
Name
target_formats
Type
string[]
Description
Menentukan format file 3D mana yang akan disertakan dalam output. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian task. Jika tidak diisi, semua format yang didukung akan disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Jika tidak diisi, semua format kecuali 3mf akan dihasilkan. 3mf hanya disertakan jika ditentukan secara eksplisit.
Name
alpha_thumbnail
Type
boolean
default false
Description
Ketika diatur ke true, task akan tambahan me-render versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Field thumbnail_url yang sudah ada tidak berubah.
Nilai yang Dikembalikan
Properti result pada respons berisi id task dari task Retexture yang baru dibuat.
Mode Kegagalan
Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
Parameter hilang: Salah satu dari model_url atau input_task_id harus disediakan.
Gaya hilang: Salah satu dari text_style_prompt, image_style_url atau multiview_image_urls harus disediakan.
Input gaya yang bertentangan: multiview_image_urls tidak dapat digabungkan dengan text_style_prompt atau image_style_url.
Model tidak didukung untuk multi-tampilan: multiview_image_urls memerlukan ai_model: "meshy-7" secara eksplisit.
Model tidak tersedia: ai_model: "meshy-7" sedang diluncurkan secara bertahap dan belum diaktifkan untuk akun Anda.
Task input tidak valid: input_task_id harus merujuk pada task yang berhasil dari model yang didukung.
Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
URL tidak dapat dijangkau: model_url, image_style_url atau salah satu elemen multiview_image_urls tidak dapat diunduh.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak cukup untuk menjalankan task ini.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Endpoint ini memungkinkan Anda untuk mengambil tugas Retexture dengan memberikan id tugas yang valid.
Lihat Objek Tugas Retexture untuk melihat properti apa saja yang termasuk dalam objek tugas Retexture.
Parameter
Name
id
Type
path
Description
Pengenal unik untuk tugas Retexture yang akan diambil.
Mengembalikan
Respon berisi objek tugas Retexture. Periksa
bagian Objek Tugas Retexture untuk detailnya.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
Objek Tugas Retexture adalah unit kerja yang digunakan Meshy untuk menghasilkan tekstur 3D dari input teks atau gambar.
Model ini memiliki properti sebagai berikut:
Properti
Name
id
Type
string
Description
Pengenal unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan secara k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi tentang format id.
Name
type
Type
string
Description
Jenis tugas Retexture. Nilainya adalah retexture.
Name
model_urls
Type
object
Description
URL yang dapat diunduh untuk file model 3D bertekstur yang dihasilkan oleh Meshy.
Name
glb
Type
string
Description
URL yang dapat diunduh untuk file GLB.
Name
fbx
Type
string
Description
URL yang dapat diunduh untuk file FBX.
Name
obj
Type
string
Description
URL yang dapat diunduh untuk file OBJ.
Name
usdz
Type
string
Description
URL yang dapat diunduh untuk file USDZ.
Name
mtl
Type
string
Description
URL yang dapat diunduh untuk file MTL, dikembalikan bersamaan dengan ekspor OBJ ketika tekstur ada.
Name
stl
Type
string
Description
URL yang dapat diunduh untuk file STL.
Name
3mf
Type
string
Description
URL yang dapat diunduh untuk file 3MF. Hanya ada ketika 3mf diminta melalui target_formats.
Name
text_style_prompt
Type
string
Description
Ini adalah prompt teks yang digunakan untuk membuat tugas tekstur.
Name
image_style_url
Type
string
Description
Ini adalah input gambar yang digunakan untuk membuat tugas tekstur.
Name
multiview_image_urls
Type
string[]
Description
URL yang dapat diunduh untuk gambar referensi multi-tampilan yang digunakan untuk membuat tugas tekstur. Hanya ada ketika tugas dibuat dengan multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk gambar thumbnail dari file model.
Name
alpha_thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk versi latar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, bidang ini dihilangkan.
Name
progress
Type
integer
Description
Kemajuan dari tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, ini akan menjadi 100.
Name
started_at
Type
timestamp
Description
Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.
Stempel waktu mewakili jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339.
Misalnya, Jumat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di Meshy API.
Name
created_at
Type
timestamp
Description
Stempel waktu saat tugas dibuat, dalam milidetik.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Sebuah array dari objek URL tekstur yang dihasilkan dari tugas. Biasanya ini hanya berisi satu objek URL tekstur. Setiap URL tekstur memiliki properti sebagai berikut:
Name
base_color
Type
string
Description
URL yang dapat diunduh untuk gambar peta warna dasar.
Name
metallic
Type
string
Description
URL yang dapat diunduh untuk gambar peta metalik.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
normal
Type
string
Description
URL yang dapat diunduh untuk gambar normal map.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
roughness
Type
string
Description
URL yang dapat diunduh untuk gambar peta kekasaran.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
emission
Type
string
Description
URL yang dapat diunduh untuk gambar peta emisi.
Jika tugas dibuat dengan enable_pbr: false, atau ai_model adalah meshy-5, properti ini akan dihilangkan.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas sebelumnya.
Properti ini hanya ada ketika status tugas adalah PENDING.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan pada kegagalan).
Contoh Model Tugas Retexture
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}