Retexture API is een functie waarmee je de AI-hertextureringsmogelijkheden van Meshy in je eigen applicatie kunt integreren. In dit gedeelte vind je alle informatie
die je nodig hebt om aan de slag te gaan met deze API.
Deze endpoint stelt je in staat om een nieuwe Retexture-taak aan te maken. Raadpleeg
The Retexture Task Object om te zien welke
eigenschappen zijn opgenomen in het Retexture task object.
Parameters
Slechts één van input_task_id of model_url is verplicht. Als beide worden opgegeven, heeft input_task_id prioriteit.
Name
input_task_id
Type
string
Verplicht
Description
De ID van de voltooide Afbeelding naar 3D- of Tekst naar 3D-taak die je opnieuw wilt textureren.
Deze taak moet een van de volgende taken zijn: Text to 3D Preview, Text to 3D Refine, Image to 3D of Remesh. Daarnaast moet de status SUCCEEDED zijn.
Name
model_url
Type
string
Verplicht
Description
Lever een 3D-model aan zodat Meshy het kan textureren. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl.
Er zijn twee manieren om het model aan te leveren:
Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet.
Data URI: Een base64-gecodeerde data URI van het model. Gebruik MIME type application/octet-stream. Voorbeeld: data:application/octet-stream;base64,<je base64-gecodeerde modeldata>.
Precies één stijlinvoer is verplicht: text_style_prompt, image_style_url of multiview_image_urls. multiview_image_urls kan niet worden gecombineerd met een van de andere twee; als zowel text_style_prompt als image_style_url worden opgegeven, heeft image_style_url prioriteit.
Name
text_style_prompt
Type
string
Verplicht
Description
Beschrijf de gewenste texturestijl van het object met tekst. Maximaal 800 tekens.
Name
image_style_url
Type
string
Verplicht
Description
Lever een 2D-afbeelding aan om het textureringsproces te sturen. We ondersteunen momenteel .jpg, .jpeg en .png formaten.
Er zijn twee manieren om de afbeelding aan te leveren:
Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet
Data URI: Een base64-gecodeerde data URI van de afbeelding. Voorbeeld van een data URI: data:image/jpeg;base64,<je base64-gecodeerde afbeeldingsdata>
Afbeeldingstexturering werkt mogelijk niet optimaal als er aanzienlijke verschillen in geometrie zijn tussen het originele asset en de geüploade afbeelding.
Name
multiview_image_urls
Type
string[]
Verplicht
Description
Lever 1 tot 4 afbeeldingen aan die hetzelfde object vanuit verschillende aanzichten tonen om de texturering te sturen. De eerste afbeelding is het primaire (voor)aanzicht; de volgorde van de overige aanzichten (links, achter, rechts) maakt niet uit.
Elk element accepteert dezelfde formaten als image_style_url (een publiek toegankelijke URL of een base64 data URI, .jpg/.jpeg/.png).
Vereist een expliciete ai_model: "meshy-7".
Name
ai_model
Type
string
standaard latest
Description
ID van het AI-model dat gebruikt wordt voor het hertextureren. Beschikbare waarden: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
standaard false
Description
Behoud de bestaande UV-layout van het model in plaats van een nieuwe te genereren.
Als je een model hertextureert dat Meshy heeft gegenereerd (via input_task_id, of een model_url die verwijst naar een Meshy-output), zet dit dan op true om de geoptimaliseerde UV-layout te hergebruiken.
Als je een door jou geüpload model van derden hertextureert, zet het op true wanneer het al goede UV's heeft die je wilt behouden, of laat het op false staan zodat Meshy nieuwe UV's uitvouwt (het beste voor modellen zonder goede UV-mapping).
Name
enable_pbr
Type
boolean
standaard false
Description
Genereer PBR-maps (metallic, roughness, normal) naast de basiskleur. Er wordt ook een emissiekaart meegeleverd wanneer ai_modelmeshy-6 is, behalve bij texture_resolution: 8k. meshy-7 en latest genereren geen emissiekaart.
Name
texture_resolution
Type
string
standaard 2k
Description
Resolutie van de basiskleurtextuur. Een van 2k (2048×2048), 4k (4096×4096), of 8k (8192×8192). Hogere resoluties leggen meer oppervlaktedetail vast.
4k en 8k vereisen ai_modelmeshy-6, meshy-7 of latest. Bij 8k wordt geen emissiekaart gegenereerd.
Name
hd_texture
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik in plaats daarvan texture_resolution — equivalent aan texture_resolution: "4k". Wanneer beide zijn ingesteld, heeft texture_resolution voorrang.
Name
remove_lighting
Type
boolean
standaard true
Description
Verwijdert highlights en schaduwen uit de basiskleurtextuur, wat een schoner resultaat oplevert dat beter werkt onder aangepaste belichtingsopstellingen.
Alleen ondersteund wanneer ai_modelmeshy-6 is.
Name
target_formats
Type
string[]
Description
Geeft aan welke 3D-bestandsformaten in de output moeten worden opgenomen. Alleen de gevraagde formaten worden gegenereerd en geretourneerd, wat de voltooiingstijd van de taak kan verkorten. Indien weggelaten, worden alle ondersteunde formaten opgenomen.
Indien weggelaten, worden alle formaten behalve 3mf gegenereerd. 3mf wordt alleen meegeleverd wanneer expliciet opgegeven.
Name
alpha_thumbnail
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak bovendien een versie van de preview met transparante achtergrond (RGBA) en retourneert deze als alpha_thumbnail_url in de GET-response. Het bestaande veld thumbnail_url blijft ongewijzigd.
Resultaten
De result-eigenschap van de response bevat de taak-id van de nieuw aangemaakte Retexture-taak.
Faalmodi
Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
Ontbrekende parameter: Ofwel model_url ofwel input_task_id moet worden opgegeven.
Ontbrekende stijl: Een van text_style_prompt, image_style_url of multiview_image_urls moet worden opgegeven.
Conflicterende stijlinvoer: multiview_image_urls kan niet worden gecombineerd met text_style_prompt of image_style_url.
Niet-ondersteund model voor multi-view: multiview_image_urls vereist een expliciete ai_model: "meshy-7".
Model niet beschikbaar: ai_model: "meshy-7" wordt geleidelijk uitgerold en is nog niet ingeschakeld voor jouw account.
Ongeldige inputtaak: input_task_id moet verwijzen naar een succesvolle taak van een ondersteund model.
Ongeldig modelformaat: model_url verwijst naar een bestand met een niet-ondersteunde extensie.
Onbereikbare URL: model_url, image_style_url of een element van multiview_image_urls kon niet worden gedownload.
Name
401 - Unauthorized
Description
Authenticatie is mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden.
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 }'
Deze endpoint stelt je in staat om een Hertextureren-taak op te halen op basis van een geldige id.
Raadpleeg Het Retexture-taakobject om te zien welke
eigenschappen zijn opgenomen in het Hertextureren-taakobject.
Parameters
Name
id
Type
path
Description
Unieke identificatiecode van de Hertextureren-taak die moet worden opgehaald.
Resultaten
De respons bevat het Hertextureren-taakobject. Raadpleeg de sectie
Het Retexture-taakobject voor details.
{"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 }]
Het Retexture-taakobject is een werkeenheid die Meshy gebruikt om een 3D-textuur te genereren op basis van tekst- of afbeeldingsinvoer.
Het model heeft de volgende eigenschappen:
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als
implementatiedetail, mag je geen aannames doen over de indeling van de id.
Name
type
Type
string
Description
Type van de Retexture-taak. De waarde is retexture.
Name
model_urls
Type
object
Description
Downloadbare URL naar het getextureerde 3D-modelbestand dat door Meshy is gegenereerd.
Name
glb
Type
string
Description
Downloadbare URL naar het GLB-bestand.
Name
fbx
Type
string
Description
Downloadbare URL naar het FBX-bestand.
Name
obj
Type
string
Description
Downloadbare URL naar het OBJ-bestand.
Name
usdz
Type
string
Description
Downloadbare URL naar het USDZ-bestand.
Name
mtl
Type
string
Description
Downloadbare URL naar het MTL-bestand, meegeleverd bij OBJ-exports wanneer er texturen aanwezig zijn.
Name
stl
Type
string
Description
Downloadbare URL naar het STL-bestand.
Name
3mf
Type
string
Description
Downloadbare URL naar het 3MF-bestand. Alleen aanwezig wanneer 3mf is aangevraagd via target_formats.
Name
text_style_prompt
Type
string
Description
Dit is de tekstprompt die is gebruikt om de textureringstaak te maken.
Name
image_style_url
Type
string
Description
Dit is de afbeeldingsinvoer die is gebruikt om de textureringstaak te maken.
Name
multiview_image_urls
Type
string[]
Description
Downloadbare URL's naar de referentieafbeeldingen met meerdere aanzichten die zijn gebruikt om de textureringstaak te maken. Alleen aanwezig wanneer de taak is gemaakt met multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Downloadbare URL naar de thumbnail-afbeelding van het modelbestand.
Name
alpha_thumbnail_url
Type
string
Description
Downloadbare URL naar een versie van thumbnail_url met transparante achtergrond (RGBA). Alleen aanwezig wanneer de taak is gemaakt met alpha_thumbnail: true en de transparante preview succesvol is gerenderd; anders wordt dit veld weggelaten.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.
Een tijdstempel geeft het aantal milliseconden weer dat is verstreken sinds 1 januari 1970 UTC, volgens
de RFC 3339-standaard.
Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt
voor alle tijdstempels in Meshy API.
Name
created_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.
Name
expires_at
Type
timestamp
Description
Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.
Name
finished_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden zijn een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Een array van textuur-URL-objecten die door de taak zijn gegenereerd. Normaal gesproken bevat dit slechts één textuur-URL-object. Elke textuur-URL heeft de volgende eigenschappen:
Name
base_color
Type
string
Description
Downloadbare URL naar de basiskleurenkaart-afbeelding.
Name
metallic
Type
string
Description
Downloadbare URL naar de metallic map-afbeelding.
Als de taak is gemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
Name
normal
Type
string
Description
Downloadbare URL naar de normal map-afbeelding.
Als de taak is gemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
Name
roughness
Type
string
Description
Downloadbare URL naar de roughness map-afbeelding.
Als de taak is gemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
Name
emission
Type
string
Description
Downloadbare URL naar de emission map-afbeelding.
Als de taak is gemaakt met enable_pbr: false, of ai_modelmeshy-5 is, wordt deze eigenschap weggelaten.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande taken.
Deze eigenschap is alleen aanwezig wanneer de taakstatus PENDING is.
Name
task_error
Type
object
Description
Foutgegevens voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS, of SUCCEEDED is. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij mislukking).
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}