Omtexturerings-API är en funktion som gör att du kan integrera Meshys AI-omtextureringsfunktioner 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 Omtexturering-uppgiftsobjektet.
Parametrar
Endast en av input_task_id eller model_url krävs. Om båda anges har input_task_id prioritet.
Name
input_task_id
Type
string
Obligatorisk
Description
ID:t för den slutförda Bild till 3D- eller Text till 3D-uppgiften du vill omtexturera.
Denna uppgift måste vara en av följande: Text till 3D Preview, Text till 3D Refine, Bild till 3D eller Remesh. Dessutom måste den ha statusen SUCCEEDED.
Name
model_url
Type
string
Obligatorisk
Description
Ange en 3D-modell för Meshy att texturera. Format som stöds: .glb, .gltf, .obj, .fbx, .stl.
Det finns två sätt att ange modellen:
Offentligt tillgänglig URL: En URL som är tillgänglig från det publika internet.
Data URI: En base64-kodad data-URI för modellen. Använd MIME type application/octet-stream. Exempel: data:application/octet-stream;base64,<your base64-encoded model data>.
Exakt en stilinmatning krävs: 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 har image_style_url prioritet.
Name
text_style_prompt
Type
string
Obligatorisk
Description
Beskriv önskad texturstil för objektet med text. Max 800 tecken.
Name
image_style_url
Type
string
Obligatorisk
Description
Ange en 2d-bild för att styra textureringsprocessen. Vi stöder för närvarande formaten .jpg, .jpeg och .png.
Det finns två sätt att ange bilden:
Offentligt tillgänglig URL: En URL som är tillgänglig från det publika internet
Data URI: En base64-kodad data-URI för bilden. Exempel på en data-URI: data:image/jpeg;base64,<your base64-encoded image data>
Bildtexturering kanske inte fungerar optimalt om det finns betydande geometriska skillnader mellan originalobjektet 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 huvudvyn (framifrån); ordningen på de återstående vyerna (vänster, bak, höger) spelar ingen roll.
Varje element accepterar samma format som image_style_url (en offentligt tillgänglig URL eller en base64-data-URI, .jpg/.jpeg/.png).
Kräver ett explicit ai_model: "meshy-7".
Name
ai_model
Type
string
standard latest
Description
ID för AI-modellen 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-output), 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 den 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 emissionskarta ingår också när ai_model är meshy-6, förutom vid texture_resolution: 8k. meshy-7 och latest producerar inte någon emissionskarta.
Name
texture_resolution
Type
string
standard 2k
Description
Upplösning för basfärgstexturen. Antingen 2k (2048×2048), 4k (4096×4096) eller 8k (8192×8192). Högre upplösningar fångar mer ytdetaljer.
4k och 8k kräver ai_modelmeshy-6, meshy-7 eller latest. Vid 8k produceras ingen emissionskarta.
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 har texture_resolution företräde.
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 resultatet. 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 format som stöds.
Om det utelämnas genereras alla format utom 3mf. 3mf inkluderas endast när det uttryckligen anges.
Name
alpha_thumbnail
Type
boolean
standard false
Description
När det är satt till true renderar uppgiften dessutom en version av förhandsgranskningen med transparent bakgrund (RGBA) och returnerar den som alpha_thumbnail_url i GET-svaret. Det befintliga fältet thumbnail_url förblir oförändrat.
Returvärden
Egenskapen result i svaret innehåller uppgifts-id:t för den nyligen skapade Omtexturering-uppgiften.
Felorsaker
Name
400 - Bad Request
Description
Begäran var oacceptabel. 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.
Motstridiga stilinmatningar: multiview_image_urls kan inte kombineras med text_style_prompt eller image_style_url.
Modell som inte stöds för flervy: multiview_image_urls kräver ett 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 indatauppgift: input_task_id måste referera till en lyckad uppgift från en modell som stöds.
Ogiltigt modellformat: model_url pekar på en fil med ett filtillägg som inte stöds.
Onåbar URL: model_url, image_style_url eller ett element i multiview_image_urls kunde inte laddas ner.
Name
401 - Unauthorized
Description
Autentiseringen misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med 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 }'
Denna endpoint gör det möjligt att hämta en omtextureringsuppgift utifrån ett giltigt uppgifts-id.
Se Objektet för omtextureringsuppgift för att se vilka
egenskaper som ingår i objektet för omtextureringsuppgiften.
Parametrar
Name
id
Type
path
Description
Unik identifierare för den omtextureringsuppgift som ska hämtas.
{"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 }]
Retexture Task-objektet är en arbetsenhet som Meshy använder för att generera en 3D-textur från antingen text- eller bildindata.
Modellen har följande egenskaper:
Egenskaper
Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id:n som
implementationsdetalj, bör du inte göra några antaganden om formatet på id:t.
Name
type
Type
string
Description
Typ av Retexture-uppgift. Värdet är retexture.
Name
model_urls
Type
object
Description
Nedladdningsbar URL till den texturerade 3D-modellfilen som genererats 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. Finns endast med 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 bildindata som användes för att skapa textureringsuppgiften.
Name
multiview_image_urls
Type
string[]
Description
Nedladdningsbara URL:er till de flervy-referensbilder som användes för att skapa textureringsuppgiften. Finns endast med 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). Finns endast med 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
Uppgiftens framsteg. Om uppgiften ännu inte har startat kommer denna egenskap att vara 0. Så snart uppgiften har lyckats blir detta 100.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften ännu inte har startat kommer denna egenskap att vara 0.
En tidsstämpel representerar antalet millisekunder som förflutit sedan 1 januari 1970 UTC, enligt
standarden RFC 3339.
Till exempel representeras fredagen den 1 september 2023 kl. 12:00:00 GMT 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 att gälla, i millisekunder.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften ännu inte är avslutad kommer denna egenskap att vara 0.
Name
status
Type
string
Description
Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
En array av textur-URL-objekt som genererats från uppgiften. Normalt innehåller den endast ett textur-URL-objekt. Varje textur-URL har följande egenskaper:
Name
base_color
Type
string
Description
Nedladdningsbar URL till bildfilen för baskulör (base color map).
Name
metallic
Type
string
Description
Nedladdningsbar URL till bildfilen för metallic map.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
normal
Type
string
Description
Nedladdningsbar URL till bildfilen för normalmap.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
roughness
Type
string
Description
Nedladdningsbar URL till bildfilen för roughness map.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
emission
Type
string
Description
Nedladdningsbar URL till bildfilen för emission map.
Om uppgiften skapas med enable_pbr: false, eller om ai_model är meshy-5, utelämnas denna egenskap.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Denna egenskap finns endast med när uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen till task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns med när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).
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}