Retexture API je funkce, která vám umožňuje integrovat schopnosti AI retexturování od Meshy do vaší vlastní aplikace. V této sekci najdete všechny informace, které potřebujete k zahájení práce s tímto API.
Tento koncový bod umožňuje vytvořit novou úlohu Retexturování. Podívejte se na
Objekt úlohy Retexturování, kde zjistíte, jaké
vlastnosti objekt úlohy Retexturování obsahuje.
Parametry
Je vyžadován 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é úlohy Obrázek na 3D nebo Text na 3D, kterou chcete retexturovat.
Tato úloha musí být jednou 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 3D model, který má Meshy texturovat. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
Model lze poskytnout dvěma způsoby:
Veřejně přístupná URL: URL adresa 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 pomocí textu požadovaný styl textury objektu. Maximálně 800 znaků.
Name
image_style_url
Type
string
Povinné
Description
Poskytněte 2D obrázek k vedení procesu texturování. Aktuálně podporujeme formáty .jpg, .jpeg a .png.
Obrázek lze poskytnout dvěma způsoby:
Veřejně přístupná URL: URL adresa 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 pohledů pro vedení texturování. První obrázek je primární (přední) pohled; 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ě přístupná 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 (pomocí input_task_id, nebo model_url odkazující na výstup Meshy), nastavte na true pro znovupoužití jeho optimalizovaného UV rozvržení.
Pokud retexturujete model třetí strany, který jste nahráli, nastavte na true, pokud již má dobré UV, které chcete zachovat, nebo ponechte false, aby Meshy vytvořilo nové UV rozvinutí (nejlepší pro modely bez řádného 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 také zahrnuta, pokud je ai_model nastaven na meshy-6, kromě 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
Použijte místo toho texture_resolution — je ekvivalentní texture_resolution: "4k". Pokud jsou nastaveny oba, má přednost texture_resolution.
Name
remove_lighting
Type
boolean
výchozí true
Description
Odstraní odlesky a stíny ze základní barevné textury, čímž vznikne čistší výsledek, který lépe funguje s vlastním nastavením osvětlení.
Podporováno pouze v případě, že ai_model je meshy-6.
Name
target_formats
Type
string[]
Description
Určuje, které 3D souborové formáty se mají zahrnout do výstupu. Vygenerovány a vráceny budou pouze požadované formáty, což může zkrátit dobu dokončení úlohy. Pokud parametr vynecháte, budou zahrnuty všechny podporované formáty.
Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf
Pokud parametr vynecháte, budou vygenerovány všechny formáty kromě 3mf. 3mf je zahrnut pouze tehdy, je-li explicitně uveden.
Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Stávající pole thumbnail_url zůstává beze změny.
Návratové hodnoty
Vlastnost result odpovědi obsahuje id úlohy nově vytvořené úlohy Retexturování.
Režimy selhání
Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
Chybějící parametr: Musí být zadán buď model_url, nebo input_task_id.
Chybějící styl: Musí být zadán 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í úloha: input_task_id musí odkazovat na úspěšnou úlohu 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í této úlohy.
Name
429 - Too Many Requests
Description
Překročili jste svůj 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 vám umožňuje načíst úkol Retexturování pomocí platného id úkolu.
Podívejte se na Objekt úkolu Retexturování, abyste viděli, které
vlastnosti jsou zahrnuty v objektu úkolu Retexturování.
Parametry
Name
id
Type
path
Description
Jedinečný identifikátor pro úkol Retexturování, který chcete načíst.
Návraty
Odpověď obsahuje objekt úkolu Retexturování. Podívejte se na
sekci Objekt úkolu Retexturování pro podrobnosti.
{"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 úlohy Retexturování je pracovní jednotka, kterou Meshy používá k vytvoření 3D textury z textových nebo obrazových vstupů. Model má následující vlastnosti:
Vlastnosti
Name
id
Type
string
Description
Unikátní identifikátor úlohy. I když používáme k-tříděné UUID pro id úloh jako implementační detail, 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
Stahovatelná URL adresa k souboru texturovaného 3D modelu generovaného Meshy.
Name
glb
Type
string
Description
Stahovatelná URL adresa k souboru GLB.
Name
fbx
Type
string
Description
Stahovatelná URL adresa k souboru FBX.
Name
obj
Type
string
Description
Stahovatelná URL adresa k souboru OBJ.
Name
usdz
Type
string
Description
Stahovatelná URL adresa k souboru USDZ.
Name
mtl
Type
string
Description
Stahovatelná URL adresa k souboru MTL, vrácená spolu s exporty OBJ, když jsou přítomny textury.
Name
stl
Type
string
Description
Stahovatelná URL adresa k souboru STL.
Name
3mf
Type
string
Description
Stahovatelná URL adresa k souboru 3MF. Přítomna pouze, když byl 3mf požadován přes 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
Stahovatelné URL adresy k referenčním obrázkům z více pohledů, které byly použity k vytvoření úlohy texturování. Přítomny pouze, když byla úloha vytvořena s multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Stahovatelná URL adresa k miniatuře obrázku souboru modelu.
Name
alpha_thumbnail_url
Type
string
Description
Stahovatelná URL adresa k verzi thumbnail_url s průhledným pozadím (RGBA). Přítomna pouze, 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
Pokrok úlohy. Pokud úloha ještě nezačala, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nezačala, tato vlastnost bude 0.
Časové razítko představuje počet milisekund uplynulých 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, kdy byla úloha vytvořena, v milisekundách.
Name
expires_at
Type
timestamp
Description
Časové razítko, kdy výsledek úlohy vyprší, v milisekundách.
Name
finished_at
Type
timestamp
Description
Časové razítko, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě není dokončena, tato vlastnost bude 0.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Pole objektů URL adres textur, které jsou generovány z úlohy. Obvykle obsahuje pouze jeden objekt URL adresy textury. Každá URL adresa textury má následující vlastnosti:
Name
base_color
Type
string
Description
Stahovatelná URL adresa k obrázku základní barevné mapy.
Name
metallic
Type
string
Description
Stahovatelná URL adresa k obrázku kovové mapy.
Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
normal
Type
string
Description
Stahovatelná URL adresa k obrázku normálové mapy.
Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
roughness
Type
string
Description
Stahovatelná URL adresa k obrázku mapy drsnosti.
Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
Name
emission
Type
string
Description
Stahovatelná URL adresa k obrázku emisní mapy.
Pokud je úloha vytvořena s enable_pbr: false, nebo ai_model je 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, když je stav úlohy PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybách pro neúspěšné úlohy. Viz Chyby pro úplnou referenci objektu task_error.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 pro úlohy FAILED (kredity jsou vráceny při selhání).
Příklad modelu úlohy Retexturování
{"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}