Przekształć zdjęcie źródłowe w kolekcjonerską minifigurkę 3D w stylu klocków w dwóch etapach:
prototyp generuje stylizowany obraz koncepcyjny z Twojego zdjęcia wejściowego, a następnie
budowa przekształca ten obraz koncepcyjny w teksturowany model 3D. Oba etapy
są połączone za pomocą input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Wygeneruj pojedynczy obraz koncepcyjny w stylu klocków z oryginalnego zdjęcia. Zwrócone ID zadania to to, które przekażesz jako input_task_id do punktu końcowego build. Odnieś się do
Obiekt zadania prototypu figurki z klocków
dla kształtu odpowiedzi.
Parametry
Name
image_url
Type
string
Wymagane
Description
Źródłowe zdjęcie, które Meshy ma stylizować jako minifigurkę z klocków. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.
Istnieją dwa sposoby dostarczenia obrazu:
Publicznie dostępny URL: URL, który jest 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>.
Name
name
Type
string
Description
Opcjonalna nazwa zadania do celów wyświetlania. Maksymalnie 100 znaków.
Name
remove_background
Type
boolean
domyślne false
Description
Gdy ustawione na true, obraz prototypu jest zwracany jako przezroczysty RGBA PNG z usuniętym tłem, dzięki czemu można umieścić temat na dowolnym tle.
Zwraca
Właściwość result odpowiedzi zawiera id nowo utworzonego zadania prototypu figurki z klocków. Sprawdź punkt końcowy Pobierz zadanie lub zasubskrybuj strumień aż zadanie osiągnie SUCCEEDED, a następnie przekaż to ID do punktu końcowego build jako input_task_id.
Tryby niepowodzenia
Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
Brakujący parametr: image_url jest wymagany.
Nieprawidłowy format obrazu: Podany image_url nie jest obsługiwanym formatem (.jpg, .jpeg, .png, .webp).
Wymiary obrazu poza zakresem: Obraz jest zbyt mały, przekracza maksymalny rozmiar pliku lub przekracza maksymalną liczbę pikseli.
Nieosiągalny URL: image_url nie mógł zostać pobrany (404 lub timeout).
Nieprawidłowy Data URI: Ciąg base64 jest niepoprawnie sformułowany.
Oznaczona zawartość: Obraz wejściowy został oznaczony przez moderation NSFW.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Proszę sprawdzić swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
403 - Forbidden
Description
Obraz wejściowy został oznaczony za naruszenie własności intelektualnej.
Name
429 - Too Many Requests
Description
Przekroczyłeś swój limit szybkości.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Stage 1: generate a brick-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Wygeneruj finalną teksturowaną 3D figurkę z klocków z udanego zadania prototypowego. Budowa uruchamia ten sam proces obraz-na-3D co Obraz na 3D, więc format obiektu odpowiedzi i lista wyjściowych URL-i są dokładnie takie same. Odwołaj się do Obiekt zadania budowy figurki z klocków dla kształtu odpowiedzi.
Parametry
Name
input_task_id
Type
string
Wymagane
Description
ID zadania prototypowego utworzonego za pośrednictwem tego samego punktu końcowego OpenAPI. Prototyp musi być utworzony z tym samym kluczem API, musi osiągnąć SUCCEEDED i musi wygenerować dokładnie jeden obraz kandydata.
Zadania prototypowe utworzone za pośrednictwem aplikacji webowej nie są akceptowane — punkt końcowy budowy akceptuje tylko zadania prototypowe utworzone przez POST /openapi/creative-lab/brick-figure/v1/prototype i odrzuca każde inne źródło z 404.
Name
name
Type
string
Description
Opcjonalna nazwa zadania do celów wyświetlania. Maksymalnie 100 znaków.
Zwraca
Właściwość result odpowiedzi zawiera id nowo utworzonego zadania budowy figurki z klocków. Sprawdź punkt końcowy Pobierz zadanie lub subskrybuj strumień aż zadanie osiągnie SUCCEEDED, a następnie pobierz teksturowany GLB z model_urls.glb (lub parę OBJ + MTL z model_urls.obj i model_urls.mtl, jeśli twój dalszy proces preferuje OBJ).
Tryby awarii
Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
Brakujący parametr: input_task_id jest wymagany.
Nieprawidłowy UUID: input_task_id nie jest prawidłowym UUID.
Rodzic nie zakończony sukcesem: Odwołane zadanie prototypowe nie osiągnęło jeszcze SUCCEEDED.
Brak kandydata: Zadanie prototypowe zakończyło się sukcesem, ale nie wygenerowało obrazu kandydata.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Proszę sprawdzić swój klucz API.
Name
402 - Payment Required
Description
Niewystarczające kredyty do wykonania tego zadania.
Name
404 - Not Found
Description
Odwołane zadanie prototypowe nie istnieje, należy do innego użytkownika lub zostało utworzone za pośrednictwem aplikacji webowej (tylko zadania prototypowe w trybie API łączą się w budowę).
Name
429 - Too Many Requests
Description
Przekroczyłeś swój limit szybkości.
Request
POST
/openapi/creative-lab/brick-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Pobierz zadanie prototypu lub budowy, podając prawidłowy id zadania. Ścieżka URL
musi odpowiadać etapowi zadania — zadanie budowy pobrane przez
/prototype/:id zwraca 404, i odwrotnie.
Anuluj zadanie figurki z klocków. Jeśli zadanie jest nadal PENDING, kredyty
zużyte w momencie tworzenia są zwracane. Zadania, które są już
IN_PROGRESS, są anulowane bez zwrotu (pracownik może już zużywać zasoby). Zadania, które osiągnęły już stan końcowy
(SUCCEEDED, FAILED, CANCELED) nie mogą być anulowane.
Ścieżka URL musi odpowiadać etapowi zadania — DELETE na
/prototype/:buildId zwraca 404.
Parametry ścieżki
Name
id
Type
path
Description
Unikalny identyfikator zadania figurki z klocków do anulowania.
Zwracane wartości
Zwraca 204 No Content w przypadku sukcesu z pustym ciałem.
Tryby błędów
Name
400 - Bad Request
Description
Zadanie jest już w stanie końcowym i nie może być anulowane.
Name
404 - Not Found
Description
Zadanie nie istnieje, należy do innego użytkownika lub jego etap nie odpowiada ścieżce URL.
Strumieniuj aktualizacje w czasie rzeczywistym dla zadania figurki z klocków za pomocą Server-Sent Events (SSE).
Ścieżka URL musi odpowiadać etapowi zadania — otwarcie strumienia na
/prototype/:buildId/stream emituje pojedynczy ładunek event: error z
status_code: 404 i zamyka strumień.
Parametry
Name
id
Type
path
Description
Unikalny identyfikator zadania figurki z klocków do strumieniowania.
Zwraca
Zwraca strumień obiektów zadań Prototyp Figurka z Klocków
lub Budowa Figurka z Klocków jako
Server-Sent Events. Dla zadań PENDING lub IN_PROGRESS, strumień odpowiedzi
będzie zawierał tylko niezbędne pola progress i status.
Pobierz stronicowaną listę swoich zadań dotyczących figurek z klocków dla jednego etapu. Ścieżka URL
wybiera etap — /prototype zwraca zadania prototypowe; /build
zwraca zadania budowlane. Zadania z innego etapu nie są uwzględniane w żadnej
odpowiedzi.
Parametry ścieżki
Name
stage
Type
path
Wymagane
Description
Albo prototype, albo build. Kolekcja zwraca tylko zadania,
których etap pasuje do URL — pobieranie /prototype nigdy nie zwraca
zadań budowlanych i odwrotnie.
Parametry zapytania
Name
page_num
Type
integer
domyślne 1
Description
Numer strony dla stronicowania.
Name
page_size
Type
integer
domyślne 10
Description
Limit rozmiaru strony. Maksymalnie dozwolone to 100 elementów.
Name
sort_by
Type
string
domyślne -created_at
Description
Pole do sortowania. Dostępne wartości:
+created_at: Sortuj według czasu utworzenia w porządku rosnącym.
-created_at: Sortuj według czasu utworzenia w porządku malejącym.
Obiekt Zadania Prototypu Figurka z Klocków to jednostka pracy, którą Meshy śledzi, aby wygenerować obraz koncepcyjny w stylu klocków z zdjęcia źródłowego. Wynik tego etapu jest połączony z etapem budowy za pomocą input_task_id.
Właściwości
Name
id
Type
string
Description
Unikalny identyfikator zadania. Chociaż używamy UUID sortowalnego według klucza do identyfikatorów zadań jako szczegółu implementacji, nie powinieneś zakładać żadnego formatu identyfikatora.
Name
type
Type
string
Description
Typ zadania. Wartość to creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
Nazwa zadania podana podczas jego tworzenia. Pusty ciąg znaków, jeśli nie podano nazwy.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
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. Gdy zadanie zakończy się sukcesem, wartość ta wyniesie 100.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład, piątek, 1 września 2023, 12:00:00 GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość null.
Name
finished_at
Type
timestamp
Description
Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie jeszcze się nie zakończyło, ta właściwość będzie miała wartość null.
Name
expires_at
Type
timestamp
Description
Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań.
Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji 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ą zwracane w przypadku niepowodzenia).
Name
image_urls
Type
array of strings
Description
Pobieralne URL-e dla kandydatów na obrazy koncepcyjne wygenerowane przez to zadanie prototypowe. Obecnie API zawsze zwraca dokładnie jednego kandydata; pole jest tablicą, aby przyszłe wersje mogły ujawnić wielu kandydatów bez wprowadzania zmian łamiących kompatybilność.
Przykład Obiektu Zadania Prototypu Figurka z Klocków
Obiekt zadania budowy figurki z klocków to jednostka pracy, którą Meshy śledzi, aby wygenerować teksturowaną 3D figurkę z klocków z zakończonego sukcesem zadania prototypowego. Używa tego samego potoku obraz-na-3D, co Obraz na 3D, więc pola wyjściowe odzwierciedlają obiekt zadania tego punktu końcowego task object.
Właściwości
Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Typ zadania. Wartość to creative-lab-brick-figure-build.
Name
name
Type
string
Description
Nazwa zadania podana podczas jego tworzenia. Pusty ciąg znaków, jeśli nie podano nazwy.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
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. Gdy zadanie zakończy się sukcesem, wartość ta wyniesie 100.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia zadania, w milisekundach.
Name
finished_at
Type
timestamp
Description
Znacznik czasu zakończenia zadania, w milisekundach.
Name
expires_at
Type
timestamp
Description
Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań. Znaczące tylko, gdy status to PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).
Name
prompt
Type
string
Description
Zawsze puste dla budowy figurki z klocków. Obecne dla kompatybilności między punktami końcowymi z wspólnym kształtem V2ImageTo3DTaskResponse używanym przez Obraz na 3D.
Name
negative_prompt
Type
string
Description
Zawsze puste dla budowy figurki z klocków. Obecne dla kompatybilności między punktami końcowymi.
Name
texture_prompt
Type
string
Description
Zawsze puste dla budowy figurki z klocków. Obecne dla kompatybilności między punktami końcowymi.
Name
texture_image_url
Type
string
Description
Zawsze puste dla budowy figurki z klocków. Obecne dla kompatybilności między punktami końcowymi.
Name
model_urls
Type
object
Description
Pobieralne URL-e dla wygenerowanego modelu 3D. Budowa figurki z klocków emituje teksturowany GLB oraz parę OBJ + MTL dla potoków preferujących Wavefront OBJ. Kształt pola odpowiada obiektowi Image to 3D model_urls, więc przyszłe dodatki formatu można wprowadzać bez zmiany wstecznej.
Name
glb
Type
string
Description
Pobieralny URL do teksturowanego pliku GLB.
Name
obj
Type
string
Description
Pobieralny URL do pliku Wavefront OBJ (geometria + UV).
Name
mtl
Type
string
Description
Pobieralny URL do towarzyszącego pliku materiału MTL dla OBJ. Sparuj z obj i wpisem z texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Pobieralny URL do miniatury obrazu pliku modelu.
Name
texture_urls
Type
array
Description
Tablica obiektów URL tekstur wygenerowanych przez to zadanie. Obecnie zawiera pojedynczy obiekt z mapą koloru bazowego.