Tekst na 3D API

Generuj modele 3D z tekstowych promptów we własnej aplikacji.

Tekst na 3D działa w dwóch krokach. Najpierw utwórz zadanie preview (mode: "preview"), aby wygenerować siatkę 3D bez tekstury, dzięki czemu możesz sprawdzić kształt. Następnie wyślij identyfikator zadania zakończonego sukcesem preview do zadania refine (mode: "refine"), aby nałożyć teksturę na siatkę. Oba kroki korzystają z tego samego punktu końcowego.

POST/openapi/v2/text-to-3d

Create a Text to 3D preview task

Tworzy zadanie podglądu Tekst na 3D, które generuje siatkę 3D bez tekstury (tylko geometrię) na podstawie promptu tekstowego. To pierwszy krok dwuetapowego procesu. Po pomyślnym zakończeniu podglądu wyślij jego identyfikator zadania w zadaniu refine, aby nałożyć teksturę na siatkę. Zobacz Create a Text to 3D refine task. Pełny schemat odpowiedzi znajdziesz w The Text to 3D task object.

Zadanie jest wykonywane w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w Processing times.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parametry

Name
mode
Type
string
Wymagane
Description
Etap dwuetapowego procesu. Wyślij preview, aby utworzyć zadanie podglądu.
Name
prompt
Type
string
Wymagane
Description
Tekst opisujący generowany obiekt, maksymalnie 800 znaków. Dłuższy tekst zwraca 400.
Name
model_type
Type
string
domyślne standard
Description
Typ generowanej siatki 3D.
Dostępne wartości:
- standard: wysoko szczegółowa siatka 3D
- smart-topology: siatka Smart Topology. Wybierz model za pomocą ai_model (meshy-t2 lub meshy-t2.5).
Przy smart-topology Meshy ignoruje should_remesh i decimation_mode oraz akceptuje wyłącznie topology: triangle.
Name
ai_model
Type
string
domyślne latest
Description
Model AI generujący model 3D. Dostępne wartości zależą od model_type.
Modele standardowe (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (przestarzałe): zamiast tego wyślij meshy-7.1
Modele Smart Topology (model_type: smart-topology):
- meshy-t2: czystsza topology, natywnie rozdzielone części, wyjście w trójkątach oraz liczba ścian ustawiana za pomocą target_polycount
- meshy-t2.5 (domyślny): ostrzejsze detale dla assetów do gier, wyjście w trójkątach oraz liczba ścian ustawiana za pomocą target_polycount
Zobacz Models, aby sprawdzić, który model pasuje do Twojego projektu, np. postaci do gry lub wydruku 3D.
Name
geometry_resolution
Type
string
domyślne standard
Description
Przebieg generowania geometrii. Dotyczy wyłącznie zadań podglądu. Refine z tym parametrem zwraca 400.
Dostępne wartości:
- standard
- 2k: uruchamia przebieg Ultra w rozdzielczości 2048³
- 4k: uruchamia przebieg Ultra w rozdzielczości 4096³, dla bardziej szczegółowej powierzchni
2k wymaga meshy-7.1, latest lub przestarzałego meshy-7. 4k wymaga meshy-7.1 lub latest. Inne modele zwracają 400.
Name
ultra_mode
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego wyślij geometry_resolution. ultra_mode: true jest równoważne geometry_resolution: "2k".
Name
should_remesh
Type
boolean
domyślne true (meshy-6-lite), false (other models)
Description
Czy wykonać remesh modelu po wygenerowaniu. Aby uzyskać model 3D najwyższej jakości, wyślij false.

Dotyczy tylko gdy should_remesh = true

Name
topology
Type
string
domyślne triangle
Description
Typ ścian modelu po remeshu.
Dostępne wartości:
- quad: siatka z przewagą czworokątów
- triangle: zdecymowana siatka trójkątów
Wynik Smart Topology jest wyłącznie trójkątny. Wysłanie quad z ai_model meshy-t2 lub meshy-t2.5 zwraca 400.
Name
decimation_mode
Type
integer
Description
Adaptacyjna liczba ścian, według poziomu. Gdy ją ustawisz, Meshy ignoruje target_polycount.
Dostępne wartości:
- 1: ultra
- 2: wysoki
- 3: średni
- 4: niski

Name
target_polycount
Type
integer
Description
Docelowa liczba ścian. Wynik może się różnić od wartości docelowej, w zależności od geometrii. Parametr ma zastosowanie w dwóch odrębnych przypadkach:
- Remesh: przy should_remesh: true na modelu standard. Meshy wykonuje remesh (decymację) siatki do tej liczby. Jeśli ustawisz decimation_mode, Meshy używa go i ignoruje target_polycount.
- Smart Topology: przy model_type: smart-topology i ai_model meshy-t2 lub meshy-t2.5. Meshy generuje model bezpośrednio z tą liczbą ścian. Remesh nie jest wykonywany i should_remesh nie jest potrzebny.
Poniższa tabela pokazuje zakres i wartość domyślną dla każdego przypadku:
Przypadek Zakres Domyślna
Remesh 100 do 300000 30000
meshy-t2 100 do 15000 4000
meshy-t2.5 100 do 30000 15000
Wartość spoza zakresu zwraca 400.
W przypadku assetu do gry typu low-poly użyj modelu Smart Topology zamiast wykonywać remesh modelu standardowego. Zobacz Models.

Przypadek	Zakres	Domyślna
Remesh	`100` do `300000`	`30000`
`meshy-t2`	`100` do `15000`	`4000`
`meshy-t2.5`	`100` do `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ przestarzałe
domyślne auto
Description
Pomiń ten parametr. Nie wpływa on na wynik.
Dostępne wartości:
- off: wyłącza symetrię
- auto: stosuje symetrię na podstawie geometrii wejściowej
- on: wymusza symetrię podczas generowania
Name
pose_mode
Type
string
domyślne ""
Description
Poza generowanego modelu.
Dostępne wartości:
- a-pose: pozycja A
- t-pose: pozycja T
- "" (pusty ciąg): brak konkretnej pozycji
Name
is_a_t_pose
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego wyślij pose_mode. Określa, czy wygenerować model w pozycji A czy T.
Name
art_style
Type
string
⚠ przestarzałe
domyślne realistic
Description
Pomiń ten parametr. Meshy go ignoruje.
Name
moderation
Type
boolean
domyślne false
Description
Czy sprawdzić prompt pod kątem szkodliwej treści przed generowaniem. Jeśli Meshy wykryje szkodliwą treść, żądanie zwraca 400, a Meshy nie tworzy zadania.
Name
target_formats
Type
string[]
Description
Formaty plików do wygenerowania. Meshy generuje i zwraca tylko te formaty, co może skrócić zadanie. Jeśli pominiesz ten parametr, Meshy generuje wszystkie formaty oprócz 3mf, który generuje tylko na żądanie.
Dostępne wartości:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
Czy dodatkowo wyrenderować podgląd z przezroczystym tłem (RGBA), zwracany w alpha_thumbnail_url podczas pobierania zadania. thumbnail_url nie ulega zmianie.
Name
auto_size
Type
boolean
domyślne false
Description
Czy oszacować rzeczywistą wysokość obiektu za pomocą wizji AI i zmienić rozmiar modelu do tej wartości. Meshy umieszcza punkt początkowy na dole, chyba że ustawisz origin_at.

Dotyczy tylko gdy auto_size = true

Name
origin_at
Type
string
domyślne bottom
Description
Gdzie umieścić punkt początkowy modelu: bottom lub center.

Zwracane wartości

Pole result odpowiedzi zawiera identyfikator nowego zadania Tekst na 3D.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje napotkany problem. Na przykład:
- Brak parametru: brakuje wymaganego parametru, np. prompt lub mode.
- Zbyt długi prompt: prompt przekracza limit znaków.
- Nieobsługiwany model dla Ultra: geometry_resolution to 2k lub 4k, z ai_model, który tego nie obsługuje.
Popraw żądanie i wyślij je ponownie. Zobacz Errors.
Name
401 - Unauthorized
Description
Brak klucza API lub klucz jest nieprawidłowy. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Na przykład:
- Niewystarczające kredyty: konto nie ma wystarczającej liczby kredytów na to zadanie lub osiągnięto limit kredytów. Sprawdź saldo kredytów, a następnie spróbuj ponownie.
- Plan bezpłatny: utworzenie zadania wymaga płatnego planu. Ulepsz swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
Name
403 - Forbidden
Description
Moderacja treści zablokowała prompt lub obraz wejściowy. Zmień dane wejściowe, a następnie spróbuj ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Odczekaj, a następnie spróbuj ponownie. Zobacz Rate limits.

POST/openapi/v2/text-to-3d

Utwórz zadanie refine Tekst na 3D

Tworzy zadanie refine Tekst na 3D, które teksturuje siatkę ukończonego zadania preview. Wyślij ID udanego zadania preview jako preview_task_id. Zobacz Utwórz zadanie preview Tekst na 3D. To drugi krok dwuetapowego procesu.

Zadanie działa w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w Czasach przetwarzania.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parametry

Name
mode
Type
string
Wymagane
Description
Krok dwuetapowego procesu. Wyślij refine, aby utworzyć zadanie refine.
Name
preview_task_id
Type
string
Wymagane
Description
ID zadania preview do teksturowania. Zadanie preview musi mieć status SUCCEEDED.
Name
enable_pbr
Type
boolean
domyślne false
Description
Czy wygenerować również mapy PBR (metaliczność, chropowatość i normalną) wraz z kolorem bazowym.
Przy ai_model meshy-6 Meshy generuje też mapę emisji, z wyjątkiem texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 i latest nie generują mapy emisji. Nie generuje jej również refine zadania preview meshy-t2 lub meshy-t2.5, które nie ustawia ai_model. Przy ai_model: meshy-n1 wartość true zwraca 400.
Name
texture_resolution
Type
string
domyślne 2k
Description
Rozdzielczość tekstury koloru bazowego. Dotyczy tylko zadań refine. Preview z tym parametrem zwraca 400.
Dostępne wartości:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Wyższe rozdzielczości uchwycają więcej szczegółów powierzchni. 4k i 8k wymagają ai_model meshy-6, meshy-7.1 lub latest. Przy meshy-n1 zwracają 400. Przy 8k Meshy nie generuje mapy emisji.
Name
hd_texture
Type
boolean
⚠ przestarzałe
domyślne false
Description
Wyślij zamiast tego texture_resolution. hd_texture: true jest równoważne texture_resolution: "4k". Jeśli wyślesz oba, Meshy używa texture_resolution.
Name
texture_prompt
Type
string
Description
Tekst, który kieruje teksturowaniem, do 800 znaków. Dłuższy tekst zwraca 400. Wyślij texture_prompt albo texture_image_url, nie oba naraz. Jeśli wyślesz oba, Meshy użyje texture_prompt. Przy ai_model: meshy-n1 wysłanie tego parametru zwraca 400.
Name
texture_image_url
Type
string
Description
Obraz 2D, który kieruje teksturowaniem, podany jako publiczny URL lub zakodowany w base64 Data URI, na przykład data:image/jpeg;base64,<twoje dane obrazu zakodowane w base64>.
Obraz musi być plikiem .jpg, .jpeg, .png lub .webp o rozmiarze maksymalnie 20 MB, co najmniej 32 pikselach z każdej strony i maksymalnie 178 956 970 pikselach (szerokość × wysokość).
Przy ai_model: meshy-n1 Meshy teksturuje na podstawie tego obrazu jako widoku z przodu.
Teksturowanie na podstawie obrazu może nie działać dobrze, gdy kształt na obrazie znacznie różni się od modelu.
Name
ai_model
Type
string
domyślne inherited from the preview task
Description
Model AI, który teksturuje siatkę.
Dostępne wartości:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: 2K tekstura koloru bazowego wyłącznie z obrazu referencyjnego. Bez promptu tekstowego, bez map PBR, bez 4K ani 8K.
- meshy-7 (przestarzałe): zamiast tego wyślij meshy-7.1
Pomiń ten parametr, aby użyć modelu zadania preview, dzięki czemu preview i jego refine działają na tym samym modelu od początku do końca. Wyślij wartość, aby go nadpisać. Jawne latest rozwiązuje się tak samo jak w zadaniu preview, więc preview latest i jego refine latest zawsze używają tego samego modelu tekstur.
Przy meshy-n1 Meshy teksturuje na podstawie texture_image_url. Bez tego parametru Meshy używa obrazu referencyjnego zapisanego przez preview meshy-7.1 lub latest. Każde inne preview zwraca 400, chyba że wyślesz texture_image_url. Preview może mieć maksymalnie 7 999 999 trójkątów. Preview zremeshowane do quadów zwraca 400.
Name
moderation
Type
boolean
domyślne false
Description
Czy sprawdzić texture_prompt i texture_image_url pod kątem szkodliwych treści przed generowaniem. Jeśli Meshy wykryje szkodliwe treści, żądanie zwraca 400, a Meshy nie tworzy zadania.
Name
remove_lighting
Type
boolean
domyślne true
Description
Czy usunąć podświetlenia i cienie z tekstury koloru bazowego. Czystszy wynik lepiej sprawdza się przy niestandardowym oświetleniu.
Działa tylko wtedy, gdy ai_model to meshy-6. meshy-7.1 i latest akceptują ten parametr i go ignorują, podobnie jak refine zadania preview meshy-t2 lub meshy-t2.5, które nie ustawia ai_model. Wysłanie go z meshy-6-lite zwraca 400. Przy meshy-n1 wartość true zwraca 400.
Name
target_formats
Type
string[]
Description
Formaty plików do wygenerowania. Meshy generuje i zwraca tylko te formaty, co może skrócić zadanie. Jeśli pominiesz ten parametr, Meshy wygeneruje wszystkie formaty oprócz 3mf, który generuje tylko na żądanie.
Dostępne wartości:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
Czy wyrenderować również podgląd z przezroczystym tłem (RGBA), zwracany w alpha_thumbnail_url podczas pobierania zadania. thumbnail_url się nie zmienia.
Name
auto_size
Type
boolean
domyślne false
Description
Czy oszacować rzeczywistą wysokość obiektu za pomocą wizji AI i dopasować do niej rozmiar modelu. Meshy umieszcza punkt początkowy na dole, chyba że ustawisz origin_at.

Dotyczy tylko gdy auto_size = true

Name
origin_at
Type
string
domyślne bottom
Description
Gdzie umieścić punkt początkowy modelu, bottom lub center.

Zwracane dane

Pole result odpowiedzi zawiera ID nowego zadania Tekst na 3D.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje znaleziony problem. Na przykład:
- Nieprawidłowe ID zadania: preview_task_id jest nieprawidłowe lub nie odpowiada żadnemu z twoich zadań preview.
- Zadanie nie jest gotowe: Zadanie preview jeszcze się nie zakończyło powodzeniem.
- Niezgodność modeli: Model AI zadania preview nie współpracuje z żądanym modelem refine.
- Nieobsługiwany model dla remove_lighting: remove_lighting zostało wysłane z ai_model: "meshy-6-lite".
- Brak obrazu referencyjnego dla Meshy N1: ai_model: meshy-n1 zostało wysłane bez texture_image_url, a preview nie ma obrazu referencyjnego, którego Meshy N1 mógłby użyć. Wyślij texture_image_url.
- Preview z quadami dla Meshy N1: ai_model: meshy-n1 zostało wysłane dla preview zremeshowanego do quadów. Wykonaj refine z innym ai_model.
- Zbyt dużo trójkątów dla Meshy N1: Przy ai_model: meshy-n1 preview ma więcej niż 7 999 999 trójkątów. Wykonaj refine z innym ai_model.
- Nieobsługiwana opcja dla Meshy N1: ai_model: meshy-n1 zostało wysłane z jedną z tych opcji:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution ustawione na 4k lub 8k
  - hd_texture: true bez texture_resolution
  - remove_lighting: true
Popraw żądanie, a następnie wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Brak klucza API lub klucz jest nieprawidłowy. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Na przykład:
- Niewystarczające kredyty: Konto nie ma wystarczającej liczby kredytów na to zadanie lub osiągnęło limit kredytów. Sprawdź swoje saldo kredytów, a następnie spróbuj ponownie.
- Plan darmowy: Utworzenie zadania wymaga płatnego planu. Zaktualizuj swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
Name
403 - Forbidden
Description
Moderacja treści zablokowała prompt lub obraz wejściowy. Zmień dane wejściowe, a następnie spróbuj ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Poczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

GET/openapi/v2/text-to-3d/:id

Pobierz zadanie Tekst na 3D

Zwraca zadanie Tekst na 3D na podstawie jego ID. Działa zarówno dla zadań preview, jak i refine.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?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=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi tworzenia.

Zwraca

Obiekt zadania Tekst na 3D.

Przykłady

Poniższa tabela przedstawia przykładowy model dla każdego mode.

Mode	Przykładowy model
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Usuń zadanie Tekst na 3D

Trwale usuwa zadanie Tekst na 3D, w tym jego modele i dane. Nie możesz cofnąć usunięcia.

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Parametry ścieżki

Name
id
Type
path
Description
ID zadania do usunięcia.

Status zadania

Usunięcie zadania o statusie PENDING zwraca kredyty wykorzystane podczas jego tworzenia.

Zadania o statusie IN_PROGRESS nie można usunąć. Żądanie zwraca 409 Conflict, a zadanie nadal się wykonuje. Meshy nie zwraca kredytów za zadanie, które już się rozpoczęło, więc jego usunięcie kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Usunięcie zadania o statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie powoduje zwrotu kredytów.

Zwraca

200 OK, gdy zadanie zostało usunięte, lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

GET/openapi/v2/text-to-3d

Lista zadań Tekst na 3D

Zwraca listę Twoich zadań Tekst na 3D.

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

Parametry

Name
page_num
Type
integer
domyślne 1
Description
Numer strony do zwrócenia, maksymalnie 255. Większa wartość zwróci 400.
Name
page_size
Type
integer
domyślne 10
Description
Liczba zadań na stronę, maksymalnie 100.
Name
sort_by
Type
string
Description
Kolejność sortowania.
Dostępne wartości:
- +created_at: od najstarszych
- -created_at: od najnowszych

Zwraca

Stronicowaną listę obiektów zadań Tekst na 3D.

GET/openapi/v2/text-to-3d/:id/stream

Przesyłanie strumieniowe zadania Tekst na 3D

Przesyła strumieniowo aktualizacje zadania Tekst na 3D jako zdarzenia Server-Sent Events (SSE).

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": null,

"consumed_credits": 20
}

Parametry

Name
id
Type
path
Description
Identyfikator zadania z odpowiedzi na żądanie utworzenia.

Zwraca

Strumień obiektów zadania Tekst na 3D jako zdarzenia Server-Sent Events.

Każde zdarzenie zawiera pełny obiekt zadania, w tej samej postaci, jaką zwraca punkt końcowy Get. Gdy zadanie ma status PENDING lub IN_PROGRESS, jego pola wynikowe nie mają jeszcze wartości.

Obiekt zadania Tekst na 3D

Obiekt zadania Tekst na 3D opisuje jedno zadanie generujące model 3D na podstawie promptu tekstowego. Przechowuje on status, progress oraz pliki modelu, gdy zadanie zakończy się powodzeniem. Tekst na 3D ma dwa etapy, preview i refine. Zadanie preview generuje model 3D zawierający wyłącznie siatkę, a zadanie refine generuje teksturowany model 3D na podstawie wyniku etapu preview.

Właściwości

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?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=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
Identyfikator zadania. Traktuj go jako nieprzejrzysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, text-to-3d-preview dla zadania preview lub text-to-3d-refine dla zadania refine.
Name
model_urls
Type
object
Description
Adresy URL do pobrania wygenerowanego modelu 3D, po jednym dla każdego formatu pliku. Format, którego zadanie nie wygenerowało, nie ma odpowiedniego klucza, zamiast pustego ciągu znaków.
- Name
  glb
  Type
  string
  Description
  Plik GLB.
- Name
  fbx
  Type
  string
  Description
  Plik FBX.
- Name
  usdz
  Type
  string
  Description
  Plik USDZ.
- Name
  obj
  Type
  string
  Description
  Plik OBJ.
- Name
  mtl
  Type
  string
  Description
  Plik MTL.
- Name
  stl
  Type
  string
  Description
  Plik STL.
- Name
  3mf
  Type
  string
  Description
  Plik 3MF. Obecny tylko wtedy, gdy target_formats zawiera 3mf.
Name
prompt
Type
string
Description
prompt wysłany w celu utworzenia zadania, niezmieniony.
Name
texture_prompt
Type
string
Description
Prompt tekstowy wysłany w celu ukierunkowania teksturowania na etapie refine.
Name
ultra_mode
Type
boolean
⚠ przestarzałe
Description
Zamiast tego odczytaj geometry_resolution.
Name
geometry_resolution
Type
string
Description
Poziom Ultra, z jakim uruchomiono zadanie preview, 2k lub 4k. Pole to jest nieobecne dla standard.
Name
texture_image_url
Type
string
Description
Adres URL do pobrania obrazu wysłanego w celu ukierunkowania teksturowania.
Name
thumbnail_url
Type
string
Description
Adres URL do pobrania miniatury modelu 3D.
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, a Meshy wyrenderowało przezroczysty podgląd.
Name
progress
Type
integer
Description
Stopień ukończenia zadania, wyrażony w procentach. Wynosi 0, dopóki zadanie się nie rozpocznie, i 100, gdy zakończy się powodzeniem.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach uniksowych. Wynosi 0, dopóki zadanie się nie rozpocznie.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach uniksowych.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach uniksowych. Wynosi 0, dopóki zadanie się nie zakończy.
Name
status
Type
string
Description
Status zadania, jeden z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
texture_urls
Type
array
Description
Adresy URL do pobrania wygenerowanych map tekstur, w postaci tablicy obiektów. Zazwyczaj zawiera jeden obiekt. Każdy obiekt ma następujące pola:
- Name
  base_color
  Type
  string
  Description
  Mapa koloru bazowego.
- Name
  metallic
  Type
  string
  Description
  Mapa metaliczności. Nieobecna, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Mapa normalnych. Nieobecna, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Mapa chropowatości. Nieobecna, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Mapa emisji. Nieobecna w każdym z następujących przypadków:
  
  Zadanie zostało utworzone z enable_pbr: false.
  
  ai_model to meshy-6-lite, meshy-7, meshy-7.1 lub latest.
  
  texture_resolution to 8k.
  
  Zadanie wykonuje refine podglądu meshy-t2 lub meshy-t2.5 bez ustawienia ai_model.
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym zadaniem w kolejce. Wartość ta ma znaczenie tylko wtedy, gdy zadanie ma status PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem. Wartość to null, chyba że status to FAILED. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie. Obecna, gdy status to PENDING, IN_PROGRESS lub SUCCEEDED. Wynosi 0 dla zadania ze statusem FAILED, ponieważ Meshy zwraca kredyty w przypadku niepowodzenia zadania.