Ang Retexture API ay isang feature na nagbibigay-daan sa iyong i-integrate ang mga kakayahan ng AI retexturing ng Meshy sa iyong sariling application. Sa seksyong ito, makikita mo ang lahat ng impormasyong kailangan mo upang makapagsimula sa API na ito.
Ang endpoint na ito ay nagbibigay-daan sa iyong gumawa ng bagong Retexture task. Sumangguni sa
The Retexture Task Object upang makita kung anong mga
property ang kasama sa Retexture task object.
Mga Parameter
Isa lamang sa input_task_id o model_url ang kinakailangan. Kapag parehong ibinigay, ang input_task_id ang mananaig.
Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng kumpletong Image to 3D o Text to 3D task na gusto mong i-retexture.
Ang task na ito ay dapat isa sa mga sumusunod: Text to 3D Preview, Text to 3D Refine, Image to 3D, o Remesh. Bukod dito, dapat itong may status na SUCCEEDED.
Name
model_url
Type
string
Kinakailangan
Description
Magbigay ng 3D model para i-texture ng Meshy. Mga sinusuportahang format: .glb, .gltf, .obj, .fbx, .stl.
May dalawang paraan para magbigay ng model:
Publicly accessible URL: Isang URL na maaaring i-access mula sa pampublikong internet.
Data URI: Isang base64-encoded data URI ng model. Gumamit ng MIME type na application/octet-stream. Halimbawa: data:application/octet-stream;base64,<your base64-encoded model data>.
Kinakailangan ang eksaktong isang style input: text_style_prompt, image_style_url, o multiview_image_urls. Hindi maaaring pagsamahin ang multiview_image_urls sa alinman sa dalawa pa; kapag parehong ibinigay ang text_style_prompt at image_style_url, ang image_style_url ang mananaig.
Name
text_style_prompt
Type
string
Kinakailangan
Description
Ilarawan ang nais mong texture style ng object gamit ang teksto. Maximum na 800 na character.
Name
image_style_url
Type
string
Kinakailangan
Description
Magbigay ng 2d na larawan upang gabayan ang proseso ng pag-texture. Kasalukuyang sinusuportahan namin ang mga format na .jpg, .jpeg, at .png.
May dalawang paraan para magbigay ng larawan:
Publicly accessible URL: Isang URL na maaaring i-access mula sa pampublikong internet
Data URI: Isang base64-encoded data URI ng larawan. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>
Maaaring hindi optimal ang pag-texture ng larawan kung may malaking pagkakaiba sa heometriya sa pagitan ng orihinal na asset at ng na-upload na larawan.
Name
multiview_image_urls
Type
string[]
Kinakailangan
Description
Magbigay ng 1 hanggang 4 na larawan na nagpapakita ng parehong object mula sa iba't ibang view upang gabayan ang pag-texture. Ang unang larawan ang pangunahing (harapang) view; hindi mahalaga ang pagkakasunud-sunod ng mga natitirang view (kaliwa, likod, kanan).
Bawat elemento ay tumatanggap ng parehong mga format tulad ng image_style_url (isang publicly accessible URL o isang base64 data URI, .jpg/.jpeg/.png).
Nangangailangan ng tahasang ai_model: "meshy-7".
Name
ai_model
Type
string
default latest
Description
ID ng AI model na gagamitin para sa retexturing. Available na mga value: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
default false
Description
Panatilihin ang umiiral na UV layout ng model sa halip na gumawa ng bago.
Kung nire-retexture mo ang isang model na ginawa ng Meshy (sa pamamagitan ng input_task_id, o isang model_url na tumutukoy sa output ng Meshy), itakda ito sa true upang muling gamitin ang na-optimize nitong UV layout.
Kung nire-retexture mo ang isang third-party na model na na-upload mo, itakda sa true kung mayroon na itong magandang UV na gusto mong panatilihin, o iwanan itong false upang hayaang mag-unwrap ang Meshy ng bagong UV (pinakamainam para sa mga model na walang wastong UV mapping).
Name
enable_pbr
Type
boolean
default false
Description
Gumawa ng PBR maps (metallic, roughness, normal) bilang karagdagan sa base color. Kasama rin ang emission map kapag ang ai_model ay meshy-6, maliban sa texture_resolution: 8k. Ang meshy-7 at latest ay hindi gumagawa ng emission map.
Name
texture_resolution
Type
string
default 2k
Description
Resolution ng base color texture. Isa sa 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Ang mas mataas na resolution ay nakakakuha ng mas maraming detalye sa ibabaw.
Ang 4k at 8k ay nangangailangan ng ai_model na meshy-6, meshy-7 o latest. Sa 8k, walang emission map na nagagawa.
Name
hd_texture
Type
boolean
⚠ lipas na
default false
Description
Gamitin sa halip ang texture_resolution — katumbas ng texture_resolution: "4k". Kapag pareho itong itinakda, ang texture_resolution ang mananaig.
Name
remove_lighting
Type
boolean
default true
Description
Inaalis ang mga highlight at anino mula sa base color texture, na nagbubunga ng mas malinis na resulta na mas mahusay gumana sa ilalim ng custom na setup ng ilaw.
Suportado lamang kapag ang ai_model ay meshy-6.
Name
target_formats
Type
string[]
Description
Tinutukoy kung aling mga 3D file format ang isasama sa output. Ang mga hiniling na format lamang ang gagawin at ibabalik, na maaaring magpababa sa oras ng pagkumpleto ng task. Kapag hindi ito isinama, lahat ng sinusuportahang format ang isasama.
Available na mga value: glb, obj, fbx, stl, usdz, 3mf
Kapag hindi ito isinama, lahat ng format maliban sa 3mf ang nagagawa. Ang 3mf ay isasama lamang kapag tahasang tinukoy.
Name
alpha_thumbnail
Type
boolean
default false
Description
Kapag itinakda sa true, ang task ay karagdagang mag-re-render ng bersyong may transparent background (RGBA) ng preview at ibabalik ito bilang alpha_thumbnail_url sa GET response. Ang umiiral na field na thumbnail_url ay hindi nagbabago.
Mga Ibinabalik
Ang result property ng response ay naglalaman ng task id ng bagong ginawang Retexture task.
Mga Mode ng Kabiguan
Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang mga sanhi:
Missing parameter: Dapat ibigay ang model_url o input_task_id.
Missing style: Dapat ibigay ang isa sa text_style_prompt, image_style_url o multiview_image_urls.
Conflicting style inputs: Hindi maaaring pagsamahin ang multiview_image_urls sa text_style_prompt o image_style_url.
Unsupported model for multi-view: Nangangailangan ang multiview_image_urls ng tahasang ai_model: "meshy-7".
Model not available: Ang ai_model: "meshy-7" ay unti-unting inilalabas at hindi pa naka-enable para sa iyong account.
Invalid input task: Ang input_task_id ay dapat tumukoy sa isang matagumpay na task mula sa isang sinusuportahang model.
Invalid model format: Ang model_url ay tumuturo sa isang file na may hindi sinusuportahang extension.
Unreachable URL: Hindi ma-download ang model_url, image_style_url o isang elemento ng multiview_image_urls.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits upang isagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang iyong rate limit.
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 }'
Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang Retexture task gamit ang isang valid na task id.
Sumangguni sa The Retexture Task Object upang makita kung
aling mga property ang kasama sa Retexture task object.
Mga Parameter
Name
id
Type
path
Description
Natatanging identifier para sa Retexture task na kukunin.
Mga Ibinabalik na Halaga
Ang tugon ay naglalaman ng Retexture task object. Tingnan ang seksyong
The Retexture Task Object para sa mga detalye.
{"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}
Permanenteng binubura ng endpoint na ito ang isang retexture task, kasama na ang lahat ng nauugnay na modelo at data. Hindi na maibabalik pa ang aksyong ito.
[ {"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 }]
Ang Retexture Task object ay isang work unit na ginagamit ng Meshy para makabuo ng 3D texture mula sa text o image inputs.
Ang model ay may mga sumusunod na properties:
Properties
Name
id
Type
string
Description
Natatanging identifier para sa task. Bagaman gumagamit kami ng k-sortable UUID para sa mga task id bilang
implementation detail, hindi mo dapat ipagpalagay ang format ng id.
Name
type
Type
string
Description
Uri ng Retexture task. Ang value ay retexture.
Name
model_urls
Type
object
Description
Downloadable URL sa textured 3D model file na binuo ng Meshy.
Name
glb
Type
string
Description
Downloadable URL sa GLB file.
Name
fbx
Type
string
Description
Downloadable URL sa FBX file.
Name
obj
Type
string
Description
Downloadable URL sa OBJ file.
Name
usdz
Type
string
Description
Downloadable URL sa USDZ file.
Name
mtl
Type
string
Description
Downloadable URL sa MTL file, ibinabalik kasama ng OBJ exports kapag may mga texture.
Name
stl
Type
string
Description
Downloadable URL sa STL file.
Name
3mf
Type
string
Description
Downloadable URL sa 3MF file. Naririto lamang kapag hiniling ang 3mf sa pamamagitan ng target_formats.
Name
text_style_prompt
Type
string
Description
Ito ang text prompt na ginamit para likhain ang texturing task.
Name
image_style_url
Type
string
Description
Ito ang image input na ginamit para likhain ang texturing task.
Name
multiview_image_urls
Type
string[]
Description
Downloadable URLs sa multi-view reference images na ginamit para likhain ang texturing task. Naririto lamang kapag nilikha ang task gamit ang multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Downloadable URL sa thumbnail image ng model file.
Name
alpha_thumbnail_url
Type
string
Description
Downloadable URL sa transparent-background (RGBA) na bersyon ng thumbnail_url. Naririto lamang kapag nilikha ang task gamit ang alpha_thumbnail: true at matagumpay na na-render ang transparent preview; kung hindi, aalisin ang field na ito.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.
Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas simula Enero 1, 1970 UTC, alinsunod sa
RFC 3339 standard.
Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Naaangkop ito
sa lahat ng timestamp sa Meshy API.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nilikha ang task, sa milliseconds.
Name
expires_at
Type
timestamp
Description
Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa tapos ang task, ang property na ito ay magiging 0.
Name
status
Type
string
Description
Status ng task. Ang posibleng mga value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Isang array ng texture URL objects na nabuo mula sa task. Karaniwan, iisang texture URL object lamang ang laman nito. Ang bawat texture URL ay may mga sumusunod na properties:
Name
base_color
Type
string
Description
Downloadable URL sa base color map image.
Name
metallic
Type
string
Description
Downloadable URL sa metallic map image.
Kung nilikha ang task gamit ang enable_pbr: false, aalisin ang property na ito.
Name
normal
Type
string
Description
Downloadable URL sa normal map image.
Kung nilikha ang task gamit ang enable_pbr: false, aalisin ang property na ito.
Name
roughness
Type
string
Description
Downloadable URL sa roughness map image.
Kung nilikha ang task gamit ang enable_pbr: false, aalisin ang property na ito.
Name
emission
Type
string
Description
Downloadable URL sa emission map image.
Kung nilikha ang task gamit ang enable_pbr: false, o meshy-5 ang ai_model, aalisin ang property na ito.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task.
Naririto lamang ang property na ito kapag ang status ng task ay PENDING.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng task na ito. Naririto kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (na-refund ang credits kapag nabigo).
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}