Retexture API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan retexturing AI dari Meshy ke dalam aplikasi Anda sendiri. Pada 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 disertakan dalam objek task Retexture.
Parameter
Hanya salah satu dari input_task_id atau model_url yang wajib diisi. Jika keduanya disediakan, input_task_id akan diprioritaskan.
Name
input_task_id
Type
string
Wajib
Description
ID dari task Gambar ke 3D atau Teks ke 3D yang telah selesai yang ingin Anda retexture.
Task ini harus 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 di-texture 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,<data model terenkode base64 Anda>.
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 keduanya disediakan, image_style_url akan diprioritaskan.
Name
text_style_prompt
Type
string
Wajib
Description
Deskripsikan gaya tekstur objek yang Anda inginkan menggunakan teks. Maksimum 800 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 gambar yang dienkode base64. Contoh data URI: data:image/jpeg;base64,<data gambar terenkode base64 Anda>
Texturing gambar mungkin tidak berfungsi optimal jika terdapat perbedaan geometri yang signifikan 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 sudut pandang berbeda untuk memandu texturing. Gambar pertama adalah tampilan utama (depan); urutan tampilan lainnya (kiri, belakang, kanan) tidak masalah.
Setiap elemen menerima format yang sama seperti 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 retexturing. 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 meretexture 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 meretexture model pihak ketiga yang Anda unggah, atur ke true jika model tersebut sudah memiliki UV yang baik yang ingin Anda pertahankan, atau biarkan false agar Meshy melakukan unwrap UV baru (paling baik untuk model yang tidak memiliki pemetaan UV yang tepat).
Name
enable_pbr
Type
boolean
default false
Description
Hasilkan peta PBR (metallic, roughness, normal) selain base color. 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 base color. 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 yang akan diprioritaskan.
Name
remove_lighting
Type
boolean
default true
Description
Menghapus highlight dan bayangan dari tekstur base color, menghasilkan hasil yang lebih bersih yang bekerja lebih baik pada 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 task. Jika dihilangkan, semua format yang didukung akan disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Jika dihilangkan, 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 merender versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Field thumbnail_url yang sudah ada tidak berubah.
Returns
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 saling 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 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 melakukan task ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju Anda.
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 mengambil tugas Retexture berdasarkan id tugas yang valid.
Lihat The Retexture Task Object untuk melihat properti
apa saja yang disertakan dalam objek tugas Retexture.
Parameter
Name
id
Type
path
Description
Pengenal unik untuk tugas Retexture yang ingin diambil.
{"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 Retexture Task adalah unit kerja yang digunakan Meshy untuk menghasilkan tekstur 3D dari input teks atau gambar.
Model ini memiliki properti berikut:
Properties
Name
id
Type
string
Description
Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan (k-sortable) untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis task 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 bersama ekspor OBJ ketika tekstur tersedia.
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 muncul ketika 3mf diminta melalui target_formats.
Name
text_style_prompt
Type
string
Description
Ini adalah prompt teks yang digunakan untuk membuat task pemberian tekstur.
Name
image_style_url
Type
string
Description
Ini adalah input gambar yang digunakan untuk membuat task pemberian tekstur.
Name
multiview_image_urls
Type
string[]
Description
URL yang dapat diunduh untuk gambar referensi Multi-Tampilan yang digunakan untuk membuat task pemberian tekstur. Hanya muncul ketika task 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 muncul ketika task dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, kolom ini akan dihilangkan.
Name
progress
Type
integer
Description
Progress dari task. Jika task belum dimulai, properti ini bernilai 0. Setelah task berhasil, nilainya akan menjadi 100.
Name
started_at
Type
timestamp
Description
Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini bernilai 0.
Stempel waktu merepresentasikan jumlah milidetik yang 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 di Meshy API.
Name
created_at
Type
timestamp
Description
Stempel waktu saat task dibuat, dalam milidetik.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini bernilai 0.
Name
status
Type
string
Description
Status dari task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Sebuah array objek URL tekstur yang dihasilkan dari task. Biasanya ini hanya berisi satu objek URL tekstur. Setiap URL tekstur memiliki properti berikut:
Name
base_color
Type
string
Description
URL yang dapat diunduh untuk gambar peta warna dasar (base color map).
Name
metallic
Type
string
Description
URL yang dapat diunduh untuk gambar peta metallic.
Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
normal
Type
string
Description
URL yang dapat diunduh untuk gambar normal map.
Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
roughness
Type
string
Description
URL yang dapat diunduh untuk gambar peta roughness.
Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
emission
Type
string
Description
URL yang dapat diunduh untuk gambar peta emission.
Jika task dibuat dengan enable_pbr: false, atau ai_model bernilai meshy-5, properti ini akan dihilangkan.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang mendahului.
Properti ini hanya muncul ketika status task adalah PENDING.
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh task ini. Muncul ketika status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).
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}