Hertextureren-API is een functie waarmee je Meshy's AI-mogelijkheden voor hertextureren in je eigen applicatie kunt integreren. In deze sectie vind je alle informatie
die je nodig hebt om met deze API aan de slag te gaan.
Met dit endpoint kun je een nieuwe Hertextureren-taak maken. Raadpleeg
Het Hertextureren-taakobject om te zien welke
eigenschappen zijn opgenomen in het Hertextureren-taakobject.
Parameters
Slechts één van input_task_id of model_url is vereist. Als beide worden opgegeven, krijgt 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 Preview, Tekst naar 3D Refine, Afbeelding naar 3D of Remesh. Daarnaast moet deze de status SUCCEEDED hebben.
Name
model_url
Type
string
Verplicht
Description
Geef een 3D-model op dat Meshy van textuur moet voorzien. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl.
Er zijn twee manieren om het model op te geven:
Openbaar 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,<your base64-encoded model data>.
Slechts één van text_style_prompt of image_style_url is vereist. Als beide worden opgegeven, krijgt image_style_url prioriteit.
Name
text_style_prompt
Type
string
Verplicht
Description
Beschrijf de gewenste textuurstijl van het object met tekst. Maximaal 600 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:
Openbaar 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,<your base64-encoded image data>
Afbeeldingstexturering werkt mogelijk niet optimaal als er aanzienlijke geometrieverschillen zijn tussen het oorspronkelijke asset en de geüploade afbeelding.
Name
ai_model
Type
string
standaard latest
Description
ID van het AI-model dat moet worden gebruikt voor hertextureren. Beschikbare waarden: meshy-5, meshy-6, latest (Meshy 6).
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 naar een Meshy-output verwijst), stel dit dan in op true om de geoptimaliseerde UV-layout opnieuw te gebruiken.
Als je een geüpload model van derden hertextureert, stel dit dan in op true wanneer het al goede UV's heeft die je wilt behouden, of laat het op false staan om Meshy nieuwe UV's te laten uitpakken (het beste voor modellen zonder correcte UV-mapping).
Name
enable_pbr
Type
boolean
standaard false
Description
Genereer PBR-maps (metallic, roughness, normal) naast de basiskleur. Een emission map wordt ook opgenomen wanneer ai_modelmeshy-6 of latest is.
Name
hd_texture
Type
boolean
standaard false
Description
Genereer de basiskleurtextuur met een 4K-resolutie (4096×4096) voor meer detail.
Alleen ondersteund wanneer ai_modelmeshy-6 of latest is. PBR-maps worden altijd op 2K gegenereerd.
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 of latest is.
Name
target_formats
Type
string[]
Description
Geeft aan welke 3D-bestandsformaten in de output moeten worden opgenomen. Alleen de aangevraagde formaten worden gegenereerd en geretourneerd, wat de voltooiingstijd van de taak kan verkorten. Wanneer dit wordt weggelaten, worden alle ondersteunde formaten opgenomen.
Wanneer dit wordt weggelaten, worden alle formaten behalve 3mf gegenereerd. 3mf wordt alleen opgenomen wanneer dit expliciet is opgegeven.
Name
alpha_thumbnail
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak daarnaast een versie van de preview met transparante achtergrond (RGBA) en retourneert deze als alpha_thumbnail_url in de GET-respons. Het bestaande veld thumbnail_url blijft ongewijzigd.
Retourneert
De eigenschap result van de respons bevat de taak-id van de nieuw gemaakte Hertextureren-taak.
Foutmodi
Name
400 - Bad Request
Description
De aanvraag was onacceptabel. Veelvoorkomende oorzaken:
Ontbrekende parameter: Ofwel model_url ofwel input_task_id moet worden opgegeven.
Ontbrekende stijl: Ofwel text_style_prompt ofwel image_style_url moet worden opgegeven.
Ongeldige invoertaak: De input_task_id moet verwijzen naar een geslaagde taak van een ondersteund model.
Ongeldig modelformaat: De model_url verwijst naar een bestand met een niet-ondersteunde extensie.
Onbereikbare URL: De model_url of image_style_url kon niet worden gedownload.
Name
401 - Unauthorized
Description
De 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 promptcurl https://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 PBRcurl https://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 }'
Met deze endpoint kun je een Hertextureren-taak ophalen met een geldige taak-id.
Raadpleeg Het Hertextureren-taakobject om te zien welke
eigenschappen zijn opgenomen in het Hertextureren-taakobject.
Parameters
Name
id
Type
path
Description
Unieke identifier voor de Hertextureren-taak die moet worden opgehaald.
{"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-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 identifier voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als
implementatiedetail, moet je geen aannames doen over de indeling 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 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, geretourneerd naast OBJ-exports 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 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
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 met transparante achtergrond (RGBA) van thumbnail_url. 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
Progress 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 vertegenwoordigt het aantal milliseconden 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 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, 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 met textuur-URL-objecten die vanuit de taak worden gegenereerd. Normaal bevat deze slechts één textuur-URL-object. Elke textuur-URL heeft de volgende eigenschappen:
Name
base_color
Type
string
Description
Downloadbare URL naar de base color map-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_model is meshy-5, wordt deze eigenschap 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 credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Retourneert 0 voor FAILED-taken (credits worden bij mislukking terugbetaald).
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}