API Reteksturowania to funkcja, która pozwala zintegrować możliwości Reteksturowania AI Meshy z Twoją własną aplikacją. W tej sekcji znajdziesz wszystkie informacje
potrzebne, aby rozpocząć korzystanie z tego API.
Ten punkt końcowy umożliwia utworzenie nowego zadania Reteksturowania. Zobacz
Obiekt zadania Reteksturowania, aby sprawdzić, które
właściwości są zawarte w obiekcie zadania Reteksturowania.
Parametry
Wymagane jest tylko jedno z input_task_id lub model_url. Jeśli podano oba, 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 reteksturować.
To zadanie musi być jednym z następujących zadań: Text to 3D Preview, Text to 3D Refine, Obraz na 3D lub Remesh. Ponadto musi mieć status SUCCEEDED.
Name
model_url
Type
string
Wymagane
Description
Podaj model 3D dla Meshy do teksturowania. Obsługiwane formaty: .glb, .gltf, .obj, .fbx, .stl.
Istnieją dwa sposoby podania modelu:
Publicznie dostępny URL: URL dostępny z publicznego internetu.
Data URI: Zakodowany w base64 Data URI modelu. Użyj MIME type application/octet-stream. Przykład: data:application/octet-stream;base64,<your base64-encoded model data>.
Wymagane jest tylko jedno z text_style_prompt lub image_style_url. Jeśli podano oba, image_style_url ma priorytet.
Name
text_style_prompt
Type
string
Wymagane
Description
Opisz pożądany styl tekstury obiektu za pomocą tekstu. Maksymalnie 600 znaków.
Name
image_style_url
Type
string
Wymagane
Description
Podaj obraz 2D, aby pokierować procesem teksturowania. Obecnie obsługujemy formaty .jpg, .jpeg i .png.
Istnieją dwa sposoby podania obrazu:
Publicznie dostępny URL: URL dostępny z publicznego internetu
Data URI: Zakodowany w base64 Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Teksturowanie obrazu może nie działać optymalnie, jeśli między oryginalnym assetem a przesłanym obrazem występują znaczne różnice geometrii.
Name
ai_model
Type
string
domyślne latest
Description
ID modelu AI do użycia przy reteksturowaniu. Dostępne wartości: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
domyślne false
Description
Zachowuje istniejący układ UV modelu zamiast generowania nowego.
Jeśli reteksturowany model został wygenerowany przez Meshy (przez input_task_id lub model_url wskazujący na wynik Meshy), ustaw tę wartość na true, aby ponownie użyć jego zoptymalizowanego układu UV.
Jeśli reteksturujesz przesłany model innej firmy, ustaw true, gdy ma już dobre UV, które chcesz zachować, albo pozostaw false, aby pozwolić Meshy rozwinąć świeże UV (najlepsze dla modeli bez poprawnego mapowania UV).
Name
enable_pbr
Type
boolean
domyślne false
Description
Generuje mapy PBR (metallic, roughness, normal) oprócz koloru bazowego. Mapa emisji jest również dołączana, gdy ai_model to meshy-6 lub latest.
Name
hd_texture
Type
boolean
domyślne false
Description
Generuje teksturę koloru bazowego w rozdzielczości 4K (4096×4096), aby uzyskać więcej szczegółów.
Obsługiwane tylko wtedy, gdy ai_model to meshy-6 lub latest. Mapy PBR są zawsze generowane w 2K.
Name
remove_lighting
Type
boolean
domyślne true
Description
Usuwa światła i cienie z tekstury koloru bazowego, tworząc czystszy wynik, który działa lepiej w niestandardowych konfiguracjach oświetlenia.
Obsługiwane tylko wtedy, gdy ai_model to meshy-6 lub latest.
Name
target_formats
Type
string[]
Description
Określa, które formaty plików 3D mają zostać uwzględnione w wyniku. Wygenerowane i zwrócone zostaną tylko żądane formaty, co może skrócić czas ukończenia zadania. W przypadku pominięcia uwzględniane są wszystkie obsługiwane formaty.
Dostępne wartości: glb, obj, fbx, stl, usdz, 3mf
W przypadku pominięcia generowane są wszystkie formaty z wyjątkiem 3mf. 3mf jest uwzględniany tylko wtedy, gdy zostanie jawnie określony.
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
Po ustawieniu 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 bez zmian.
Zwraca
Właściwość result odpowiedzi zawiera id zadania nowo utworzonego zadania Reteksturowania.
Tryby niepowodzenia
Name
400 - Bad Request
Description
Żądanie było niedopuszczalne. Typowe przyczyny:
Brakujący parametr: Należy podać model_url albo input_task_id.
Brakujący styl: Należy podać text_style_prompt albo image_style_url.
Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do pomyślnego zadania z obsługiwanego modelu.
Nieprawidłowy format modelu: model_url wskazuje plik z nieobsługiwanym rozszerzeniem.
Nieosiągalny URL: Nie można pobrać model_url lub image_style_url.
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 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 }'
Ten punkt końcowy pozwala pobrać zadanie Reteksturowanie na podstawie prawidłowego id.
Zapoznaj się z sekcją Obiekt zadania Reteksturowanie, aby zobaczyć, które
właściwości są zawarte w obiekcie zadania Reteksturowanie.
Parametry
Name
id
Type
path
Description
Unikalny identyfikator zadania Reteksturowanie do pobrania.
{"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 }]
Obiekt zadania Reteksturowanie to jednostka pracy, której Meshy używa do generowania tekstury 3D na podstawie danych wejściowych w postaci tekstu lub obrazu.
Model ma następujące właściwości:
Properties
Name
id
Type
string
Description
Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy k-sortowalnego UUID dla identyfikatorów zadań,
nie należy przyjmować żadnych założeń dotyczących formatu identyfikatora.
Name
type
Type
string
Description
Typ zadania Reteksturowanie. Wartość to retexture.
Name
model_urls
Type
object
Description
Adres URL do pobrania teksturowanego pliku modelu 3D wygenerowanego przez Meshy.
Name
glb
Type
string
Description
Adres URL do pobrania pliku GLB.
Name
fbx
Type
string
Description
Adres URL do pobrania pliku FBX.
Name
obj
Type
string
Description
Adres URL do pobrania pliku OBJ.
Name
usdz
Type
string
Description
Adres URL do pobrania pliku USDZ.
Name
mtl
Type
string
Description
Adres URL do pobrania pliku MTL, zwracany wraz z eksportami OBJ, gdy obecne są tekstury.
Name
stl
Type
string
Description
Adres URL do pobrania pliku STL.
Name
3mf
Type
string
Description
Adres URL do pobrania pliku 3MF. Obecny tylko wtedy, gdy zażądano 3mf przez target_formats.
Name
text_style_prompt
Type
string
Description
To jest prompt tekstowy, który został użyty do utworzenia zadania teksturowania.
Name
image_style_url
Type
string
Description
To jest wejściowy obraz, który został użyty do utworzenia zadania teksturowania.
Name
thumbnail_url
Type
string
Description
Adres URL do pobrania obrazu miniatury pliku modelu.
Name
alpha_thumbnail_url
Type
string
Description
Adres URL do pobrania wersji thumbnail_url z przezroczystym tłem (RGBA). Obecny tylko wtedy, gdy zadanie zostało utworzone z alpha_thumbnail: true i przezroczysty podgląd został pomyślnie wyrenderowany; w przeciwnym razie to pole jest pomijane.
Name
progress
Type
integer
Description
Postęp zadania. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie mieć wartość 0. Gdy zadanie zakończy się powodzeniem, wartość zmieni się na 100.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie mieć wartość 0.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 r. UTC, zgodnie
ze standardem RFC 3339.
Na przykład piątek, 1 września 2023 r., 12:00:00 GMT jest reprezentowany jako 1693569600000. Dotyczy to
wszystkich znaczników czasu w Meshy API.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Name
expires_at
Type
timestamp
Description
Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.
Name
finished_at
Type
timestamp
Description
Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze zakończone, ta właściwość będzie mieć wartość 0.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Tablica obiektów URL tekstur, które są generowane 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
Adres URL do pobrania obrazu mapy koloru bazowego.
Name
metallic
Type
string
Description
Adres URL do pobrania obrazu mapy metaliczności.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość zostanie pominięta.
Name
normal
Type
string
Description
Adres URL do pobrania obrazu mapy normalnych.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość zostanie pominięta.
Name
roughness
Type
string
Description
Adres URL do pobrania obrazu mapy chropowatości.
Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość zostanie pominięta.
Name
emission
Type
string
Description
Adres URL do pobrania obrazu mapy emisji.
Jeśli zadanie zostało utworzone z enable_pbr: false lub ai_model to meshy-5, ta właściwość zostanie pominięta.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań.
Ta właściwość występuje tylko wtedy, gdy status zadania to PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu dla zadań zakończonych niepowodzeniem. Zobacz Błędy, aby uzyskać pełną referencję obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane 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}