Obraz na 3D API

Obraz na 3D API to funkcja, która umożliwia zintegrowanie możliwości Obraz na 3D od Meshy z Twoją własną aplikacją. W tej sekcji znajdziesz wszystkie informacje potrzebne do rozpoczęcia pracy z tym API.

POST/openapi/v1/image-to-3d

Create an Image to 3D Task

Ten punkt końcowy pozwala utworzyć nowe zadanie Obraz na 3D. Zapoznaj się z obiektem zadania Obraz na 3D, aby zobaczyć, jakie właściwości zawiera obiekt zadania Obraz na 3D.

Zadanie jest wykonywane w tle. Informacje o tym, jak długo zwykle to trwa, znajdziesz w sekcji Czasy przetwarzania.

Parametry

Wymagane jest podanie tylko jednego z pól input_task_id lub image_url. Jeśli podane zostaną oba, priorytet ma input_task_id.

Name
input_task_id
Type
string
Wymagane
Description
ID zakończonego zadania generowania obrazu, którego wynik ma zostać użyty jako obraz wejściowy. To zadanie musi być jednym z następujących: Tekst na obraz lub Obraz na obraz. Dodatkowo musiało zostać uruchomione przez API, mieć status SUCCEEDED i wygenerować dokładnie jeden obraz.

Name
image_url
Type
string
Wymagane
Description
Podaj obraz, który Meshy ma wykorzystać do utworzenia modelu. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.
Maksymalny rozmiar pliku: 20 MB.
Obraz można podać na dwa sposoby:
- Publicznie dostępny URL: adres URL dostępny z poziomu publicznego internetu.
- Data URI: zakodowany w base64 Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
domyślne standard
Description
Określa typ generowania siatki 3D.
Dostępne wartości:
- standard: zwykłe 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.
Gdy wybrano smart-topology, parametry should_remesh, save_pre_remeshed_model i decimation_mode są ignorowane, a akceptowane jest wyłącznie topology: triangle.
lowpoly zostanie wycofane 30 października 2026 r. Po tej dacie żądania z model_type: "lowpoly" będą zwracać błąd. Zalecamy przejście na Meshy T2.5 (model_type: "smart-topology" z ai_model: "meshy-t2.5"). Gdy wybrano lowpoly, parametry ai_model, topology, target_polycount, should_remesh i save_pre_remeshed_model są ignorowane.
Name
ai_model
Type
string
domyślne latest
Description
ID modelu do użycia. 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 ustawiana za pomocą target_polycount.
- meshy-t2.5 (domyślny): ostrzejsze szczegóły dla assetów do gier. Wynik w trójkątach oraz liczba ścian ustawiana za pomocą target_polycount.
Name
geometry_resolution
Type
string
domyślne standard
Description
Przebieg generowania geometrii. 2k uruchamia przebieg Ultra w rozdzielczości 2048³; 4k uruchamia go w rozdzielczości 4096³ dla najdrobniejszych szczegółów powierzchni.
Dostępne wartości: standard, 2k, 4k
Wymaga meshy-7.1 lub latest.
Name
ultra_mode
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego użyj geometry_resolution. ultra_mode: true jest równoważne geometry_resolution: "2k".
Name
should_texture
Type
boolean
domyślne true
Description
Określa, czy tekstury mają zostać wygenerowane. Ustawienie wartości false pomija fazę teksturowania, zwracając siatkę bez tekstur.

Dotyczy tylko gdy should_texture = true

Name
enable_pbr
Type
boolean
domyślne false
Description
Generuje mapy PBR (metaliczność, chropowatość, mapa normalnych) oprócz koloru bazowego. Mapa emisji jest również dołączana, gdy ai_model to meshy-6, z wyjątkiem texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 i latest nie generują mapy emisji.
Name
texture_resolution
Type
string
domyślne 2k
Description
Rozdzielczość tekstury koloru bazowego. Jedna z wartości 2k (2048×2048), 4k (4096×4096) lub 8k (8192×8192). Wyższe rozdzielczości odwzorowują więcej szczegółów powierzchni.
4k i 8k nie są dostępne dla ai_model meshy-6-lite. Przy 8k mapa emisji nie jest generowana.
Name
hd_texture
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego użyj texture_resolution — odpowiednik texture_resolution: "4k". Gdy oba parametry są ustawione, pierwszeństwo ma texture_resolution.
Name
texture_prompt
Type
string
Description
Podaj prompt tekstowy, który pokieruje procesem teksturowania. Maksymalnie 800 znaków.
Name
texture_image_url
Type
string
Description
Podaj obraz 2D, który pokieruje procesem teksturowania. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.
Maksymalny rozmiar pliku: 20 MB.
Obraz można podać na dwa sposoby:
- Publicznie dostępny URL: adres URL dostępny z poziomu publicznego internetu
- Data URI: zakodowany w base64 Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Teksturowanie na podstawie obrazu może nie działać optymalnie, jeśli istnieją znaczące różnice geometrii między oryginalnym assetem a przesłanym obrazem. Do sterowania procesem teksturowania można użyć tylko jednego z parametrów: texture_image_url lub texture_prompt. Jeśli podane zostaną oba parametry, domyślnie do teksturowania modelu zostanie użyty texture_prompt. Teksturowanie za pomocą tekstu lub obrazu kosztuje 10 kredytów za zadanie.

Name
should_remesh
Type
boolean
domyślne false (Meshy 6 and Meshy 7 models), true (others)
Description
Określa, czy włączyć fazę remesh. W celu uzyskania modelu najwyższej jakości zalecamy ustawienie should_remesh na false.

Dotyczy tylko gdy should_remesh = true

Name
topology
Type
string
domyślne triangle
Description
Określa topology wygenerowanego modelu.
Dostępne wartości:
- quad: generuje siatkę z przewagą czworokątów.
- triangle: generuje zdecymowaną siatkę trójkątów.
Wynik Smart Topology to wyłącznie trójkąty. Żądanie quad razem z ai_model meshy-t2 lub meshy-t2.5 zwraca błąd.
Name
decimation_mode
Type
integer
Description
Włącza adaptacyjną decymację poprzez ustawienie poziomu liczby wielokątów. Gdy jest ustawiona, target_polycount jest ignorowane.
Dostępne wartości:
- 1: Adaptacyjna — bardzo duża liczba wielokątów.
- 2: Adaptacyjna — duża liczba wielokątów.
- 3: Adaptacyjna — średnia liczba wielokątów.
- 4: Adaptacyjna — mała liczba wielokątów.
Name
save_pre_remeshed_model
Type
boolean
domyślne false
Description
Gdy ustawione na true, Meshy zapisuje dodatkowo plik GLB sprzed zakończenia fazy remesh.

Name
target_polycount
Type
integer
Description
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 — przy should_remesh: true dla modelu standard. Siatka jest poddawana remesh (decymacji) do w przybliżeniu tej liczby. Zakres od 100 do 300 000, domyślnie 30 000. Jeśli ustawiono decimation_mode, ma ono priorytet, a target_polycount jest ignorowane.
- Smart Topology — przy 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 uruchamiany, a should_remesh nie jest wymagane. Dla meshy-t2: zakres od 100 do 15 000, domyślnie 4000. Dla meshy-t2.5: zakres od 100 do 30 000, domyślnie 15 000.

Name
symmetry_mode
Type
string
⚠ przestarzałe
domyślne auto
Description
Przestarzałe. Ten parametr nie wpływa już 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.
Name
pose_mode
Type
string
domyślne ""
Description
Określa tryb pozy wygenerowanego modelu.
Dostępne wartości:
- a-pose: generuje model w pozycji A.
- t-pose: generuje model w pozycji T.
- "" (pusty ciąg znaków): brak określonej pozy.
Name
is_a_t_pose
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego użyj pose_mode. Określa, czy wygenerować model w pozycji A/T.
Name
surface_mode
Type
string
⚠ przestarzałe
Description
Nie wpływa już na wynik. Wybierał tryb generowania modelu, który został od tego czasu wycofany; zamiast tego użyj ai_model.
Akceptowane wartości to organic i hard; każda inna wartość zwraca 400.
Name
image_enhancement
Type
boolean
domyślne true
Description
Optymalizuje obraz wejściowy w celu uzyskania lepszych wyników. Ustaw na false, aby zachować dokładny wygląd obrazu wejściowego bez żadnego przetwarzania stylu.
Obsługiwane tylko wtedy, gdy ai_model to meshy-6, meshy-7.1 lub latest. Ustawienie tego z meshy-6-lite lub z model_type: smart-topology zwraca błąd.
Name
remove_lighting
Type
boolean
domyślne true
Description
Usuwa z tekstury koloru bazowego światła i cienie, dając czystszy wynik, który lepiej sprawdza się w niestandardowych ustawieniach oświetlenia.
Działa tylko wtedy, gdy ai_model to meshy-6. meshy-7.1 i latest akceptują ten parametr, ale go ignorują. Ustawienie tego z meshy-6-lite lub z model_type: smart-topology zwraca błąd.
Name
moderation
Type
boolean
domyślne false
Description
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 fazy generowania.
Sprawdzane będą treści pochodzące z pól image_url, texture_image_url i texture_prompt.
Name
target_formats
Type
string[]
Description
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
Jeśli parametr zostanie pominięty, generowane są wszystkie formaty oprócz 3mf. 3mf jest dołączany tylko wtedy, gdy zostanie wyraźnie podany.
Name
auto_size
Type
boolean
domyślne false
Description
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 ustawia się na bottom, chyba że origin_at zostanie jawnie podane.
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
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.
Name
multi_view_thumbnails
Type
boolean
domyślne false
Description
Gdy ustawione na true, zadanie dodatkowo renderuje cztery miniatury z czterech głównych kierunków (przód, prawa strona, tył, lewa strona) i zwraca je w polu thumbnail_urls w odpowiedzi GET. Istniejące pole thumbnail_url pozostaje bez zmian i nadal wskazuje widok z przodu, więc istniejący klienci nie są objęci zmianą.
Wydłuża czas realizacji zadania o około 3 sekundy.

Dotyczy tylko gdy auto_size = true

Name
origin_at
Type
string
domyślne bottom
Description
Położenie punktu początkowego, gdy auto_size jest włączone.
Dostępne wartości: bottom, center.

Zwracane dane

Właściwość result odpowiedzi zawiera id zadania nowo utworzonego zadania Obraz na 3D.

Tryby błędów

Name
400 - Bad Request
Description
Żądanie było nieprawidłowe. Typowe przyczyny:
- Brak parametru: należy podać image_url lub input_task_id.
- Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zadania Tekst na obraz lub Obraz na obraz ze statusem SUCCEEDED, które wygenerowało dokładnie jeden obraz.
- Nieprawidłowy format obrazu: podany image_url nie jest w obsługiwanym formacie (.jpg, .jpeg, .png, .webp).
- Niedostępny URL: nie udało się pobrać image_url (404 lub timeout).
- Zbyt duży obraz: obraz image_url lub texture_image_url przekracza 20 MB.
- Nieprawidłowy Data URI: ciąg base64 jest nieprawidłowo sformatowany.
- Nieprawidłowa kombinacja parametrów: enable_pbr jest obsługiwane tylko wtedy, gdy should_texture ma wartość true.
- 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.
- Nieobsługiwany model dla opcji obrazu: image_enhancement lub remove_lighting jest ustawione razem z ai_model: "meshy-6-lite" lub model_type: "smart-topology".
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/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Pobierz zadanie Obraz na 3D

Ten punkt końcowy umożliwia pobranie zadania Obraz na 3D na podstawie prawidłowego id zadania. Zapoznaj się z sekcją Obiekt zadania Obraz na 3D, aby zobaczyć, jakie właściwości są zawarte w obiekcie zadania Obraz na 3D.

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Obraz na 3D do pobrania.

Zwracane dane

Odpowiedź zawiera obiekt zadania Obraz na 3D. Szczegóły znajdziesz w sekcji Obiekt zadania Obraz na 3D.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

DELETE/openapi/v1/image-to-3d/:id

Usuwanie zadania Obraz na 3D

Ten punkt końcowy trwale usuwa zadanie Obraz na 3D, w tym wszystkie powiązane modele i dane. Ta operacja jest nieodwracalna.

Parametry ścieżki

Name
id
Type
path
Description
ID zadania Obraz na 3D do usunięcia.

Status zadania

Zadanie, które wciąż ma status PENDING, zostaje usunięte, a kredyty pobrane w momencie utworzenia są zwracane.

Zadanie, które ma już status IN_PROGRESS, nie może zostać usunięte: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal się wykonuje. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie ono status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) jest usuwane bez zwrotu kredytów.

Zwracane wartości

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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 is left 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."
}

GET/openapi/v1/image-to-3d

Lista zadań Obraz na 3D

Ten punkt końcowy umożliwia pobranie listy zadań Obraz na 3D.

Parametry

Atrybuty opcjonalne

Name
page_num
Type
integer
Description
Numer strony do stronicowania. Zaczyna się i domyślnie wynosi 1.
Name
page_size
Type
integer
Description
Limit rozmiaru strony. Domyślnie 10 elementów. Maksymalna dozwolona wartość to 100 elementów.
Name
sort_by
Type
string
Description
Pole, według którego ma nastąpić sortowanie. Dostępne wartości:
- +created_at: Sortuj według czasu utworzenia rosnąco.
- -created_at: Sortuj według czasu utworzenia malejąco.

Zwraca

Zwraca stronicowaną listę obiektów zadań Obraz na 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Strumieniowanie zadania Obraz na 3D

Ten punkt końcowy strumieniuje aktualizacje w czasie rzeczywistym dla zadania Obraz na 3D przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Obraz na 3D do strumieniowania.

Zwraca

Zwraca strumień Obiektów zadania Obraz na 3D jako Server-Sent Events.

Dla zadań PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i status.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/image-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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

Obiekt zadania Obraz na 3D

Obiekt zadania Obraz na 3D to jednostka pracy śledzona przez Meshy w celu wygenerowania modelu 3D na podstawie wejściowego obrazu. Obiekt ma następujące właściwości:

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania. Mimo że jako szczegół implementacyjny używamy identyfikatorów zadań w formie UUID z zachowaniem porządku k-sortowalnego, nie należy przyjmować żadnych założeń co do formatu tego identyfikatora.
Name
type
Type
string
Description
Typ zadania Obraz na 3D. Wartość to image-to-3d.
Name
model_urls
Type
object
Description
Pobieralny URL do pliku modelu 3D z nałożoną teksturą, wygenerowanego przez Meshy. Właściwość dla danego formatu zostanie pominięta, jeśli ten format nie został wygenerowany, zamiast zwracać pusty ciąg znaków.
- 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 obecne 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 format 3mf został zażądany poprzez target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Pobieralny URL do oryginalnego pliku wyjściowego GLB sprzed remeshowania.
  Dostępne tylko wtedy, gdy zadanie zostało utworzone zarówno z should_remesh: true, jak i save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Pobieralny URL do miniatury obrazu pliku modelu. Odpowiednik thumbnail_urls.front, gdy jest obecny; zachowany dla zgodności wstecznej.
Name
alpha_thumbnail_url
Type
string
Description
Pobieralny URL do wersji thumbnail_url z przezroczystym tłem (RGBA). Obecny tylko wtedy, gdy zadanie zostało utworzone z alpha_thumbnail: true, a przezroczysty podgląd został pomyślnie wyrenderowany; w przeciwnym razie to pole jest pomijane.
Name
thumbnail_urls
Type
object
Description
Pobieralne adresy URL czterech miniatur przedstawiających model 3D z czterech głównych kierunków. Każda wartość to podpisany URL do obrazu PNG 512×512, wyrenderowanego z użyciem tych samych materiałów i oświetlenia co thumbnail_url. Przydatne do podglądu modelu z wielu kątów w potokach wsadowych bez konieczności pobierania pliku GLB.
Obecne tylko wtedy, gdy zadanie zostało utworzone z multi_view_thumbnails: true i osiągnęło status SUCCEEDED. Starsze zadania oraz zadania utworzone bez tej opcji nie będą zawierać tego pola.
- Name
  front
  Type
  string
  Description
  Widok z przodu, obrót 0° wokół osi pionowej (odpowiada thumbnail_url).
- Name
  right
  Type
  string
  Description
  Widok z prawej strony, obrót 90°.
- Name
  back
  Type
  string
  Description
  Widok z tyłu, obrót 180°.
- Name
  left
  Type
  string
  Description
  Widok z lewej strony, obrót 270°.
Name
texture_prompt
Type
string
Description
Prompt tekstowy, który został użyty do pokierowania procesem teksturowania.
Name
texture_image_url
Type
string
Description
Pobieralny URL do obrazu tekstury, który został użyty do pokierowania procesem teksturowania.
Name
ultra_mode
Type
boolean
⚠ przestarzałe
Description
Przestarzałe; zamiast tego odczytaj geometry_resolution.
Name
geometry_resolution
Type
string
Description
Poziom Ultra, w jakim działało zadanie (2k lub 4k); pomijane dla standard.
Name
progress
Type
integer
Description
Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie wynosić 0. Gdy zadanie zakończy się powodzeniem, przyjmie wartość 100.
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 wynosić 0.
Znacznik czasu reprezentuje liczbę milisekund, która upłynęła od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, godzina 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 jeszcze się nie zakończyło, ta właściwość będzie wynosić 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 wygenerowanych w ramach zadania. Zazwyczaj zawiera ona tylko jeden obiekt URL tekstury. Każdy obiekt 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 metaliczności.
  Jeśli zadanie zostało utworzone z enable_pbr: false, ta właściwość zostanie 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ść zostanie 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ść zostanie 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 ma wartość meshy-6-lite, meshy-7.1, meshy-t2 lub latest, ta właściwość zostanie pominięta.
Name
preceding_tasks
Type
integer
Description
Liczba zadań poprzedzających.
Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.
Name
task_error
Type
object
Description
Szczegóły błędu dla zadań zakończonych niepowodzeniem. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.
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 (w przypadku niepowodzenia kredyty są zwracane).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}