Retexture API to funkcja, która pozwala na integrację możliwości reteksturyzacji AI od Meshy z własną aplikacją. W tej sekcji znajdziesz wszystkie informacje potrzebne do rozpoczęcia pracy z tym API.
Ten punkt końcowy pozwala na utworzenie nowego zadania Retexture. Zajrzyj do
The Retexture Task Object, aby zobaczyć, które
właściwości są zawarte w obiekcie zadania Retexture.
Parameters
Wymagane jest tylko jedno z input_task_id lub model_url. Jeśli oba są dostarczone, input_task_id ma priorytet.
Name
input_task_id
Type
string
Wymagane
Description
ID ukończonego zadania Obraz na 3D lub Tekst na 3D, które chcesz zreteksturyzować.
To zadanie musi być jednym z następujących zadań: Tekst na 3D Podgląd, Tekst na 3D Doprecyzowanie, Obraz na 3D lub Remesh. Dodatkowo musi mieć status SUCCEEDED.
Name
model_url
Type
string
Wymagane
Description
Podaj model 3D, aby Meshy mógł zastosować teksturę. Obsługiwane formaty: .glb, .gltf, .obj, .fbx, .stl.
Są dwa sposoby na dostarczenie modelu:
Publicznie dostępny URL: URL dostępny z publicznego internetu.
Data URI: dane URI zakodowane w base64. Użyj typu MIME application/octet-stream. Przykład: data:application/octet-stream;base64,<twoje dane modelu zakodowane w base64>.
Dokładnie jedno źródło stylu jest wymagane: text_style_prompt, image_style_url lub multiview_image_urls. multiview_image_urls nie można łączyć z żadnym z pozostałych dwóch; jeśli zarówno text_style_prompt, jak i image_style_url są dostarczone, image_style_url ma priorytet.
Name
text_style_prompt
Type
string
Wymagane
Description
Opisz za pomocą tekstu pożądany styl tekstury obiektu. Maksymalnie 600 znaków.
Name
image_style_url
Type
string
Wymagane
Description
Podaj dwuwymiarowy obraz, który poprowadzi proces nakładania tekstury. Aktualnie obsługiwane formaty: .jpg, .jpeg oraz .png.
Są dwa sposoby na dostarczenie obrazu:
Publicznie dostępny URL: URL dostępny z publicznego internetu
Data URI: dane URI zakodowane w base64. Przykład danych URI: data:image/jpeg;base64,<twoje dane obrazu zakodowane w base64>
Nakładanie tekstury na obraz może nie działać optymalnie, jeśli występują znaczące różnice w geometrii między oryginalnym asetem a przesłanym obrazem.
Name
multiview_image_urls
Type
string[]
Wymagane
Description
Dostarcz od 1 do 4 obrazów pokazujących ten sam obiekt z różnych widoków w celu poprowadzenia procesu nakładania tekstury. Pierwszy widok jest głównym (przód); kolejność pozostałych widoków (lewy, tył, prawy) nie ma znaczenia.
Każdy element akceptuje te same formaty co image_style_url (publicznie dostępny URL lub dane URI base64, .jpg/.jpeg/.png).
Wymaga ai_model: "meshy-7" (lub latest).
Name
ai_model
Type
string
domyślne latest
Description
ID modelu AI do użycia w procesie reteksturyzacji. Dostępne wartości: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
domyślne false
Description
Zachowaj istniejący układ UV modelu zamiast generować nowy.
Jeśli reteksturyzujesz model wygenerowany przez Meshy (przez input_task_id, lub model_url, który wskazuje na wynik Meshy), ustaw to na true, aby ponownie użyć jego zoptymalizowanego układu UV.
Jeśli reteksturyzujesz model zewnętrzny, który przesłałeś, ustaw true, gdy ma on już dobry układ UV, który chcesz zachować, lub pozostaw false, aby Meshy rozpłaszczył nowy układ UV (najlepiej dla modeli bez odpowiedniego mapowania UV).
Name
enable_pbr
Type
boolean
domyślne false
Description
Generuj mapy PBR (metaliczne, chropowatości, normalne) oprócz koloru bazowego. Mapa emisji jest również dołączana, gdy ai_model to meshy-6, z wyjątkiem texture_resolution: 8k. meshy-7 oraz latest nie generują mapy emisji.
Name
texture_resolution
Type
string
domyślne 2k
Description
Rozdzielczość tekstury koloru bazowego. Jedna z 2k (2048×2048), 4k (4096×4096), lub 8k (8192×8192). Wyższe rozdzielczości uchwycają więcej szczegółów powierzchni.
4k oraz 8k wymagają ai_modelmeshy-6, meshy-7 lub latest. Przy 8k mapa emisji nie jest tworzona.
Name
hd_texture
Type
boolean
⚠ przestarzałe
domyślne false
Description
Użyj texture_resolution zamiast tego — równoważne z texture_resolution: "4k". Kiedy oba są ustawione, texture_resolution ma priorytet.
Name
remove_lighting
Type
boolean
domyślne true
Description
Usuwa podświetlenia i cienie z tekstury koloru bazowego, co daje czystszy efekt, który lepiej działa w niestandardowych ustawieniach oświetlenia.
Obsługiwane tylko, gdy ai_model to meshy-6.
Name
target_formats
Type
string[]
Description
Określa, które formaty plików 3D mają być uwzględnione w wyjściu. Tylko żądane formaty zostaną wygenerowane i zwrócone, co może skrócić czas wykonania zadania. Kiedy jest pomijane, wszystkie obsługiwane formaty są uwzględniane.
Dostępne wartości: glb, obj, fbx, stl, usdz, 3mf
Gdy pominięte, generowane są wszystkie formaty oprócz 3mf. 3mf jest uwzględniane tylko wtedy, gdy jest wyraźnie wskazane.
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
Kiedy ustawione na true, zadanie dodatkowo renderuje wersję podglądu z przezroczystym tłem (RGBA) i zwraca ją jako alpha_thumbnail_url w odpowiedzi GET. Istniejące pole thumbnail_url pozostaje niezmienione.
Returns
Właściwość result odpowiedzi zawiera id nowo utworzonego zadania Retexture.
Failure Modes
Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
Brakujący parametr: Musi być dostarczone model_url lub input_task_id.
Brakujący styl: Musi być dostarczone jedno z text_style_prompt, image_style_url lub multiview_image_urls.
Konfliktujące źródła stylu: multiview_image_urls nie można łączyć z text_style_prompt lub image_style_url.
Nieobsługiwany model dla wielu widoków: multiview_image_urls wymaga ai_model: "meshy-7" (lub latest).
Model nie jest dostępny: ai_model: "meshy-7" jest sukcesywnie wprowadzany i nie jest jeszcze dostępny dla twojego konta.
Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zakończonego sukcesem zadania z obsługiwanego modelu.
Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem.
Nieosiągalny URL: Element model_url, image_style_url lub multiview_image_urls nie mógł zostać pobrany.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.
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 }'
Ten punkt końcowy pozwala na pobranie zadania Retexture, pod warunkiem posiadania ważnego id zadania.
Zajrzyj do The Retexture Task Object, aby zobaczyć, które
właściwości są zawarte w obiekcie zadania Retexture.
Parameters
Name
id
Type
path
Description
Unikalny identyfikator dla zadania Retexture do pobrania.
Returns
Odpowiedź zawiera obiekt zadania Retexture. Sprawdź
The Retexture Task Object, aby uzyskać szczegóły.
{"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 }]
The Retexture Task object to jednostka robocza, której Meshy używa do generowania tekstury 3D z wejść tekstowych lub obrazkowych.
Model ma następujące właściwości:
Properties
Name
id
Type
string
Description
Unikalny identyfikator dla zadania. Chociaż używamy k-sortowalnego UUID dla identyfikatorów zadań jako szczegółu implementacyjnego, nie powinieneś dokonywać żadnych założeń dotyczących formatu identyfikatora.
Name
type
Type
string
Description
Typ zadania retexture. Wartość to retexture.
Name
model_urls
Type
object
Description
Pobieralny URL do wygenerowanego przez Meshy pliku modelu 3D z teksturą.
Name
glb
Type
string
Description
Pobieralny URL do pliku GLB.
Name
fbx
Type
string
Description
Pobieralny URL do pliku FBX.
Name
obj
Type
string
Description
Pobieralny URL do pliku OBJ.
Name
usdz
Type
string
Description
Pobieralny URL do pliku USDZ.
Name
mtl
Type
string
Description
Pobieralny URL do pliku MTL, zwracany wraz z eksportami OBJ, gdy dostępne są tekstury.
Name
stl
Type
string
Description
Pobieralny URL do pliku STL.
Name
3mf
Type
string
Description
Pobieralny URL do pliku 3MF. Obecny tylko wtedy, gdy 3mf było żądane przez target_formats.
Name
text_style_prompt
Type
string
Description
To tekstowy prompt użyty do utworzenia zadania teksturyzacji.
Name
image_style_url
Type
string
Description
To wejście obrazkowe użyte do utworzenia zadania teksturyzacji.
Name
multiview_image_urls
Type
string[]
Description
Pobieralne URL do referencyjnych obrazów z wielu widoków używane do utworzenia zadania teksturyzacji. Obecne tylko, gdy zadanie zostało utworzone z multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Pobieralny URL do miniatury obrazu pliku modelu.
Name
alpha_thumbnail_url
Type
string
Description
Pobieralny URL do wersji thumbnail_url z przezroczystym tłem (RGBA). Obecne tylko, gdy zadanie zostało utworzone z alpha_thumbnail: true i przezroczysty podgląd został pomyślnie wyrenderowany; inaczej to pole jest pomijane.
Name
progress
Type
integer
Description
Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Po zakończeniu zadania ta wartość zmieni się na 100.
Name
started_at
Type
timestamp
Description
Znacznik czasu, kiedy zadanie zostało rozpoczęte, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie z
standardem RFC 3339.
Na przykład piątek, 1 września 2023 12:00:00 GMT to 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
created_at
Type
timestamp
Description
Znacznik czasu, kiedy zadanie zostało utworzone, w milisekundach.
Name
expires_at
Type
timestamp
Description
Znacznik czasu, kiedy wynik zadania wygasa, w milisekundach.
Name
finished_at
Type
timestamp
Description
Znacznik czasu, kiedy zadanie zostało zakończone, w milisekundach. Jeśli zadanie jeszcze się nie zakończyło, ta właściwość będzie miała wartość 0.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Tablica obiektów URL tekstur wygenerowanych z zadania. Zwykle zawiera tylko jeden obiekt URL tekstury. Każdy URL tekstury ma następujące właściwości:
Name
base_color
Type
string
Description
Pobieralny URL do obrazu mapy koloru bazowego.
Name
metallic
Type
string
Description
Pobieralny URL do obrazu mapy metalicznej.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość będzie pominięta.
Name
normal
Type
string
Description
Pobieralny URL do obrazu mapy normalnych.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość będzie pominięta.
Name
roughness
Type
string
Description
Pobieralny URL do obrazu mapy chropowatości.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość będzie pominięta.
Name
emission
Type
string
Description
Pobieralny URL do obrazu mapy emisji.
Jeśli zadanie zostało utworzone z enable_pbr: false, lub ai_model to meshy-5, ta właściwość będzie pominięta.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań.
To właściwość jest obecna tylko, gdy status zadania to PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu dla niepowodzeń zadań. Zobacz Błędy, aby uzyskać pełne odniesienie do obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecne, gdy status zadania to PENDING, IN_PROGRESS, lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są refundowane w przypadku niepowodzenia).
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}