Hertextureren API is een functie waarmee je de AI-hertextureringsmogelijkheden van Meshy in je eigen applicatie kunt integreren. In deze sectie vind je alle informatie die je nodig hebt om aan de slag te gaan met deze API.
Met deze endpoint kunt u een nieuwe Retexture-taak aanmaken. Raadpleeg
Het Retexture Task Object om te zien welke
eigenschappen bij het Retexture-taakobject horen.
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 u 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. Bovendien moet de status SUCCEEDED zijn.
Name
model_url
Type
string
Verplicht
Description
Geef een 3D-model op dat Meshy moet textureren. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl.
Er zijn twee manieren om het model op te geven:
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,<uw base64-gecodeerde modelgegevens>.
Precies één stijl-invoer 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 textuurstijl van het object met tekst. Maximaal 800 tekens.
Name
image_style_url
Type
string
Verplicht
Description
Geef een 2d-afbeelding op om het textureringsproces te sturen. We ondersteunen momenteel de formaten .jpg, .jpeg en .png.
Er zijn twee manieren om de afbeelding op te geven:
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,<uw base64-gecodeerde afbeeldingsgegevens>
Afbeeldingstexturering werkt mogelijk niet optimaal als er aanzienlijke geometrieverschillen zijn tussen het originele asset en de geüploade afbeelding.
Name
multiview_image_urls
Type
string[]
Verplicht
Description
Geef 1 tot 4 afbeeldingen op 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 wordt gebruikt 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 u een model opnieuw textureert dat door Meshy is gegenereerd (via input_task_id, of een model_url die verwijst naar een Meshy-uitvoer), zet dit dan op true om de geoptimaliseerde UV-layout ervan te hergebruiken.
Als u een door u geüpload model van derden opnieuw textureert, zet dit op true wanneer het al goede UV's heeft die u wilt behouden, of laat het op false staan zodat Meshy nieuwe UV's uitrolt (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 toegevoegd wanneer ai_modelmeshy-6 is, behalve bij texture_resolution: 8k. meshy-7 en latest produceren 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 oppervlaktedetails vast.
4k en 8k vereisen ai_modelmeshy-6, meshy-7 of latest. Bij 8k wordt geen emissiekaart geproduceerd.
Name
hd_texture
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik in plaats daarvan texture_resolution — gelijk aan texture_resolution: "4k". Als beide zijn ingesteld, heeft texture_resolution voorrang.
Name
remove_lighting
Type
boolean
standaard true
Description
Verwijdert hoogtelichten en schaduwen uit de basiskleurtextuur, wat een schoner resultaat oplevert dat beter werkt bij aangepaste belichtingsopstellingen.
Alleen ondersteund wanneer ai_modelmeshy-6 is.
Name
target_formats
Type
string[]
Description
Specificeert welke 3D-bestandsformaten in de uitvoer moeten worden opgenomen. Alleen de gevraagde formaten worden gegenereerd en teruggegeven, wat de doorlooptijd van de taak kan verkorten. Indien weggelaten, worden alle ondersteunde formaten opgenomen.
Indien weggelaten, worden alle formaten behalve 3mf gegenereerd. 3mf wordt alleen opgenomen wanneer dit expliciet wordt opgegeven.
Name
alpha_thumbnail
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak bovendien een versie met transparante achtergrond (RGBA) van de preview en geeft deze terug als alpha_thumbnail_url in het GET-antwoord. Het bestaande veld thumbnail_url blijft ongewijzigd.
Retourwaarden
De result-eigenschap van het antwoord bevat de taak-id van de nieuw aangemaakte Retexture-taak.
Faalscenario's
Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
Ontbrekende parameter: Er moet ofwel model_url of input_task_id worden opgegeven.
Ontbrekende stijl: Een van text_style_prompt, image_style_url of multiview_image_urls moet worden opgegeven.
Conflicterende stijl-invoer: multiview_image_urls kan niet worden gecombineerd met text_style_prompt of image_style_url.
Niet-ondersteund model voor meerdere aanzichten: 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 uw account.
Ongeldige invoertaak: 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 uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
429 - Too Many Requests
Description
U heeft uw 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 met een geldig taak id.
Raadpleeg Het Hertextureren Taak Object om te zien welke
eigenschappen zijn opgenomen in het Hertextureren taak object.
Parameters
Name
id
Type
path
Description
Unieke identificatie voor de Hertextureren taak 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 Hertextureren Taak object is een werkunit die Meshy gebruikt om een 3D textuur te genereren vanuit tekst- of afbeeldingsinvoer. Het model heeft de volgende eigenschappen:
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we een k-sortable UUID gebruiken voor taak-id's als implementatiedetail, moet je geen aannames maken over het formaat van de id.
Name
type
Type
string
Description
Type van de Hertextureren taak. 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 creëren.
Name
image_style_url
Type
string
Description
Dit is de afbeeldingsinvoer die werd gebruikt om de textureringstaak te creëren.
Name
multiview_image_urls
Type
string[]
Description
Downloadbare URL's naar de meerdere aanzichten referentieafbeeldingen die werden gebruikt om de textureringstaak te creëren. Alleen aanwezig wanneer de taak werd gecreëerd 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 transparante achtergrond (RGBA) versie van thumbnail_url. Alleen aanwezig wanneer de taak werd gecreëerd met alpha_thumbnail: true en de transparante preview succesvol werd gerenderd; anders wordt dit veld weggelaten.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, zal deze eigenschap 0 zijn. Zodra de taak is geslaagd, wordt dit 100.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer de taak werd gestart, in milliseconden. Als de taak nog niet is gestart, 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 werd gecreëerd, 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 werd voltooid, in milliseconden. Als de taak nog niet is voltooid, zal deze eigenschap 0 zijn.
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 zijn gegenereerd vanuit de taak. Normaal bevat dit slechts één textuur URL-object. Elke textuur URL heeft de volgende eigenschappen:
Name
base_color
Type
string
Description
Downloadbare URL naar de basis kleurkaart afbeelding.
Name
metallic
Type
string
Description
Downloadbare URL naar de metallic kaart afbeelding.
Als de taak is gecreëerd 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 gecreëerd met enable_pbr: false, zal deze eigenschap worden weggelaten.
Name
roughness
Type
string
Description
Downloadbare URL naar de roughness kaart afbeelding.
Als de taak is gecreëerd met enable_pbr: false, zal deze eigenschap worden weggelaten.
Name
emission
Type
string
Description
Downloadbare URL naar de emissie kaart afbeelding.
Als de taak is gecreëerd met enable_pbr: false, of ai_model is meshy-5, zal deze eigenschap worden 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
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.
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).
Voorbeeld Hertextureren Taak 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}