Retexture API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan retexturing AI dari Meshy ke dalam aplikasi Anda sendiri. Dalam bagian ini, Anda akan menemukan semua informasi yang Anda perlukan untuk memulai dengan API ini.
Endpoint ini memungkinkan Anda membuat tugas Retexture baru. Lihat
Objek Tugas Retexture untuk melihat properti apa saja yang termasuk dalam objek tugas Retexture.
Parameter
Hanya satu dari input_task_id atau model_url yang diperlukan. Jika keduanya disediakan, input_task_id memiliki prioritas.
Name
input_task_id
Type
string
Wajib
Description
ID dari tugas Gambar ke 3D atau Teks ke 3D yang telah selesai yang ingin Anda lakukan retexture.
Tugas ini harus berupa salah satu tugas berikut: Teks ke 3D Pratinjau, Teks ke 3D Refinasi, Gambar ke 3D atau Remesh. Selain itu, tugas tersebut harus memiliki status SUCCEEDED.
Name
model_url
Type
string
Wajib
Description
Berikan model 3D untuk di-retexture 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 base64-encoded dari model. Gunakan MIME type application/octet-stream. Contoh: data:application/octet-stream;base64,<your base64-encoded model data>.
Tepat satu input gaya adalah diperlukan: 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 keduanya disediakan, image_style_url memiliki prioritas.
Name
text_style_prompt
Type
string
Wajib
Description
Deskripsikan gaya tekstur yang Anda inginkan dari objek menggunakan teks. Maksimal 600 karakter.
Name
image_style_url
Type
string
Wajib
Description
Berikan gambar 2D untuk memandu proses texturing. Kami saat ini 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 base64-encoded dari gambar. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>
Texturing gambar mungkin tidak berfungsi optimal jika ada perbedaan geometri yang substansial antara asset asli dan gambar yang diunggah.
Name
multiview_image_urls
Type
string[]
Wajib
Description
Berikan 1 hingga 4 gambar yang menunjukkan objek yang sama dari tampilan yang berbeda untuk memandu texturing. Gambar pertama adalah tampilan utama (depan); urutan tampilan yang tersisa (kiri, belakang, kanan) tidak penting.
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" (atau latest).
Name
ai_model
Type
string
default latest
Description
ID model AI yang akan digunakan untuk retexturing. Nilai yang tersedia: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
default false
Description
Menjaga tata letak UV model yang ada daripada menghasilkan yang baru.
Jika Anda melakukan retexture pada model yang dihasilkan oleh Meshy (melalui input_task_id, atau model_url yang mengarah ke output Meshy), setel ini ke true untuk menggunakan kembali tata letak UV yang telah dioptimalkan.
Jika Anda melakukan retexture pada model pihak ketiga yang Anda unggah, setel true ketika sudah memiliki UV yang bagus yang ingin Anda pertahankan, atau biarkan false untuk membiarkan Meshy membuka tata letak UV baru (terbaik untuk model yang tidak memiliki pemetaan UV yang tepat).
Name
enable_pbr
Type
boolean
default false
Description
Menghasilkan Peta PBR (metallic, roughness, normal) selain dari warna dasar. Peta emisi juga disertakan ketika 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, peta emisi tidak dihasilkan.
Name
hd_texture
Type
boolean
⚠ usang
default false
Description
Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Ketika keduanya diatur, texture_resolution akan memiliki prioritas.
Name
remove_lighting
Type
boolean
default true
Description
Menghilangkan sorotan dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih yang bekerja lebih baik dengan pengaturan pencahayaan kustom.
Hanya didukung ketika 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 tugas. Ketika tidak disebutkan, semua format yang didukung disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Ketika tidak disebutkan, semua format kecuali 3mf dihasilkan. 3mf hanya disertakan ketika secara eksplisit disebutkan.
Name
alpha_thumbnail
Type
boolean
default false
Description
Ketika diatur ke true, tugas tambahan akan merender versi latar belakang transparan (RGBA) dari pratinjau dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Kolom thumbnail_url yang ada tidak berubah.
Hasil
Properti result dari respons berisi id tugas dari tugas Retexture yang baru dibuat.
Mode Kegagalan
Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
Parameter yang Hilang: model_url atau input_task_id harus disediakan.
Gaya yang Hilang: Salah satu dari text_style_prompt, image_style_url atau multiview_image_urls harus disediakan.
Input gaya konflik: multiview_image_urls tidak dapat digabungkan dengan text_style_prompt atau image_style_url.
Model tidak didukung untuk multi-tampilan: multiview_image_urls membutuhkan ai_model: "meshy-7" (atau latest).
Model tidak tersedia: ai_model: "meshy-7" sedang diluncurkan secara bertahap dan belum diaktifkan untuk akun Anda.
Tugas input tidak valid: input_task_id harus merujuk ke tugas yang berhasil dari model yang didukung.
Format model tidak valid: model_url merujuk ke file dengan ekstensi yang tidak didukung.
URL Tidak Dapat Dicapai: Elemen model_url, image_style_url atau multiview_image_urls tidak dapat diunduh.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit yang tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju Anda.
Request
POST
/openapi/v1/retexture
# Retexture dengan 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 dengan gaya gambar dan 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 mendapatkan 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.
Hasil
Respons 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 berikut:
Properti
Name
id
Type
string
Description
Pengenal unik untuk tugas. Meskipun kami menggunakan UUID k-sorting untuk id tugas sebagai rincian implementasi, Anda sebaiknya tidak membuat asumsi apa pun tentang format id.
Name
type
Type
string
Description
Jenis tugas Retexture. Nilai adalah retexture.
Name
model_urls
Type
object
Description
URL yang dapat diunduh ke file model 3D bertekstur yang dihasilkan oleh Meshy.
Name
glb
Type
string
Description
URL yang dapat diunduh ke file GLB.
Name
fbx
Type
string
Description
URL yang dapat diunduh ke file FBX.
Name
obj
Type
string
Description
URL yang dapat diunduh ke file OBJ.
Name
usdz
Type
string
Description
URL yang dapat diunduh ke file USDZ.
Name
mtl
Type
string
Description
URL yang dapat diunduh ke file MTL, dikembalikan bersamaan dengan ekspor OBJ ketika tekstur ada.
Name
stl
Type
string
Description
URL yang dapat diunduh ke file STL.
Name
3mf
Type
string
Description
URL yang dapat diunduh ke 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 texturing.
Name
image_style_url
Type
string
Description
Ini adalah input gambar yang digunakan untuk membuat tugas texturing.
Name
multiview_image_urls
Type
string[]
Description
URL yang dapat diunduh ke gambar referensi multi-tampilan yang digunakan untuk membuat tugas texturing. Hanya ada ketika tugas dibuat dengan multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL yang dapat diunduh ke gambar thumbnail dari file model.
Name
alpha_thumbnail_url
Type
string
Description
URL yang dapat diunduh ke versi transparan-latar belakang (RGBA) dari thumbnail_url. Hanya ada ketika tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, kolom 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 dari saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.
Stempel waktu merepresentasikan jumlah milidetik yang telah berlalu sejak 1 Januari 1970 UTC, mengikuti
standar RFC 3339.
Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Ini berlaku
untuk semua stempel waktu dalam Meshy API.
Name
created_at
Type
timestamp
Description
Stempel waktu dari saat tugas dibuat, dalam milidetik.
Name
expires_at
Type
timestamp
Description
Stempel waktu dari saat hasil tugas kedaluwarsa, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu dari 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 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 objek URL tekstur satu. Setiap URL tekstur memiliki properti berikut:
Name
base_color
Type
string
Description
URL yang dapat diunduh ke gambar peta warna dasar.
Name
metallic
Type
string
Description
URL yang dapat diunduh ke gambar peta metallic.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
normal
Type
string
Description
URL yang dapat diunduh ke gambar peta normal.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
roughness
Type
string
Description
URL yang dapat diunduh ke gambar peta roughness.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
emission
Type
string
Description
URL yang dapat diunduh ke 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 jika terjadi kegagalan).
Example Retexture Task Model
{"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}