Retexture API is een functie die je toestaat om de AI-hertextureringsmogelijkheden van Meshy in je eigen applicatie te integreren. In deze sectie vind je alle informatie die je nodig hebt om te beginnen met deze API.
Deze endpoint staat je toe om een nieuwe Hertextureringstaak te maken. Raadpleeg Het Hertextureringstaak Object om te zien welke eigenschappen zijn opgenomen in het hertextureringstaak object.
Parameters
Slechts één van input_task_id of model_url is vereist. Als beide worden verstrekt, 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 wilt hertextureren. Deze taak moet een van de volgende taken zijn: Tekst naar 3D Voorbeeld, Tekst naar 3D Verfijn, Afbeelding naar 3D of Remesh. Bovendien moet het een status van SUCCEEDED hebben.
Name
model_url
Type
string
Verplicht
Description
Bied een 3D-model aan dat Meshy moet textureren. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl.
Er zijn twee manieren om het model aan te bieden:
Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het publieke internet.
Data URI: Een base64-gecodeerde data URI van het model. Gebruik MIME type application/octet-stream. Voorbeeld: data:application/octet-stream;base64,<your base64-encoded model data>.
Precies één stijlinput is vereist: 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 verstrekt, heeft image_style_url prioriteit.
Name
text_style_prompt
Type
string
Verplicht
Description
Beschrijf je gewenste textuurstijl van het object met tekst. Maximaal 600 karakters.
Name
image_style_url
Type
string
Verplicht
Description
Bied een 2D-afbeelding om het textureringsproces te begeleiden. We ondersteunen momenteel .jpg, .jpeg, en .png formaten.
Er zijn twee manieren om de afbeelding aan te bieden:
Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het publieke internet.
Data URI: Een base64-gecodeerde data URI van de afbeelding. Voorbeeld van een data URI: data:image/jpeg;base64,<your base64-encoded image data>
Afbeelding texturering kan niet optimaal werken als er aanzienlijke geometrieverschillen zijn tussen het originele asset en de geüploade afbeelding.
Name
multiview_image_urls
Type
string[]
Verplicht
Description
Bied 1 tot 4 afbeeldingen van hetzelfde object uit verschillende hoeken om de texturering te begeleiden. De eerste afbeelding is de primaire (voor)weergave; de volgorde van de overige weergaven (links, achter, rechts) doet er niet toe.
Elk element accepteert dezelfde formaten als image_style_url (een publiek toegankelijke URL of een base64 data URI, .jpg/.jpeg/.png).
Vereist ai_model: "meshy-7" (of latest).
Name
ai_model
Type
string
standaard latest
Description
ID van het AI-model om te gebruiken voor hertexturering. 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 hertexturert dat Meshy heeft gegenereerd (via input_task_id, of een model_url die naar een Meshy-uitvoer verwijst), stel dit in op true om zijn geoptimaliseerde UV-layout opnieuw te gebruiken.
Als je een third-party model dat je hebt geüpload hertexturert, stel true in wanneer het al goede UV's heeft die je wilt behouden, of laat het false om Meshy verse UV's te laten uitvouwen (beste voor modellen die geen goede UV-mapping hebben).
Name
enable_pbr
Type
boolean
standaard false
Description
Genereer PBR-maps (metallic, roughness, normal) naast de basiskleur. Een emissie-map is ook inbegrepen wanneer ai_modelmeshy-6 is, behalve bij texture_resolution: 8k. meshy-7 en latest produceren geen emissie-map.
Name
texture_resolution
Type
string
standaard 2k
Description
Basis kleur textuurresolutie. Een van 2k (2048×2048), 4k (4096×4096), of 8k (8192×8192). Hogere resoluties vangen meer oppervlakdetail.
4k en 8k vereisen ai_modelmeshy-6, meshy-7 of latest. Bij 8k wordt geen emissie-map geproduceerd.
Name
hd_texture
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik texture_resolution in plaats daarvan — gelijk aan texture_resolution: "4k". Wanneer beide zijn ingesteld, heeft texture_resolution voorrang.
Name
remove_lighting
Type
boolean
standaard true
Description
Verwijdert highlights en schaduwen van de basiskleur textuur, wat een schoner resultaat oplevert dat beter werkt onder aangepaste lichtinstellingen.
Alleen ondersteund wanneer ai_modelmeshy-6 is.
Name
target_formats
Type
string[]
Description
Specificeert welke 3D-bestandsformaten in de uitvoering moeten worden opgenomen. Alleen de gevraagde formaten worden gegenereerd en geretourneerd, wat de voltooiingstijd van de taak kan verminderen. Wanneer weggelaten worden alle ondersteunde formaten opgenomen.
Wanneer weggelaten, worden alle formaten behalve 3mf gegenereerd. 3mf is alleen inbegrepen wanneer expliciet opgegeven.
Name
alpha_thumbnail
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak ook een versie van de preview met een transparante achtergrond (RGBA) en retourneert deze als alpha_thumbnail_url in de GET-response. Het bestaande thumbnail_url-veld blijft ongewijzigd.
Returns
De result eigenschap van de response bevat de taak id van de nieuw gecreëerde Hertextureringstaak.
Failure Modes
Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
Missende parameter: Ofwel model_url of input_task_id moet worden verstrekt.
Missende stijl: Eén van text_style_prompt, image_style_url of multiview_image_urls moet worden verstrekt.
Conflicterende stijlinputs: 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 ai_model: "meshy-7" (of latest).
Model niet beschikbaar: ai_model: "meshy-7" wordt geleidelijk uitgerold en is nog niet ingeschakeld voor jouw account.
Ongeldige inputtaak: De input_task_id moet verwijzen naar een succesvolle taak van een ondersteund model.
Ongeldig modelformaat: De model_url verwijst naar een bestand met een niet-ondersteunde extensie.
Onbereikbare URL: De model_url, image_style_url of een element van multiview_image_urls kon niet worden gedownload.
Name
401 - Unauthorized
Description
Authenticatie 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
# Hertextureren met tekstpromptcurlhttps://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 }'# Hertextureren met beeldstijl en 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 staat je toe om een Hertextureringstaak op te halen gezien een geldige taak id.
Raadpleeg Het Hertextureringstaak Object om te zien welke
eigenschappen zijn opgenomen in het hertextureringstaak object.
Parameters
Name
id
Type
path
Description
Unieke identificatie voor de Hertextureringstaak om op te halen.
{"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 Hertextureringstaak object is een werkunit die Meshy gebruikt om een 3D textuur te genereren uit tekst of afbeelding invoeren. Het model heeft de volgende eigenschappen:
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak. Terwijl we een k-sorteerbare UUID gebruiken als taak id’s als implementatiedetail, moet je geen aannames maken over het formaat van de id.
Name
type
Type
string
Description
Type van de Hertextureringstaak. De waarde is retexture.
Name
model_urls
Type
object
Description
Downloadbare URL naar het getextureerde 3D-modelbestand gegenereerd door Meshy.
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, geretourneerd naast OBJ-exporten wanneer 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 werd gebruikt om de textureringstaak te maken.
Name
image_style_url
Type
string
Description
Dit is de afbeeldinginvoer die werd gebruikt om de textureringstaak te maken.
Name
multiview_image_urls
Type
string[]
Description
Downloadbare URL's naar de multi-view referentieafbeeldingen die werden gebruikt om de textureringstaak te maken. Alleen aanwezig wanneer de taak werd gecreëerd met multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Downloadbare URL naar de thumbnailafbeelding van het modelbestand.
Name
alpha_thumbnail_url
Type
string
Description
Downloadbare URL naar een versie met transparante achtergrond (RGBA) van thumbnail_url. Alleen aanwezig wanneer de taak werd gecreëerd met alpha_thumbnail: true en de transparante preview succesvol was gerenderd; anders wordt dit veld weggelaten.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, wordt dit 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, zal deze eigenschap 0 zijn.
Een tijdstempel vertegenwoordigt het aantal milliseconden 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 gemaakt, 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, wordt 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 gegenereerd zijn van de taak. Normaal bevat dit slechts één textuur URL-object. Elk texture URL heeft de volgende eigenschappen:
Name
base_color
Type
string
Description
Downloadbare URL naar de basis kleur map afbeelding.
Name
metallic
Type
string
Description
Downloadbare URL naar de metallic map afbeelding.
Als de taak is gemaakt met enable_pbr: false, zal deze eigenschap worden weggelaten.
Name
normal
Type
string
Description
Downloadbare URL naar de normal map afbeelding.
Als de taak is gemaakt met enable_pbr: false, zal deze eigenschap worden weggelaten.
Name
roughness
Type
string
Description
Downloadbare URL naar de roughness map afbeelding.
Als de taak is gemaakt met enable_pbr: false, zal deze eigenschap worden weggelaten.
Name
emission
Type
string
Description
Downloadbare URL naar de emissie map afbeelding.
Als de taak is gemaakt met enable_pbr: false, of ai_modelmeshy-5 is, zal deze eigenschap worden weggelaten.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken.
Deze eigenschap is alleen aanwezig wanneer de taakstatus PENDING is.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.
Name
consumed_credits
Type
integer
Description
Het aantal verbruikte credits door deze taak. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS, of SUCCEEDED is. Retourneert 0 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}