Retexture API je funkce, která vám umožňuje integrovat schopnosti AI retexturování Meshy do vaší vlastní aplikace. V této části najdete všechny informace, které potřebujete k zahájení práce s tímto API.
Tento koncový bod vám umožňuje vytvořit nový úkol pro Retexturování. Odkaz na Objekt úkolu pro Retexturování zobrazí, které vlastnosti jsou zahrnuty v objektu úkolu pro Retexturování.
Parametry
Pouze jeden z input_task_id nebo model_url je vyžadován. Pokud jsou poskytnuty oba, input_task_id má prioritu.
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 úkolů: Text na 3D Náhled, Text na 3D Zjemnění, Obrázek na 3D nebo Remesh. Navíc musí mít stav SUCCEEDED.
Name
model_url
Type
string
Povinné
Description
Poskytněte 3D model pro Meshy k retexturování. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
Existují dva způsoby, jak poskytnout model:
Veřejně přístupná URL: URL, která je přístupná z veřejného internetu.
Data URI: Základně zakódovaná data URI modelu. Použijte MIME type application/octet-stream. Příklad: data:application/octet-stream;base64,<vaše základně zakódovaná data modelu>.
Přesně jedna možnost stylu vstupu je vyžadována: text_style_prompt, image_style_url nebo multiview_image_urls. multiview_image_urls nelze kombinovat s žádnou z ostatních dvou; pokud jsou poskytnuty jak text_style_prompt, tak image_style_url, image_style_url má prioritu.
Name
text_style_prompt
Type
string
Povinné
Description
Popište požadovaný styl textury objektu pomocí textu. Maximálně 600 znaků.
Name
image_style_url
Type
string
Povinné
Description
Poskytněte 2d obrázek, který vede proces texturování. V současné době podporujeme formáty .jpg, .jpeg a .png.
Existují dva způsoby, jak poskytnout obrázek:
Veřejně přístupná URL: URL, která je přístupná z veřejného internetu
Data URI: Základně zakódovaná data URI obrázku. Příklad dat URI: data:image/jpeg;base64,<vaše základně zakódovaná data obrázku>
Texturování podle obrázku nemusí fungovat optimálně, pokud jsou mezi původním assetem a nahraným obrázkem podstatné rozdíly v geometrie.
Name
multiview_image_urls
Type
string[]
Povinné
Description
Poskytněte 1 až 4 obrázky zobrazující tentýž objekt z různých pohledů, aby vedly texturování. První obrázek je primární (čelní) pohled; pořadí zbývajících pohledů (levý, zadní, pravý) není důležité.
Každý prvek přijímá stejné formáty jako image_style_url (veřejně přístupná URL nebo základní data URI, .jpg/.jpeg/.png).
Vyžaduje ai_model: "meshy-7" (nebo latest).
Name
ai_model
Type
string
výchozí latest
Description
ID AI modelu použitého pro retexturování. Dostupné hodnoty: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
výchozí false
Description
Zachovat existující UV rozvržení modelu místo generování nového.
Pokud si přetexturováváte model, který byl generován Meshy (prostřednictvím input_task_id, nebo model_url, který ukazuje na Meshy output), nastavte toto na true, abyste znovu použili jeho optimalizované UV rozvržení.
Pokud přetexturováváte model třetí strany, který jste nahráli, nastavte na true, když již má dobré UVs, které chcete zachovat, nebo nechte false, aby Meshy vyměnil nové UVs (nejlépe pro modely, které nemají správné UV mapování).
Name
enable_pbr
Type
boolean
výchozí false
Description
Generovat PBR mapy (kovový, hrubý, normálová) kromě základní barvy. Emisní mapa je také zahrnuta, když ai_model je meshy-6, kromě texture_resolution: 8k. meshy-7 a latest nevytváří emisní mapu.
Name
texture_resolution
Type
string
výchozí 2k
Description
Rozlišení základní barvy textury. Jedno z: 2k (2048×2048), 4k (4096×4096) nebo 8k (8192×8192). Vyšší rozlišení zachycuje více povrchových detailů.
4k a 8k vyžadují ai_modelmeshy-6, meshy-7 nebo latest. Při 8k se nevytváří emisní mapa.
Name
hd_texture
Type
boolean
⚠ zastaralé
výchozí false
Description
Použijte texture_resolution namísto toho — ekvivalentní k texture_resolution: "4k". Když jsou oba nastaveny, texture_resolution má přednost.
Name
remove_lighting
Type
boolean
výchozí true
Description
Odstraní světla a stíny ze základní barvy textura, čímž vytváří čistší výsledek, který lépe funguje při vlastních světelných nastaveních.
Podporováno pouze, když ai_model je meshy-6.
Name
target_formats
Type
string[]
Description
Určuje, které 3D formáty souborů mají být zahrnuty ve výsledku. Budou generovány a vráceny pouze vyžadované formáty, což může snížit dobu dokončení úkolu. Když je vynechán, jsou zahrnuty všechny podporované formáty.
Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf
Při vynechání jsou generovány všechny formáty kromě 3mf. 3mf je zahrnuto pouze, když je výslovně specifikováno.
Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Když je nastaveno na true, úkol navíc vytvoří verzi s průhledným pozadím (RGBA) náhledu a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Stávající pole thumbnail_url je nezměněno.
Vrátí
Vlastnost result v odpovědi obsahuje ID úkolu nově vytvořeného úkolu pro Retexturování.
Selhání režimy
Name
400 - Špatný požadavek
Description
Požadavek byl nepřijatelný. Běžné příčiny:
Chybí parametr: Musí být poskytován buď model_url, nebo input_task_id.
Chybí styl: Musí být poskytována jedna z text_style_prompt, image_style_url nebo multiview_image_urls.
Konfliktní vstupy stylu: multiview_image_urls nelze kombinovat s text_style_prompt nebo image_style_url.
Nepodporovaný model pro více pohledů: multiview_image_urls vyžaduje ai_model: "meshy-7" (nebo latest).
Model není dostupný: ai_model: "meshy-7" je postupně zaváděn a ještě není povolen pro váš účet.
Neplatný vstupní úkol: input_task_id musí odkazovat na úspěšný úkol z podporovaného modelu.
Neplatný formát modelu: model_url ukazuje na soubor s nepodporovanou příponou.
Nepropojitelná URL: model_url, image_style_url nebo prvek multiview_image_urls nemohl být stažen.
Name
401 - Neoprávněný
Description
Autentizace selhala. Prosím zkontrolujte svůj API klíč.
Name
402 - Platba vyžadována
Description
Nedostatečné kredity k provedení tohoto úkolu.
Name
429 - Příliš mnoho požadavků
Description
Překročili jste svůj limit rychlosti.
Požadavek
POST
/openapi/v1/retexture
# Retexturování s textovým promptemcurlhttps://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 }'# Retexturování s obrazovým stylem a 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 úkol pro Retexturování, pokud je zadán platný id úkolu.
Odkaz na Objekt úkolu pro Retexturování zobrazí, které vlastnosti jsou zahrnuty v objektu úkolu pro Retexturování.
Parametry
Name
id
Type
path
Description
Jedinečný identifikátor pro úkol pro Retexturování, který 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 úkolu pro 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
Jedinečný identifikátor pro úkol. I když používáme k-seriálové UUID pro ID úkolů jako implementační detail, neměli byste předpokládat žádné detaily o formátu ID.
Name
type
Type
string
Description
Typ úkolu pro Retexturování. Hodnota je retexture.
Name
model_urls
Type
object
Description
Stahovatelná URL ke strukturovanému 3D modelovému souboru generovanému Meshy.
Name
glb
Type
string
Description
Stahovatelná URL ke GLB souboru.
Name
fbx
Type
string
Description
Stahovatelná URL ke FBX souboru.
Name
obj
Type
string
Description
Stahovatelná URL ke OBJ souboru.
Name
usdz
Type
string
Description
Stahovatelná URL ke USDZ souboru.
Name
mtl
Type
string
Description
Stahovatelná URL ke MTL souboru, vráceno společně s OBJ exporty, když jsou přítomny textury.
Name
stl
Type
string
Description
Stahovatelná URL ke STL souboru.
Name
3mf
Type
string
Description
Stahovatelná URL ke 3MF souboru. Přítomné pouze, když 3mf bylo požadováno prostřednictvím target_formats.
Name
text_style_prompt
Type
string
Description
Toto je textový prompt, který byl použit k vytvoření úkolu texturování.
Name
image_style_url
Type
string
Description
Toto je obrazový vstup, který byl použit k vytvoření úkolu texturování.
Name
multiview_image_urls
Type
string[]
Description
Stahovatelná URL k referenčním obrázkům z více pohledů, které byly použity k vytvoření úkolu texturování. Přítomné pouze, když byl úkol vytvořen pomocí multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Stahovatelné URL k miniatuře obrázku modelového souboru.
Name
alpha_thumbnail_url
Type
string
Description
Stahovatelná URL k verzi thumbnail_url s průhledným pozadím (RGBA). Přítomné pouze, když byl úkol vytvořen 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 úkolu. Pokud úkol ještě není zahájen, tato vlastnost bude 0. Jakmile bude úkol úspěšně dokončen, stane se 100.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byl úkol zahájen, v milisekundách. Pokud úkol ještě není zahájen, tato vlastnost bude 0.
Časové razítko představuje počet milisekund, které uplynuly od 1. ledna, 1970 UTC, dle
RFC 3339 standardu.
Například, pátek, 1. září 2023 12:00:00 PM GMT je reprezentováno jako 1693569600000. To platí
pro všechna časová razítka v Meshy API.
Name
created_at
Type
timestamp
Description
Časové razítko, kdy byl úkol vytvořen, v milisekundách.
Name
expires_at
Type
timestamp
Description
Časové razítko, kdy vyprší výsledek úkolu, v milisekundách.
Name
finished_at
Type
timestamp
Description
Časové razítko, kdy byl úkol dokončen, v milisekundách. Pokud úkol ještě není dokončen, tato vlastnost bude 0.
Name
status
Type
string
Description
Stav úkolu. Možné hodnoty jsou jedním z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Pole objektů URL textur, které jsou generovány z úkolu. Normálně obsahuje pouze jeden objekt URL textury. Každá URL textury má následující vlastnosti:
Name
base_color
Type
string
Description
Stahovatelná URL ke základní barvě mapy obrazu.
Name
metallic
Type
string
Description
Stahovatelná URL ke kovové mapě obrazu.
Pokud je úkol vytvořen s enable_pbr: false, tato vlastnost bude vynechána.
Name
normal
Type
string
Description
Stahovatelná URL ke normálové mapě obrazu.
Pokud je úkol vytvořen s enable_pbr: false, tato vlastnost bude vynechána.
Name
roughness
Type
string
Description
Stahovatelná URL ke hrubé mapě obrazu.
Pokud je úkol vytvořen s enable_pbr: false, tato vlastnost bude vynechána.
Name
emission
Type
string
Description
Stahovatelná URL k emisní mapě obrazu.
Pokud je úkol vytvořen 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 úkolů.
Tato vlastnost je k dispozici pouze, když je stav úkolu PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybách pro neúspěšné úkoly. Viz Chyby pro úplnou referenci objektu task_error.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných tímto úkolem. K dispozici, když stav úkolu je PENDING, IN_PROGRESS nebo SUCCEEDED. Vrátí 0 pro úkoly FAILED (kredity jsou vráceny při neúspěchu).
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}