Tekst na 3D API

To pole powinno być ustawione na „preview” podczas tworzenia zadania preview.

Opisz, jakiego rodzaju obiektem jest model 3D. Maksymalnie 800 znaków.

Określ typ generowania siatki 3D.

Dostępne wartości:

• standard: Standardowe generowanie siatki 3D o wysokim poziomie szczegółowości.
• smart-topology: Wybierz model Smart Topology za pomocą ai_model (meshy-t2 lub meshy-t2.5).
• lowpoly (przestarzałe, zostanie wycofane 30 października 2026 r.): Generuje siatkę low-poly zoptymalizowaną pod kątem czystszych wielokątów. Zamiast tego zalecamy Meshy T2.5: smart-topology z meshy-t2.5.

ID modelu, którego należy użyć. Dostępne wartości zależą od model_type.

Generowanie standardowe (model_type: standard):

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (przestarzałe): zamiast tego użyj meshy-7.1.

Generowanie Smart Topology (model_type: smart-topology):

• meshy-t2: model Smart Topology — czystsza topology, natywnie rozdzielone części, wynik w trójkątach oraz liczba ścian, którą można ustawić za pomocą target_polycount.
• meshy-t2.5 (domyślny): Ostrzejsze detale dla zasobów do gier. Wynik w trójkątach oraz liczba ścian, którą można ustawić za pomocą target_polycount.

Przebieg generowania geometrii. 2k uruchamia przebieg Ultra w rozdzielczości 2048³; 4k uruchamia go w rozdzielczości 4096³ dla najdokładniejszych szczegółów powierzchni.

Dostępne wartości: standard, 2k, 4k

Użyj zamiast tego geometry_resolution. ultra_mode: true jest równoważne geometry_resolution: "2k".

Kontroluje, czy włączyć fazę remesh. W przypadku modelu o najwyższej jakości zalecamy ustawienie should_remesh na false.

Docelowa liczba wielokątów (ścian) w wyniku. Rzeczywista liczba może odbiegać od wartości docelowej w zależności od geometrii.

target_polycount ma zastosowanie w dwóch niezależnych przypadkach:

• Remesh — z should_remesh: true dla modelu standard. Siatka jest poddawana remesh (decymacji) do w przybliżeniu tej liczby. Zakres od 100 do 300 000, wartość domyślna 30 000. Jeśli ustawiono decimation_mode, ma on priorytet, a target_polycount jest ignorowany.
• Smart Topology — z model_type: smart-topology oraz ai_model meshy-t2 lub meshy-t2.5. Model jest generowany bezpośrednio z tą liczbą ścian; remesh nie jest wykonywany, a should_remesh nie jest wymagane. Dla meshy-t2: zakres od 100 do 15 000, wartość domyślna 4 000. Dla meshy-t2.5: zakres od 100 do 30 000, wartość domyślna 15 000.

Przestarzałe. Ten parametr nie ma już wpływu na wynik.

Pole symmetry_mode kontroluje zachowanie symetrii podczas procesu generowania modelu.

Prawidłowe wartości to:

• off: Wyłącza symetrię.
• auto: Automatycznie określa i stosuje symetrię na podstawie geometrii wejściowej.
• on: Wymusza symetrię podczas generowania.

Określ pose_mode dla generowanego modelu.

Dostępne wartości:

• a-pose: Generuje model w pozycji A.
• t-pose: Generuje model w pozycji T.
• "" (pusty ciąg znaków): Nie zastosowano konkretnej pozy.

Użyj zamiast tego pose_mode. Określa, czy wygenerować model w pozycji A/T.

Nieobsługiwane przez Meshy-6. Żądania korzystające z Meshy-6 będą ignorować art_style, a niektóre kombinacje mogą powodować błędy. Dostępne wartości: realistic, sculpture.

Gdy ustawione na true, treść wejściowa zostanie automatycznie sprawdzona pod kątem potencjalnie szkodliwych treści. Jeśli zostaną wykryte szkodliwe treści, zadanie nie przejdzie do etapu generowania.

Sprawdzony zostanie tekst z prompt.

Określa, które formaty plików 3D mają zostać uwzględnione w wyniku. Generowane i zwracane będą tylko żądane formaty, co może skrócić czas realizacji zadania. Jeśli parametr zostanie pominięty, uwzględnione zostaną wszystkie obsługiwane formaty.

Dostępne wartości: glb, obj, fbx, stl, usdz, 3mf

Gdy ustawione na true, zadanie dodatkowo renderuje wersję preview z przezroczystym tłem (RGBA) i zwraca ją jako alpha_thumbnail_url w odpowiedzi GET. Istniejące pole thumbnail_url pozostaje bez zmian.

Gdy ustawione na true, usługa wykorzystuje wizję AI, aby automatycznie oszacować rzeczywistą wysokość obiektu i odpowiednio zmienić rozmiar modelu. Punkt początkowy domyślnie przyjmie wartość bottom, chyba że origin_at zostanie jawnie ustawione.

Żądanie było nieprawidłowe. Typowe przyczyny:

• Brakujący parametr: Brakuje wymaganego parametru (np. prompt, mode).
• Nieprawidłowy parametr: art_style nie jest jedną z dozwolonych wartości.
• Zbyt długi prompt: prompt przekracza limit znaków.
• Nieobsługiwany model dla low poly: ai_model: "meshy-6-lite" nie obsługuje model_type: "lowpoly".
• Nieobsługiwany model dla Ultra: geometry_resolution wymaga meshy-7.1 lub latest.

Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.

Niewystarczająca liczba kredytów, aby wykonać to zadanie.

Przekroczono limit szybkości.

To pole powinno mieć wartość "refine" podczas tworzenia zadania refine.

Odpowiadający identyfikator zadania preview.

Status podanego zadania preview musi mieć wartość SUCCEEDED.

Generuje mapy PBR (metaliczność, chropowatość, normalna) oprócz koloru bazowego. Mapa emisji jest dołączana również wtedy, gdy ai_model ma wartość meshy-6, z wyjątkiem texture_resolution: 8k (wtedy mapa emisji nie jest tworzona). meshy-6-lite, meshy-7.1 i latest nie generują mapy emisji, podobnie jak refine podglądu meshy-t2, który nie ustawia ai_model.

Rozdzielczość tekstury koloru bazowego. Jedna z wartości 2k (2048×2048), 4k (4096×4096) lub 8k (8192×8192). Wyższe rozdzielczości pozwalają uchwycić więcej szczegółów powierzchni. Dotyczy tylko mode refine.

Zamiast tego użyj texture_resolution — odpowiednik texture_resolution: "4k". Gdy oba są ustawione, pierwszeństwo ma texture_resolution.

Podaj dodatkowy prompt tekstowy, który pokieruje procesem teksturowania. Maksymalnie 800 znaków.

Podaj obraz 2D, który pokieruje procesem teksturowania. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.

Maksymalny rozmiar pliku: 20 MB.

Istnieją dwa sposoby podania obrazu:

• Publicznie dostępny URL: adres URL dostępny z poziomu publicznego internetu
• Data URI: zakodowany w base64 identyfikator URI danych obrazu. Przykład identyfikatora URI danych: data:image/jpeg;base64,<your base64-encoded image data>

Identyfikator modelu używanego do refine.

Dostępne wartości:

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (przestarzałe): użyj zamiast tego meshy-7.1.

Pomiń ten parametr, aby odziedziczyć model użyty w zadaniu preview, co utrzymuje preview i jego refine na tym samym modelu od początku do końca. Podaj jawną wartość, aby nadpisać to dziedziczenie.

Gdy ustawione na true, treść wejściowa zostanie automatycznie sprawdzona pod kątem potencjalnie szkodliwej zawartości. Jeśli zostanie wykryta szkodliwa treść, zadanie nie przejdzie do etapu generowania.

Sprawdzany będzie zarówno tekst z texture_prompt, jak i obraz z texture_image_url.

Usuwa podświetlenia i cienie z tekstury koloru bazowego, dając czystszy wynik, który lepiej sprawdza się przy niestandardowych ustawieniach oświetlenia.

Określa, które formaty plików 3D mają zostać uwzględnione w wyniku. Generowane i zwracane będą tylko żądane formaty, co może skrócić czas ukończenia zadania. Gdy pominięte, uwzględniane są wszystkie obsługiwane formaty.

Dostępne wartości: glb, obj, fbx, stl, usdz, 3mf

Gdy 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 bez zmian.

Gdy ustawione na true, usługa wykorzystuje wizję AI do automatycznego oszacowania rzeczywistej wysokości obiektu i odpowiedniego zmienienia rozmiaru modelu. Punkt początkowy domyślnie ustawi się na bottom, chyba że origin_at zostanie jawnie ustawiony.

Żądanie było niedopuszczalne. Typowe przyczyny:

• Nieprawidłowy identyfikator zadania: preview_task_id jest nieprawidłowy lub nie istnieje.
• Zadanie nie jest gotowe: zadanie preview jeszcze się nie powiodło.
• Niezgodność modeli: model AI zadania preview jest niezgodny z żądanym modelem refine.
• Nieobsługiwany model dla remove_lighting: remove_lighting jest ustawiony razem z ai_model: "meshy-6-lite".

Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.

Niewystarczająca liczba kredytów do wykonania tego zadania.

Nie znaleziono zadania preview wskazanego przez preview_task_id.

Przekroczono limit szybkości.

Unikalny identyfikator zadania Tekst na 3D do pobrania.

ID zadania Tekst na 3D do usunięcia.

Numer strony do stronicowania.

Limit rozmiaru strony. Maksymalna dozwolona wartość to 100 elementów.

Pole, według którego ma nastąpić sortowanie.

Dostępne wartości:

• +created_at: Sortowanie według czasu utworzenia w kolejności rosnącej.
• -created_at: Sortowanie według czasu utworzenia w kolejności malejącej.

Unikalny identyfikator zadania Tekst na 3D do przesyłania strumieniowego.

Unikalny identyfikator zadania. Choć jako szczegół implementacyjny używamy identyfikatorów zadań w postaci UUID z sortowaniem k, nie należy przyjmować żadnych założeń dotyczących formatu tego identyfikatora.

Typ zadania Tekst na 3D. Możliwe wartości to text-to-3d-preview dla zadań etapu preview oraz text-to-3d-refine dla zadań etapu refine.

Adres URL do pobrania pliku modelu 3D z teksturą wygenerowanego przez Meshy. Właściwość dla danego formatu zostanie pominięta, jeśli dany format nie został wygenerowany, zamiast zwracać pusty ciąg znaków.

To jest niezmieniony prompt, który został użyty do utworzenia zadania.

Utrzymywane dla zachowania zgodności wstecznej. To pole nie ma żadnego wpływu funkcjonalnego na generowane modele.

Niezmieniony art_style, który został użyty do utworzenia zadania preview. Niewspierane przez Meshy-6.

Utrzymywane dla zachowania zgodności wstecznej. To pole nie ma żadnego wpływu funkcjonalnego na generowane modele.

Dodatkowy prompt tekstowy dostarczony w celu ukierunkowania procesu teksturowania podczas etapu refine.

Przestarzałe; odczytaj zamiast tego geometry_resolution.

Poziom Ultra, z jakim uruchomiono zadanie preview (2k lub 4k); pomijane dla standard.

Adres URL do pobrania obrazu tekstury, który został użyty do ukierunkowania procesu teksturowania.

Adres URL do pobrania obrazu miniatury pliku modelu.

Adres URL do pobrania wersji thumbnail_url z przezroczystym tłem (RGBA). Występuje 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.

Adres URL do pobrania wideo podglądu. Zostanie usunięty w przyszłej wersji.

Postęp zadania (progress). Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Gdy zadanie zakończy się powodzeniem, przyjmie wartość 100.

Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0.

Znacznik czasu utworzenia zadania, w milisekundach.

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ść 0.

Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Tablica obiektów adresów URL tekstur wygenerowanych w ramach zadania. Zwykle zawiera ona tylko jeden obiekt adresu URL tekstury. Każdy obiekt adresu URL tekstury posiada następujące właściwości:

Liczba zadań poprzedzających.

Szczegóły błędu dla nieudanych zadań. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.

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).