Omtexturering API är en funktion som låter dig integrera Meshys AI-omtextureringsmöjligheter i din egen applikation. I det här avsnittet hittar du all information
du behöver för att komma igång med detta API.
Denna endpoint låter dig skapa en ny Omtexturering-uppgift. Se
The Retexture Task Object för att se vilka
egenskaper som ingår i objektet för Omtexturering-uppgifter.
Parametrar
Endast en av input_task_id eller model_url är obligatorisk. Om båda anges tar input_task_id prioritet.
Name
input_task_id
Type
string
Obligatorisk
Description
ID för den slutförda Bild till 3D- eller Text till 3D-uppgiften som du vill omtexturera.
Denna uppgift måste vara en av följande: Text till 3D förhandsvisning, Text till 3D förfining, Bild till 3D eller Remesh. Dessutom måste den ha statusen SUCCEEDED.
Name
model_url
Type
string
Obligatorisk
Description
Ange en 3D-modell som Meshy ska texturera. Stödda format: .glb, .gltf, .obj, .fbx, .stl.
Det finns två sätt att ange modellen:
Publikt tillgänglig URL: En URL som är åtkomlig från det publika internet.
Data URI: En base64-kodad data URI av modellen. Använd MIME type application/octet-stream. Exempel: data:application/octet-stream;base64,<din base64-kodade modelldata>.
Exakt en stilinmatning är obligatorisk: text_style_prompt, image_style_url, eller multiview_image_urls. multiview_image_urls kan inte kombineras med någon av de andra två; om både text_style_prompt och image_style_url anges, tar image_style_url prioritet.
Name
text_style_prompt
Type
string
Obligatorisk
Description
Beskriv den önskade texturstilen för objektet med text. Maximalt 800 tecken.
Name
image_style_url
Type
string
Obligatorisk
Description
Ange en 2d-bild för att styra textureringsprocessen. Vi stödjer för närvarande .jpg, .jpeg, och .png-format.
Det finns två sätt att ange bilden:
Publikt tillgänglig URL: En URL som är åtkomlig från det publika internet
Data URI: En base64-kodad data URI av bilden. Exempel på en data URI: data:image/jpeg;base64,<din base64-kodade bilddata>
Bildtexturering kan fungera suboptimalt om det finns betydande geometriska skillnader mellan den ursprungliga tillgången och den uppladdade bilden.
Name
multiview_image_urls
Type
string[]
Obligatorisk
Description
Ange 1 till 4 bilder som visar samma objekt från olika vinklar för att styra textureringen. Den första bilden är den primära (fram) vyn; ordningen på de återstående vyerna (vänster, bak, höger) spelar ingen roll.
Varje element accepterar samma format som image_style_url (en publikt tillgänglig URL eller en base64 data URI, .jpg/.jpeg/.png).
Kräver en explicit ai_model: "meshy-7".
Name
ai_model
Type
string
standard latest
Description
ID för den AI-modell som ska användas för omtexturering. Tillgängliga värden: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
standard false
Description
Behåll modellens befintliga UV-layout istället för att generera en ny.
Om du omtexturerar en modell som Meshy har genererat (via input_task_id, eller en model_url som pekar på en Meshy-utdata), sätt detta till true för att återanvända dess optimerade UV-layout.
Om du omtexturerar en tredjepartsmodell du har laddat upp, sätt true när den redan har bra UV:er du vill behålla, eller lämna det som false för att låta Meshy packa upp nya UV:er (bäst för modeller som saknar korrekt UV-mappning).
Name
enable_pbr
Type
boolean
standard false
Description
Generera PBR-mappar (metallic, roughness, normal) utöver basfärgen. En emissionsmapp inkluderas också när ai_model är meshy-6, förutom vid texture_resolution: 8k. meshy-7 och latest producerar inte en emissionsmapp.
Name
texture_resolution
Type
string
standard 2k
Description
Upplösning för basfärgstextur. En av 2k (2048×2048), 4k (4096×4096), eller 8k (8192×8192). Högre upplösningar fångar mer ytdetalj.
4k och 8k kräver ai_modelmeshy-6, meshy-7 eller latest. Vid 8k produceras ingen emissionsmapp.
Name
hd_texture
Type
boolean
⚠ föråldrad
standard false
Description
Använd texture_resolution istället — motsvarar texture_resolution: "4k". När båda anges tar texture_resolution prioritet.
Name
remove_lighting
Type
boolean
standard true
Description
Tar bort highlights och skuggor från basfärgstexturen, vilket ger ett renare resultat som fungerar bättre med anpassade ljussättningar.
Stöds endast när ai_model är meshy-6.
Name
target_formats
Type
string[]
Description
Anger vilka 3D-filformat som ska ingå i utdatan. Endast de begärda formaten kommer att genereras och returneras, vilket kan minska tiden det tar att slutföra uppgiften. Om det utelämnas inkluderas alla stödda format.
Om det utelämnas genereras alla format förutom 3mf. 3mf inkluderas endast när det anges explicit.
Name
alpha_thumbnail
Type
boolean
standard false
Description
När det sätts till true renderar uppgiften dessutom en version med transparent bakgrund (RGBA) av förhandsvisningen och returnerar den som alpha_thumbnail_url i GET-svaret. Det befintliga thumbnail_url-fältet förblir oförändrat.
Returvärden
Egenskapen result i svaret innehåller uppgifts-id:et för den nyligen skapade Omtexturering-uppgiften.
Felläge
Name
400 - Bad Request
Description
Förfrågan var inte godtagbar. Vanliga orsaker:
Saknad parameter: Antingen model_url eller input_task_id måste anges.
Saknad stil: En av text_style_prompt, image_style_url eller multiview_image_urls måste anges.
Konflikterande stilinmatningar: multiview_image_urls kan inte kombineras med text_style_prompt eller image_style_url.
Ostödd modell för flervy: multiview_image_urls kräver en explicit ai_model: "meshy-7".
Modell inte tillgänglig: ai_model: "meshy-7" rullas ut stegvis och är ännu inte aktiverad för ditt konto.
Ogiltig indata-uppgift: input_task_id måste referera till en lyckad uppgift från en stödd modell.
Ogiltigt modellformat: model_url pekar på en fil med ett ostödd filändelse.
Onåbar URL: model_url, image_style_url eller ett element i multiview_image_urls kunde inte laddas ner.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.
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 }'
Detta endpoint tillåter dig att hämta en Omtexturering uppgift givet ett giltigt uppgifts-id.
Se Omtexturering Uppgiftsobjektet för att se vilka
egenskaper som ingår i Omtexturering uppgiftsobjektet.
Parametrar
Name
id
Type
path
Description
Unik identifierare för Omtexturering uppgiften att hämta.
{"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 }]
Objektet för Omtexturering är en arbetsenhet som Meshy använder för att generera en 3D-textur från antingen text- eller bildinmatningar. Modellen har följande egenskaper:
Egenskaper
Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder ett k-sorterbart UUID för uppgifts-id som implementeringsdetalj, bör du inte göra några antaganden om formatet på id.
Name
type
Type
string
Description
Typ av Omtextureringsuppgift. Värdet är retexture.
Name
model_urls
Type
object
Description
Nedladdningsbar URL till den texturerade 3D-modellfilen som genereras av Meshy.
Name
glb
Type
string
Description
Nedladdningsbar URL till GLB-filen.
Name
fbx
Type
string
Description
Nedladdningsbar URL till FBX-filen.
Name
obj
Type
string
Description
Nedladdningsbar URL till OBJ-filen.
Name
usdz
Type
string
Description
Nedladdningsbar URL till USDZ-filen.
Name
mtl
Type
string
Description
Nedladdningsbar URL till MTL-filen, returneras tillsammans med OBJ-exporter när texturer finns.
Name
stl
Type
string
Description
Nedladdningsbar URL till STL-filen.
Name
3mf
Type
string
Description
Nedladdningsbar URL till 3MF-filen. Endast närvarande när 3mf begärdes via target_formats.
Name
text_style_prompt
Type
string
Description
Detta är textprompten som användes för att skapa textureringsuppgiften.
Name
image_style_url
Type
string
Description
Detta är bildinmatningen som användes för att skapa textureringsuppgiften.
Name
multiview_image_urls
Type
string[]
Description
Nedladdningsbara URL:er till flervy-referensbilderna som användes för att skapa textureringsuppgiften. Endast närvarande när uppgiften skapades med multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Nedladdningsbar URL till miniatyrbilden av modellfilen.
Name
alpha_thumbnail_url
Type
string
Description
Nedladdningsbar URL till en version av thumbnail_url med transparent bakgrund (RGBA). Endast närvarande när uppgiften skapades med alpha_thumbnail: true och den transparenta förhandsvisningen renderades framgångsrikt; annars utelämnas detta fält.
Name
progress
Type
integer
Description
Framsteg för uppgiften. Om uppgiften inte har startat ännu kommer denna egenskap att vara 0. När uppgiften har lyckats kommer detta att bli 100.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startat ännu kommer denna egenskap att vara 0.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt
RFC 3339-standarden.
Till exempel, fredag 1 september 2023 12:00:00 GMT representeras som 1693569600000. Detta gäller
för alla tidsstämplar i Meshy API.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftens resultat upphör, i millisekunder.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften inte är avslutad ännu kommer denna egenskap att vara 0.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden är en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
En array av textur-URL-objekt som genereras från uppgiften. Normalt innehåller detta endast ett textur-URL-objekt. Varje textur-URL har följande egenskaper:
Name
base_color
Type
string
Description
Nedladdningsbar URL till basfärgskartan.
Name
metallic
Type
string
Description
Nedladdningsbar URL till metallkartbilden.
Om uppgiften skapas med enable_pbr: false kommer denna egenskap att utelämnas.
Name
normal
Type
string
Description
Nedladdningsbar URL till normalmap-bilden.
Om uppgiften skapas med enable_pbr: false kommer denna egenskap att utelämnas.
Name
roughness
Type
string
Description
Nedladdningsbar URL till grovhetskartbilden.
Om uppgiften skapas med enable_pbr: false kommer denna egenskap att utelämnas.
Name
emission
Type
string
Description
Nedladdningsbar URL till emissionskartbilden.
Om uppgiften skapas med enable_pbr: false, eller ai_model är meshy-5, kommer denna egenskap att utelämnas.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Denna egenskap är endast närvarande när uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Felformationer för misslyckade uppgifter. Se Fel för fullständig referens till task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Närvarande när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).
Exempel på Omtextureringsuppgiftsmodell
{"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}