Retexture API je funkce, která vám umožňuje integrovat schopnosti AI retexturování Meshy do vaší vlastní aplikace. V této sekci najdete všechny informace,
které potřebujete k tomu, abyste s tímto API mohli začít.
Tento koncový bod umožňuje vytvořit nový úkol Retexturování. Podrobnosti o
vlastnostech, které objekt úkolu Retexturování obsahuje, najdete v části
The Retexture Task Object.
Parametry
Vyžadován je pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, má přednost input_task_id.
Name
input_task_id
Type
string
Povinné
Description
ID dokončeného úkolu Obrázek na 3D nebo Text na 3D, který chcete retexturovat.
Tento úkol musí být jedním z následujících: Text na 3D Preview, Text na 3D Refine, Obrázek na 3D nebo Remesh. Kromě toho musí mít stav SUCCEEDED.
Name
model_url
Type
string
Povinné
Description
Poskytněte Meshy 3D model k texturování. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
Model lze zadat dvěma způsoby:
Veřejně dostupná URL: Adresa URL, která je dostupná z veřejného internetu.
Data URI: Base64 kódované data URI modelu. Použijte MIME type application/octet-stream. Příklad: data:application/octet-stream;base64,<vaše base64 kódovaná data modelu>.
Je vyžadován přesně jeden vstup stylu: text_style_prompt, image_style_url nebo multiview_image_urls. multiview_image_urls nelze kombinovat s žádným z ostatních dvou; pokud jsou zadány jak text_style_prompt, tak image_style_url, má přednost image_style_url.
Name
text_style_prompt
Type
string
Povinné
Description
Popište textem požadovaný styl textury objektu. Maximálně 800 znaků.
Name
image_style_url
Type
string
Povinné
Description
Poskytněte 2D obrázek, který bude vodítkem pro proces texturování. V současné době podporujeme formáty .jpg, .jpeg a .png.
Obrázek lze zadat dvěma způsoby:
Veřejně dostupná URL: Adresa URL, která je dostupná z veřejného internetu
Data URI: Base64 kódované data URI obrázku. Příklad data URI: data:image/jpeg;base64,<vaše base64 kódovaná data obrázku>
Texturování podle obrázku nemusí fungovat optimálně, pokud existují výrazné rozdíly v geometrii mezi původním assetem a nahraným obrázkem.
Name
multiview_image_urls
Type
string[]
Povinné
Description
Poskytněte 1 až 4 obrázky zobrazující stejný objekt z různých úhlů pohledu, které budou vodítkem pro texturování. První obrázek je hlavní (přední) pohled; na pořadí zbývajících pohledů (levý, zadní, pravý) nezáleží.
Každý prvek přijímá stejné formáty jako image_style_url (veřejně dostupná URL nebo base64 data URI, .jpg/.jpeg/.png).
Vyžaduje explicitní ai_model: "meshy-7".
Name
ai_model
Type
string
výchozí latest
Description
ID AI modelu, který se má použít pro retexturování. Dostupné hodnoty: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
výchozí false
Description
Zachová stávající UV rozvržení modelu místo generování nového.
Pokud retexturujete model, který vygenerovalo Meshy (přes input_task_id, nebo model_url, který odkazuje na výstup Meshy), nastavte tuto hodnotu na true, aby se znovu použilo jeho optimalizované UV rozvržení.
Pokud retexturujete model třetí strany, který jste nahráli, nastavte true, pokud již má dobré UV, které chcete zachovat, nebo ponechte false, aby Meshy vytvořilo nové UV rozvinutí (nejlepší pro modely, které postrádají správné UV mapování).
Name
enable_pbr
Type
boolean
výchozí false
Description
Vygeneruje PBR mapy (metallic, roughness, normal) kromě základní barvy. Emisní mapa je zahrnuta také, pokud je ai_model roven meshy-6, s výjimkou texture_resolution: 8k. meshy-7 a latest emisní mapu negenerují.
Name
texture_resolution
Type
string
výchozí 2k
Description
Rozlišení textury základní barvy. Jedna z hodnot 2k (2048×2048), 4k (4096×4096) nebo 8k (8192×8192). Vyšší rozlišení zachycují více povrchových detailů.
4k a 8k vyžadují ai_modelmeshy-6, meshy-7 nebo latest. Při 8k se negeneruje emisní mapa.
Name
hd_texture
Type
boolean
⚠ zastaralé
výchozí false
Description
Místo toho použijte texture_resolution — odpovídá hodnotě texture_resolution: "4k". Pokud jsou nastaveny obě, má přednost texture_resolution.
Name
remove_lighting
Type
boolean
výchozí true
Description
Odstraní světla a stíny z textury základní barvy, čímž vznikne čistší výsledek, který lépe funguje s vlastním nastavením osvětlení.
Podporováno pouze pokud je ai_model roven meshy-6.
Name
target_formats
Type
string[]
Description
Určuje, které formáty 3D souborů se mají zahrnout do výstupu. Vygenerují a vrátí se pouze požadované formáty, což může zkrátit dobu dokončení úkolu. Pokud je vynecháno, jsou zahrnuty všechny podporované formáty.
Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf
Pokud je vynecháno, generují se všechny formáty kromě 3mf. 3mf je zahrnut pouze při explicitním zadání.
Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, úkol navíc vyrenderuje verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi na GET požadavek. Existující pole thumbnail_url zůstává beze změny.
Návratové hodnoty
Vlastnost result v odpovědi obsahuje id úkolu nově vytvořeného úkolu Retexturování.
Chybové stavy
Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Časté příčiny:
Chybějící parametr: Musí být uveden buď model_url, nebo input_task_id.
Chybějící styl: Musí být uveden jeden z parametrů text_style_prompt, image_style_url nebo multiview_image_urls.
Konfliktní vstupy stylu: multiview_image_urls nelze kombinovat s text_style_prompt ani image_style_url.
Nepodporovaný model pro více pohledů: multiview_image_urls vyžaduje explicitní ai_model: "meshy-7".
Model není dostupný: ai_model: "meshy-7" se postupně zavádí a pro váš účet ještě není povolen.
Neplatný vstupní úkol: input_task_id musí odkazovat na úspěšný úkol z podporovaného modelu.
Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
Nedostupná URL: model_url, image_style_url nebo prvek multiview_image_urls se nepodařilo stáhnout.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení tohoto úkolu.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti.
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 }'
Tento koncový bod umožňuje získat úlohu Retexturování na základě platného id úlohy.
Podrobnosti o vlastnostech, které jsou součástí objektu úlohy Retexturování, najdete v části
Objekt úlohy Retexturování.
Parametry
Name
id
Type
path
Description
Jedinečný identifikátor úlohy Retexturování, kterou chcete získat.
{"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 }]
Objekt Retexture Task je pracovní jednotka, kterou Meshy používá k vygenerování 3D textury z textového nebo obrazového vstupu.
Model má následující vlastnosti:
Vlastnosti
Name
id
Type
string
Description
Jedinečný identifikátor úlohy. Přestože jako implementační detail používáme pro id úloh k-sortable UUID,
neměli byste dělat žádné předpoklady o formátu id.
Name
type
Type
string
Description
Typ úlohy Retexturování. Hodnota je retexture.
Name
model_urls
Type
object
Description
Stažitelná URL adresa na soubor s texturovaným 3D modelem vygenerovaným pomocí Meshy.
Name
glb
Type
string
Description
Stažitelná URL adresa na soubor GLB.
Name
fbx
Type
string
Description
Stažitelná URL adresa na soubor FBX.
Name
obj
Type
string
Description
Stažitelná URL adresa na soubor OBJ.
Name
usdz
Type
string
Description
Stažitelná URL adresa na soubor USDZ.
Name
mtl
Type
string
Description
Stažitelná URL adresa na soubor MTL, vrácená spolu s exportem OBJ, pokud jsou přítomny textury.
Name
stl
Type
string
Description
Stažitelná URL adresa na soubor STL.
Name
3mf
Type
string
Description
Stažitelná URL adresa na soubor 3MF. Přítomna pouze tehdy, když byl formát 3mf požadován prostřednictvím target_formats.
Name
text_style_prompt
Type
string
Description
Toto je textový prompt, který byl použit k vytvoření úlohy texturování.
Name
image_style_url
Type
string
Description
Toto je obrazový vstup, který byl použit k vytvoření úlohy texturování.
Name
multiview_image_urls
Type
string[]
Description
Stažitelné URL adresy na referenční obrázky z více pohledů, které byly použity k vytvoření úlohy texturování. Přítomny pouze v případě, že úloha byla vytvořena s multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Stažitelná URL adresa na miniaturu obrázku souboru modelu.
Name
alpha_thumbnail_url
Type
string
Description
Stažitelná URL adresa na verzi thumbnail_url s průhledným pozadím (RGBA). Přítomna pouze tehdy, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vykreslen; jinak je toto pole vynecháno.
Name
progress
Type
integer
Description
Postup úlohy (progress). Pokud úloha ještě nebyla zahájena, tato vlastnost bude mít hodnotu 0. Jakmile úloha uspěje, hodnota se změní na 100.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha zahájena, v milisekundách. Pokud úloha ještě nebyla zahájena, tato vlastnost bude mít hodnotu 0.
Časové razítko představuje počet milisekund, které uplynuly od 1. ledna 1970 UTC, podle
standardu RFC 3339.
Například pátek 1. září 2023 12:00:00 GMT je reprezentován jako 1693569600000. To platí
pro všechna časová razítka v Meshy API.
Name
created_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha vytvořena, v milisekundách.
Name
expires_at
Type
timestamp
Description
Časové razítko okamžiku, kdy vyprší platnost výsledku úlohy, v milisekundách.
Name
finished_at
Type
timestamp
Description
Časové razítko okamžiku, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude mít hodnotu 0.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Pole objektů URL textur vygenerovaných touto úlohou. Běžně obsahuje pouze jeden objekt URL textury. Každý objekt URL textury má následující vlastnosti:
Name
base_color
Type
string
Description
Stažitelná URL adresa na obrázek mapy základní barvy.
Name
metallic
Type
string
Description
Stažitelná URL adresa na obrázek metalické mapy.
Pokud byla úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
normal
Type
string
Description
Stažitelná URL adresa na obrázek normálové mapy.
Pokud byla úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
roughness
Type
string
Description
Stažitelná URL adresa na obrázek mapy drsnosti.
Pokud byla úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
emission
Type
string
Description
Stažitelná URL adresa na obrázek mapy emise.
Pokud byla úloha vytvořena s enable_pbr: false, nebo pokud je ai_model roven meshy-5, tato vlastnost bude vynechána.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Tato vlastnost je přítomna pouze tehdy, když je stav úlohy PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplný referenční popis objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh se stavem FAILED vrací 0 (kredity jsou při selhání vráceny).
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}