Retekstur API adalah ciri yang membolehkan anda mengintegrasikan keupayaan retekstur AI Meshy ke dalam aplikasi anda sendiri. Dalam bahagian ini, anda akan menemui semua maklumat yang anda perlukan untuk memulakan dengan API ini.
Endpoint ini membolehkan anda membuat tugas Retekstur baharu. Rujuk
The Retexture Task Object untuk melihat
ciri-ciri yang disertakan dengan objek tugas Retekstur.
Parameter
Hanya salah satu daripada input_task_id atau model_urldiperlukan. Jika kedua-duanya disediakan, input_task_id mengambil keutamaan.
Name
input_task_id
Type
string
Diperlukan
Description
ID tugas Imej ke 3D atau Teks ke 3D yang telah selesai yang ingin anda retekstur.
Tugas ini mestilah salah satu daripada tugas berikut: Text to 3D Preview, Text to 3D Refine, Image to 3D atau Remesh. Selain itu, tugas tersebut mesti mempunyai status SUCCEEDED.
Name
model_url
Type
string
Diperlukan
Description
Berikan model 3D untuk Meshy tekstur. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl.
Terdapat dua cara untuk menyediakan model:
URL yang boleh diakses secara awam: URL yang boleh diakses dari internet awam.
Data URI: Data URI model yang dikodkan base64. Gunakan MIME type application/octet-stream. Contoh: data:application/octet-stream;base64,<data model anda yang dikodkan base64>.
Tepat satu input gaya adalah diperlukan: text_style_prompt, image_style_url, atau multiview_image_urls. multiview_image_urls tidak boleh digabungkan dengan mana-mana dua yang lain; jika kedua-dua text_style_prompt dan image_style_url disediakan, image_style_url mengambil keutamaan.
Name
text_style_prompt
Type
string
Diperlukan
Description
Terangkan gaya tekstur objek yang anda kehendaki menggunakan teks. Maksimum 800 aksara.
Name
image_style_url
Type
string
Diperlukan
Description
Sediakan imej 2d untuk membimbing proses tekstur. Kami buat masa ini menyokong format .jpg, .jpeg, dan .png.
Terdapat dua cara untuk menyediakan imej:
URL yang boleh diakses secara awam: URL yang boleh diakses dari internet awam
Data URI: Data URI imej yang dikodkan base64. Contoh Data URI: data:image/jpeg;base64,<data imej anda yang dikodkan base64>
Tekstur imej mungkin tidak berfungsi dengan optimum jika terdapat perbezaan geometri yang besar antara aset asal dan imej yang dimuat naik.
Name
multiview_image_urls
Type
string[]
Diperlukan
Description
Sediakan 1 hingga 4 imej yang menunjukkan objek yang sama daripada pandangan berbeza untuk membimbing tekstur. Imej pertama adalah pandangan utama (hadapan); susunan pandangan yang selebihnya (kiri, belakang, kanan) tidak penting.
Setiap elemen menerima format yang sama seperti image_style_url (URL yang boleh diakses secara awam atau Data URI base64, .jpg/.jpeg/.png).
Memerlukan ai_model: "meshy-7" secara jelas.
Name
ai_model
Type
string
lalai latest
Description
ID model AI yang digunakan untuk retekstur. Nilai yang tersedia: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
lalai false
Description
Kekalkan susun atur UV sedia ada model dan bukannya menjana yang baharu.
Jika anda melakukan retekstur pada model yang dijana oleh Meshy (melalui input_task_id, atau model_url yang menunjuk kepada output Meshy), tetapkan ini kepada true untuk menggunakan semula susun atur UV yang dioptimumkan.
Jika anda melakukan retekstur pada model pihak ketiga yang anda muat naik, tetapkan true apabila ia sudah mempunyai UV yang baik yang anda ingin kekalkan, atau biarkan false untuk membiarkan Meshy membuka lipatan UV baharu (paling sesuai untuk model yang tidak mempunyai pemetaan UV yang betul).
Name
enable_pbr
Type
boolean
lalai false
Description
Jana peta PBR (metallic, roughness, normal) selain warna asas. Peta emisi juga disertakan apabila ai_model ialah meshy-6, kecuali pada texture_resolution: 8k. meshy-7 dan latest tidak menghasilkan peta emisi.
Name
texture_resolution
Type
string
lalai 2k
Description
Resolusi tekstur warna asas. Salah satu daripada 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap lebih banyak perincian permukaan.
4k dan 8k memerlukan ai_modelmeshy-6, meshy-7 atau latest. Pada 8k, tiada peta emisi dihasilkan.
Name
hd_texture
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan texture_resolution sebagai gantinya — bersamaan dengan texture_resolution: "4k". Apabila kedua-duanya ditetapkan, texture_resolution mengambil keutamaan.
Name
remove_lighting
Type
boolean
lalai true
Description
Membuang sorotan dan bayang-bayang daripada tekstur warna asas, menghasilkan hasil yang lebih bersih yang berfungsi lebih baik di bawah tetapan pencahayaan tersuai.
Hanya disokong apabila ai_model ialah meshy-6.
Name
target_formats
Type
string[]
Description
Menentukan format fail 3D yang hendak disertakan dalam output. Hanya format yang diminta akan dijana dan dikembalikan, yang dapat mengurangkan masa penyelesaian tugas. Jika ditinggalkan, semua format yang disokong akan disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Jika ditinggalkan, semua format kecuali 3mf dijana. 3mf hanya disertakan apabila dinyatakan secara jelas.
Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugas tersebut turut memaparkan versi latar belakang lutsinar (RGBA) bagi pratonton dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.
Pulangan
Ciri result bagi respons mengandungi id tugas bagi tugas Retekstur yang baharu dicipta.
Mod Kegagalan
Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Sebab-sebab biasa:
Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
Gaya hilang: Salah satu daripada text_style_prompt, image_style_url atau multiview_image_urls mesti disediakan.
Input gaya bercanggah: multiview_image_urls tidak boleh digabungkan dengan text_style_prompt atau image_style_url.
Model tidak disokong untuk berbilang pandangan: multiview_image_urls memerlukan ai_model: "meshy-7" secara jelas.
Model tidak tersedia: ai_model: "meshy-7" sedang dilancarkan secara progresif dan belum diaktifkan untuk akaun anda.
Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya daripada model yang disokong.
Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
URL tidak dapat dicapai: model_url, image_style_url atau elemen multiview_image_urls tidak dapat dimuat turun.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar 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 membolehkan anda mendapatkan tugas Retekstur dengan memberikan id tugas yang sah.
Rujuk kepada Objek Tugas Retekstur untuk melihat
sifat-sifat yang disertakan dengan objek tugas Retekstur.
Parameter
Name
id
Type
path
Description
Pengenal pasti unik untuk tugas Retekstur yang ingin diperoleh.
Pulangan
Respons mengandungi objek tugas Retekstur. Semak
bahagian Objek Tugas Retekstur untuk butiran lanjut.
{"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 Retekstur adalah unit kerja yang digunakan oleh Meshy untuk menjana tekstur 3D daripada input teks atau imej. Model ini mempunyai sifat-sifat berikut:
Sifat-sifat
Name
id
Type
string
Description
Pengenal pasti unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh diurutkan k untuk id tugas sebagai butiran pelaksanaan, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Retekstur. Nilainya adalah retexture.
Name
model_urls
Type
object
Description
URL boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy.
Name
glb
Type
string
Description
URL boleh dimuat turun untuk fail GLB.
Name
fbx
Type
string
Description
URL boleh dimuat turun untuk fail FBX.
Name
obj
Type
string
Description
URL boleh dimuat turun untuk fail OBJ.
Name
usdz
Type
string
Description
URL boleh dimuat turun untuk fail USDZ.
Name
mtl
Type
string
Description
URL boleh dimuat turun untuk fail MTL, dikembalikan bersama eksport OBJ apabila tekstur hadir.
Name
stl
Type
string
Description
URL boleh dimuat turun untuk fail STL.
Name
3mf
Type
string
Description
URL boleh dimuat turun untuk fail 3MF. Hanya hadir apabila 3mf diminta melalui target_formats.
Name
text_style_prompt
Type
string
Description
Ini adalah prompt teks yang digunakan untuk mencipta tugas tekstur.
Name
image_style_url
Type
string
Description
Ini adalah input imej yang digunakan untuk mencipta tugas tekstur.
Name
multiview_image_urls
Type
string[]
Description
URL boleh dimuat turun untuk imej rujukan berbilang pandangan yang digunakan untuk mencipta tugas tekstur. Hanya hadir apabila tugas dicipta dengan multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL boleh dimuat turun untuk imej kecil fail model.
Name
alpha_thumbnail_url
Type
string
Description
URL boleh dimuat turun untuk versi latar belakang telus (RGBA) dari thumbnail_url. Hanya hadir apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton telus berjaya dirender; jika tidak, medan ini diabaikan.
Name
progress
Type
integer
Description
Kemajuan tugas. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
started_at
Type
timestamp
Description
Cap masa apabila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut
standard RFC 3339.
Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai
kepada semua cap masa dalam Meshy API.
Name
created_at
Type
timestamp
Description
Cap masa apabila tugas dicipta, dalam milisaat.
Name
expires_at
Type
timestamp
Description
Cap masa apabila hasil tugas tamat tempoh, dalam milisaat.
Name
finished_at
Type
timestamp
Description
Cap masa apabila tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat 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
Satu array objek URL tekstur yang dijana daripada tugas. Biasanya ini hanya mengandungi satu objek URL tekstur. Setiap URL tekstur mempunyai sifat-sifat berikut:
Name
base_color
Type
string
Description
URL boleh dimuat turun untuk imej peta warna asas.
Name
metallic
Type
string
Description
URL boleh dimuat turun untuk imej peta logam.
Jika tugas dicipta dengan enable_pbr: false, sifat ini akan diabaikan.
Name
normal
Type
string
Description
URL boleh dimuat turun untuk imej peta normal.
Jika tugas dicipta dengan enable_pbr: false, sifat ini akan diabaikan.
Name
roughness
Type
string
Description
URL boleh dimuat turun untuk imej peta kekasaran.
Jika tugas dicipta dengan enable_pbr: false, sifat ini akan diabaikan.
Name
emission
Type
string
Description
URL boleh dimuat turun untuk imej peta emisi.
Jika tugas dicipta dengan enable_pbr: false, atau ai_model adalah meshy-5, sifat ini akan diabaikan.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Sifat ini hanya hadir apabila status tugas adalah PENDING.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan semula apabila gagal).
Contoh Model Tugas Retekstur
{"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}