Die Retexture-API ist eine Funktion, mit der du die KI-gestützten Retexturierungsfunktionen von Meshy in deine eigene Anwendung integrieren kannst. In diesem Abschnitt findest du alle Informationen,
die du benötigst, um mit dieser API loszulegen.
Dieser endpoint ermöglicht es Ihnen, eine neue Retexture-Aufgabe zu erstellen. Siehe
Das Retexture-Aufgabenobjekt, um zu sehen, welche
Eigenschaften im Retexture-Aufgabenobjekt enthalten sind.
Parameter
Nur eines von input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Vorrang.
Name
input_task_id
Type
string
Erforderlich
Description
Die ID der abgeschlossenen Image to 3D- oder Text to 3D-Aufgabe, die Sie neu texturieren möchten.
Diese Aufgabe muss eine der folgenden Aufgaben sein: Text to 3D Preview, Text to 3D Refine, Image to 3D oder Remesh. Außerdem muss sie den Status SUCCEEDED haben.
Name
model_url
Type
string
Erforderlich
Description
Stellen Sie Meshy ein 3D-Modell zum Texturieren bereit. Unterstützte Formate: .glb, .gltf, .obj, .fbx, .stl.
Es gibt zwei Möglichkeiten, das Modell bereitzustellen:
Öffentlich zugängliche URL: Eine URL, die über das öffentliche Internet erreichbar ist.
Data URI: Eine base64-codierte Data URI des Modells. Verwenden Sie den MIME-Typ application/octet-stream. Beispiel: data:application/octet-stream;base64,<your base64-encoded model data>.
Nur eines von text_style_prompt oder image_style_url ist erforderlich. Wenn beide angegeben werden, hat image_style_url Vorrang.
Name
text_style_prompt
Type
string
Erforderlich
Description
Beschreiben Sie den gewünschten Texturstil des Objekts mit Text. Maximal 600 Zeichen.
Name
image_style_url
Type
string
Erforderlich
Description
Stellen Sie ein 2D-Bild bereit, um den Texturierungsprozess zu steuern. Wir unterstützen derzeit die Formate .jpg, .jpeg und .png.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
Öffentlich zugängliche URL: Eine URL, die über das öffentliche Internet erreichbar ist
Data URI: Eine base64-codierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Die Bildtexturierung funktioniert möglicherweise nicht optimal, wenn es erhebliche Geometrieunterschiede zwischen dem ursprünglichen Asset und dem hochgeladenen Bild gibt.
Name
ai_model
Type
string
Standard latest
Description
ID des KI-Modells, das für die Neu-Texturierung verwendet werden soll. Verfügbare Werte: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
Standard false
Description
Behalten Sie das vorhandene UV-Layout des Modells bei, anstatt ein neues zu generieren.
Wenn Sie ein von Meshy generiertes Modell neu texturieren (über input_task_id oder eine model_url, die auf eine Meshy-Ausgabe verweist), setzen Sie dies auf true, um dessen optimiertes UV-Layout wiederzuverwenden.
Wenn Sie ein hochgeladenes Drittanbieter-Modell neu texturieren, setzen Sie true, wenn es bereits gute UVs hat, die Sie beibehalten möchten, oder lassen Sie es auf false, damit Meshy neue UVs unwrappt (am besten für Modelle ohne korrektes UV-Mapping).
Name
enable_pbr
Type
boolean
Standard false
Description
Generiert zusätzlich zur Basisfarbe PBR-Maps (Metallic, Roughness, Normal). Eine Emission-Map ist ebenfalls enthalten, wenn ai_modelmeshy-6 oder latest ist.
Name
hd_texture
Type
boolean
Standard false
Description
Generiert die Base-Color-Textur mit 4K-Auflösung (4096×4096) für höhere Details.
Nur unterstützt, wenn ai_modelmeshy-6 oder latest ist. PBR-Maps werden immer in 2K generiert.
Name
remove_lighting
Type
boolean
Standard true
Description
Entfernt Glanzlichter und Schatten aus der Base-Color-Textur und erzeugt ein saubereres Ergebnis, das unter benutzerdefinierten Beleuchtungs-Setups besser funktioniert.
Nur unterstützt, wenn ai_modelmeshy-6 oder latest ist.
Name
target_formats
Type
string[]
Description
Gibt an, welche 3D-Dateiformate in die Ausgabe aufgenommen werden sollen. Nur die angeforderten Formate werden generiert und zurückgegeben, wodurch sich die Abschlusszeit der Aufgabe verkürzen kann. Wenn ausgelassen, werden alle unterstützten Formate eingeschlossen.
Verfügbare Werte: glb, obj, fbx, stl, usdz, 3mf
Wenn ausgelassen, werden alle Formate außer 3mf generiert. 3mf wird nur eingeschlossen, wenn es ausdrücklich angegeben wird.
Name
alpha_thumbnail
Type
boolean
Standard false
Description
Wenn auf true gesetzt, rendert die Aufgabe zusätzlich eine Version der Vorschau mit transparentem Hintergrund (RGBA) und gibt sie in der GET-Antwort als alpha_thumbnail_url zurück. Das vorhandene Feld thumbnail_url bleibt unverändert.
Rückgabe
Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Retexture-Aufgabe.
Fehlermodi
Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
Fehlender Stil: Entweder text_style_prompt oder image_style_url muss angegeben werden.
Ungültige Eingabeaufgabe: Die input_task_id muss auf eine erfolgreiche Aufgabe eines unterstützten Modells verweisen.
Ungültiges Modellformat: Die model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung.
Nicht erreichbare URL: Die model_url oder image_style_url konnte nicht heruntergeladen werden.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API key.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihr Rate-Limit überschritten.
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 }'
Dieser endpoint ermöglicht es Ihnen, eine Retexture-Aufgabe anhand einer gültigen Aufgaben-id abzurufen.
Siehe Das Retexture-Aufgabenobjekt, um zu erfahren, welche
Eigenschaften im Retexture-Aufgabenobjekt enthalten sind.
Parameter
Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Retexture-Aufgabe.
Rückgabe
Die Antwort enthält das Retexture-Aufgabenobjekt. Weitere Details finden Sie im Abschnitt
Das Retexture-Aufgabenobjekt.
{"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}
Dieser endpoint löscht eine Retexture-Aufgabe dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion kann nicht rückgängig gemacht werden.
[ {"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 }]
Das Retexture-Aufgabenobjekt ist eine Arbeitseinheit, die Meshy verwendet, um eine 3D-Textur aus Text- oder Bildeingaben zu generieren.
Das Modell hat die folgenden Eigenschaften:
Eigenschaften
Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Aufgaben-IDs verwenden,
solltest du keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ der Retexture-Aufgabe. Der Wert ist retexture.
Name
model_urls
Type
object
Description
Herunterladbare URL zur von Meshy generierten texturierten 3D-Modelldatei.
Name
glb
Type
string
Description
Herunterladbare URL zur GLB-Datei.
Name
fbx
Type
string
Description
Herunterladbare URL zur FBX-Datei.
Name
obj
Type
string
Description
Herunterladbare URL zur OBJ-Datei.
Name
usdz
Type
string
Description
Herunterladbare URL zur USDZ-Datei.
Name
mtl
Type
string
Description
Herunterladbare URL zur MTL-Datei, die bei OBJ-Exporten zurückgegeben wird, wenn Texturen vorhanden sind.
Name
stl
Type
string
Description
Herunterladbare URL zur STL-Datei.
Name
3mf
Type
string
Description
Herunterladbare URL zur 3MF-Datei. Nur vorhanden, wenn 3mf über target_formats angefordert wurde.
Name
text_style_prompt
Type
string
Description
Dies ist der Text-Prompt, der zum Erstellen der Texturierungsaufgabe verwendet wurde.
Name
image_style_url
Type
string
Description
Dies ist die Bildeingabe, die zum Erstellen der Texturierungsaufgabe verwendet wurde.
Name
thumbnail_url
Type
string
Description
Herunterladbare URL zum Vorschaubild der Modelldatei.
Name
alpha_thumbnail_url
Type
string
Description
Herunterladbare URL zu einer Version von thumbnail_url mit transparentem Hintergrund (RGBA). Nur vorhanden, wenn die Aufgabe mit alpha_thumbnail: true erstellt wurde und die transparente Vorschau erfolgreich gerendert wurde; andernfalls wird dieses Feld ausgelassen.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird sie zu 100.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0.
Ein Zeitstempel stellt die Anzahl der seit dem 1. Januar 1970 UTC vergangenen Millisekunden dar, gemäß
dem RFC 3339-Standard.
Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 PM GMT als 1693569600000 dargestellt. Dies gilt
für alle Zeitstempel in der Meshy API.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Aufgabenergebnis abläuft, in Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen ist, ist diese Eigenschaft 0.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Ein Array von Textur-URL-Objekten, die aus der Aufgabe generiert werden. Normalerweise enthält dies nur ein Textur-URL-Objekt. Jede Textur-URL hat die folgenden Eigenschaften:
Name
base_color
Type
string
Description
Herunterladbare URL zum Base-Color-Map-Bild.
Name
metallic
Type
string
Description
Herunterladbare URL zum Metallic-Map-Bild.
Wenn die Aufgabe mit enable_pbr: false erstellt wird, wird diese Eigenschaft ausgelassen.
Name
normal
Type
string
Description
Herunterladbare URL zum Normal-Map-Bild.
Wenn die Aufgabe mit enable_pbr: false erstellt wird, wird diese Eigenschaft ausgelassen.
Name
roughness
Type
string
Description
Herunterladbare URL zum Roughness-Map-Bild.
Wenn die Aufgabe mit enable_pbr: false erstellt wird, wird diese Eigenschaft ausgelassen.
Name
emission
Type
string
Description
Herunterladbare URL zum Emission-Map-Bild.
Wenn die Aufgabe mit enable_pbr: false erstellt wird oder ai_modelmeshy-5 ist, wird diese Eigenschaft ausgelassen.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Aufgaben.
Diese Eigenschaft ist nur vorhanden, wenn der Aufgabenstatus PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehlschlag erstattet).
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}