Retexture API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan Retexture AI Meshy ke dalam aplikasi Anda sendiri. Di 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 mengetahui
properti apa saja yang disertakan dalam objek tugas Retexture.
Parameter
Hanya salah satu dari input_task_id atau model_url yang wajib. Jika keduanya diberikan, input_task_id mendapat prioritas.
Name
input_task_id
Type
string
Wajib
Description
ID tugas Gambar ke 3D atau Teks ke 3D yang telah selesai dan ingin Anda Retexture.
Tugas ini harus merupakan salah satu dari tugas berikut: Pratinjau Teks ke 3D, Penyempurnaan Teks ke 3D, Gambar ke 3D, atau Remesh. Selain itu, tugas 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 memberikan 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>.
Hanya salah satu dari text_style_prompt atau image_style_url yang wajib. Jika keduanya diberikan, image_style_url mendapat prioritas.
Name
text_style_prompt
Type
string
Wajib
Description
Jelaskan gaya tekstur objek yang Anda inginkan menggunakan teks. Maksimum 600 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 memberikan 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 dari gambar mungkin tidak bekerja secara optimal jika terdapat perbedaan geometri yang substansial antara aset asli dan gambar yang diunggah.
Name
ai_model
Type
string
default latest
Description
ID model AI yang akan digunakan untuk Retexture. Nilai yang tersedia: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
default false
Description
Pertahankan tata letak UV yang sudah ada pada model alih-alih membuat yang baru.
Jika Anda melakukan Retexture pada model yang dihasilkan 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 ketika model tersebut sudah memiliki UV yang baik dan ingin Anda pertahankan, atau biarkan false agar Meshy membuka UV baru (terbaik 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 emission juga disertakan ketika ai_model adalah meshy-6 atau latest.
Name
hd_texture
Type
boolean
default false
Description
Hasilkan tekstur warna dasar pada resolusi 4K (4096×4096) untuk detail yang lebih tinggi.
Hanya didukung ketika ai_model adalah meshy-6 atau latest. peta PBR selalu dihasilkan pada 2K.
Name
remove_lighting
Type
boolean
default true
Description
Menghapus highlight dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih dan bekerja lebih baik di bawah pengaturan pencahayaan kustom.
Hanya didukung ketika ai_model adalah meshy-6 atau latest.
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. Jika dihilangkan, semua format yang didukung disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Jika dihilangkan, semua format kecuali 3mf akan dihasilkan. 3mf hanya disertakan ketika ditentukan secara eksplisit.
Name
alpha_thumbnail
Type
boolean
default false
Description
Ketika diatur ke true, tugas juga merender versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Field thumbnail_url yang sudah ada tidak berubah.
Mengembalikan
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 hilang: Salah satu dari model_url atau input_task_id harus diberikan.
Gaya hilang: Salah satu dari text_style_prompt atau image_style_url harus diberikan.
Tugas input tidak valid: input_task_id harus merujuk ke tugas 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 atau image_style_url tidak dapat diunduh.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju Anda.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurl https://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 PBRcurl https://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 dengan id yang valid.
Lihat Objek Tugas Retexture untuk mengetahui
properti yang disertakan dalam objek tugas Retexture.
Parameter
Name
id
Type
path
Description
Pengidentifikasi unik untuk tugas Retexture yang akan diambil.
Mengembalikan
Respons berisi objek tugas Retexture. Lihat 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
Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan-k untuk id tugas sebagai
detail implementasi, Anda tidak boleh membuat asumsi apa pun 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 bersama ekspor OBJ saat 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 ada saat 3mf diminta melalui target_formats.
Name
text_style_prompt
Type
string
Description
Ini adalah prompt teks yang digunakan untuk membuat tugas pemberian tekstur.
Name
image_style_url
Type
string
Description
Ini adalah input gambar yang digunakan untuk membuat tugas pemberian tekstur.
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 berlatar belakang transparan (RGBA) dari thumbnail_url. Hanya ada saat tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, bidang ini dihilangkan.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, nilainya 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 merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti
standar RFC 3339.
Misalnya, 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 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 tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Array objek URL tekstur yang dihasilkan dari tugas. 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 map warna dasar.
Name
metallic
Type
string
Description
URL yang dapat diunduh untuk gambar map metallic.
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 map roughness.
Jika tugas dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
Name
emission
Type
string
Description
URL yang dapat diunduh untuk gambar map emission.
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 muncul saat status tugas adalah PENDING.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh tugas ini. Ada saat status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat 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}