Retexture API är en funktion som gör att du kan integrera Meshys AI-omtexturering 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 är obligatorisk. 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 som Meshy ska texturera. Format som stöds: .glb, .gltf, .obj, .fbx, .stl.
Det finns två sätt att tillhandahålla 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,<din base64-kodade modelldata>.
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 den önskade texturstilen 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 tillhandahålla 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,<din base64-kodade bilddata>
Bildtexturering fungerar eventuellt inte optimalt om det finns betydande geometriska skillnader mellan originaltillgå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 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 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-6-lite, 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 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 laddat upp, sätt true när den redan har bra UV:er du vill behålla, eller lämna det 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-6-lite, meshy-7 och latest producerar ingen emissionskarta.
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 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 utdata. Endast de begärda formaten genereras och returneras, vilket kan minska tiden det tar att slutföra uppgiften. Om parametern utelämnas inkluderas alla format som stöds.
Om parametern utelämnas genereras alla format utom 3mf. 3mf inkluderas endast när det anges explicit.
Name
alpha_thumbnail
Type
boolean
standard false
Description
När detta sätts 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
Svarets result-egenskap innehåller id för den nyskapade Omtexturering-uppgiften.
Felscenarier
Name
400 - Bad Request
Description
Förfrågan kunde inte accepteras. 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 stöds inte för flervy: multiview_image_urls kräver en explicit ai_model: "meshy-7".
Modell inte tillgänglig: ai_model: "meshy-7" och ai_model: "meshy-6-lite" rullas ut stegvis och kanske inte är aktiverade för ditt konto ännu.
Ogiltig input-uppgift: 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 hämtas.
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 låter dig hämta en Omtextureringsuppgift givet ett giltigt uppgifts-id.
Se Objektet Omtextureringsuppgift för vilka
egenskaper som ingår i objektet för Omtextureringsuppgift.
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}
Denna endpoint tar bort en omtextureringsuppgift permanent, inklusive alla tillhörande modeller och data. Denna åtgärd kan inte ångras.
Sökvägsparametrar
Name
id
Type
path
Description
ID:t för den omtextureringsuppgift som ska tas bort.
Uppgiftsstatus
En uppgift som fortfarande är PENDING tas bort och de credits som
förbrukades vid skapandet återbetalas.
En uppgift som redan är IN_PROGRESS kan inte tas bort: begäran
avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift
som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt i körningen
skulle kosta dig både creditsen och resultatet. Vänta tills den når
SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.
En uppgift i ett slutgiltigt tillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort
utan återbetalning.
Returer
Returnerar 200 OK vid lyckad borttagning, eller 409 Conflict när uppgiften
är IN_PROGRESS.
// 200 OK on success, with an empty body.//// 409 Conflict when the task is IN_PROGRESS — the task is left running:{"message":"Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."}
[ {"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 }]
Retextureringsuppgiftsobjektet ä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 id:ts format.
Name
type
Type
string
Description
Typ av Omtexturering-uppgift. Värdet är retexture.
Name
model_urls
Type
object
Description
Nedladdningsbar URL till den textursatta 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 bildindatan 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. 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 genomskinlig bakgrund (RGBA). Finns endast med när uppgiften skapades med alpha_thumbnail: true och den genomskinliga förhandsvisningen renderades framgångsrikt; annars utelämnas detta fält.
Name
progress
Type
integer
Description
Uppgiftens progress. Om uppgiften inte har startat ännu är denna egenskap 0. När uppgiften har lyckats blir den 100.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startat ännu är denna egenskap 0.
En tidsstämpel representerar antalet millisekunder som förflutit sedan 1 januari 1970 UTC, enligt
standarden RFC 3339.
Till exempel representeras fredag 1 september 2023 12:00:00 PM 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 inte är avslutad ännu är denna egenskap 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 genereras från uppgiften. Vanligtvis innehåller denna 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-kartan.
Name
metallic
Type
string
Description
Nedladdningsbar URL till bildfilen för metallic-kartan.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
normal
Type
string
Description
Nedladdningsbar URL till bildfilen för normalmappen.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
roughness
Type
string
Description
Nedladdningsbar URL till bildfilen för roughness-kartan.
Om uppgiften skapas med enable_pbr: false utelämnas denna egenskap.
Name
emission
Type
string
Description
Nedladdningsbar URL till bildfilen för emission-kartan.
Om uppgiften skapas med enable_pbr: false, eller ai_model är meshy-6-lite, 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
Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga referensen för 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}