API Obraz na 3D

Zamień obraz w model 3D, teksturowany lub nieteksturowany, w wybranych przez siebie formatach. Wyślij obraz lub skorzystaj z wyniku zadania Tekst na obraz lub Obraz na obraz.

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

Utwórz zadanie Obraz na 3D

Tworzy zadanie Obraz na 3D. Zadanie jest wykonywane w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w Czasach przetwarzania.

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"]
  }'

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

Response

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

Parametry

Name
input_task_id
Type
string
Wymagane
Description
Wymagane, chyba że wyślesz image_url. Identyfikator zadania Tekst na obraz lub Obraz na obraz, którego obraz chcesz użyć jako danych wejściowych. Zadanie musi zostać utworzone przez Ciebie za pomocą API, mieć status SUCCEEDED i musi wygenerować dokładnie jeden obraz.

Name
image_url
Type
string
Wymagane
Description
Wymagane, chyba że wyślesz input_task_id. Obraz do przekształcenia w model 3D, podany jako publiczny adres URL lub zakodowany w base64 Data URI, na przykład data:image/jpeg;base64,<your base64-encoded image data>. Jeśli wyślesz oba, Meshy użyje input_task_id.
Obraz musi być plikiem JPG, JPEG, PNG lub WebP o rozmiarze co najwyżej 20 MB, co najmniej 32 pikseli po każdej stronie i co najwyżej 178 956 970 pikseli (szerokość × wysokość).

Name
model_type
Type
string
domyślne standard
Description
Rodzaj generowanej siatki 3D.
Dostępne wartości:
- standard: siatka o wysokim poziomie szczegółowości
- smart-topology: siatka z modelu Smart Topology, który wybierasz za pomocą ai_model (meshy-t2 lub meshy-t2.5)
Przy smart-topology Meshy ignoruje should_remesh, save_pre_remeshed_model i decimation_mode, i 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):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (przestarzałe): zamiast tego użyj meshy-7.1
Modele Smart Topology (model_type: smart-topology) generują trójkąty, przy liczbie ścianek, którą możesz ustawić za pomocą target_polycount:
- meshy-t2: czystsza topology i naturalnie oddzielone części
- meshy-t2.5 (domyślny): ostrzejsze szczegóły dla assetów do gier
Name
geometry_resolution
Type
string
domyślne standard
Description
Przebieg generowania geometrii.
Dostępne wartości:
- standard
- 2k: uruchamia przebieg Ultra w rozdzielczości 2048³
- 4k: uruchamia przebieg Ultra w rozdzielczości 4096³, dla maksymalnej szczegółowości powierzchni
2k wymaga meshy-7.1, latest lub przestarzałego meshy-7. 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
Czy generować tekstury. true zwraca model z teksturą, a false pomija teksturowanie i zwraca siatkę bez tekstury.

Dotyczy tylko gdy should_texture = true

Name
texture_model
Type
string
domyślne depends on ai_model
Description
Model AI teksturujący model 3D w ramach tego samego zadania. Pomiń ten parametr, aby użyć domyślnego modelu tekstur dla Twojego ai_model. Nie zmienia to kosztu w kredytach.
Dostępne wartości:
- meshy-7: Meshy 7, z mapami PBR i teksturami do 8K
- meshy-n1: Meshy N1, tekstura koloru bazowego 2K wyłącznie na podstawie obrazów referencyjnych
- meshy-6-lite: Meshy 6 Lite, tekstura 2K przy najniższym koszcie
- meshy-6: Meshy 6, dostępny tylko jako domyślny dla ai_model: meshy-6
Każdy ai_model obsługuje meshy-7, meshy-n1 i meshy-6-lite. Opcja, której wybrany model tekstur nie obsługuje, zwraca 400. Przy meshy-n1, wygenerowany model powyżej 7 999 999 trójkątów kończy zadanie niepowodzeniem, a Meshy zwraca za nie kredyty. Przy should_texture: false Meshy ignoruje texture_model, ale nieznana wartość nadal zwraca 400.
Zobacz Modele, aby dowiedzieć się, co robi każdy model tekstur i który wybrać.
Name
enable_pbr
Type
boolean
domyślne false
Description
Czy generować również mapy PBR (metaliczność, chropowatość i normal map) oprócz koloru bazowego. true wymaga should_texture: true i zwraca 400 przy should_texture: false. Przy texture_model: meshy-n1, true zwraca 400.
Model tekstur Meshy 6 generuje również mapę emisji, z wyjątkiem przy texture_resolution: 8k.
Name
texture_resolution
Type
string
domyślne 2k
Description
Rozmiar tekstury koloru bazowego. Większa tekstura zawiera więcej szczegółów powierzchni.
Dostępne wartości:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k i 8k wymagają modelu tekstur Meshy 7 lub Meshy 6 i zwracają 400 przy pozostałych. Przy 8k Meshy nie generuje mapy emisji.
Name
hd_texture
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego użyj texture_resolution. hd_texture: true jest równoważne texture_resolution: "4k". Jeśli wyślesz oba, Meshy użyje texture_resolution.
Name
texture_prompt
Type
string
Description
Tekst naprowadzający teksturę, do 800 znaków. Dłuższy tekst zwraca 400. Przy texture_model: meshy-n1, wysłanie go zwraca 400.
Name
texture_image_url
Type
string
Description
Obraz naprowadzający teksturę, podany jako publiczny adres URL lub zakodowany w base64 Data URI, na przykład data:image/jpeg;base64,<your base64-encoded image data>. Obraz musi być plikiem JPG, JPEG, PNG lub WebP o rozmiarze co najwyżej 20 MB, co najmniej 32 pikseli po każdej stronie i co najwyżej 178 956 970 pikseli (szerokość × wysokość).
Meshy naprowadza teksturę tylko na podstawie jednego z: texture_prompt lub texture_image_url. Jeśli wyślesz oba, Meshy użyje texture_prompt. Informacje o koszcie teksturowania w kredytach znajdziesz w Cennik.
Przy texture_model: meshy-n1, Meshy teksturuje na podstawie tego obrazu jako widoku z przodu, lub na podstawie obrazu wejściowego, jeśli go pominiesz.
Teksturowanie na podstawie obrazu może nie działać dobrze, gdy kształt obrazu znacznie różni się od geometrii modelu 3D.

Name
should_remesh
Type
boolean
domyślne true (meshy-6-lite), false (other models)
Description
Czy uruchomić fazę remesh. Aby uzyskać model 3D najwyższej jakości, ustaw false.

Dotyczy tylko gdy should_remesh = true

Name
topology
Type
string
domyślne triangle
Description
Typ ścianek modelu po remesh.
Dostępne wartości:
- quad: siatka z przewagą czworokątów
- triangle: zdecymowana siatka trójkątów
Wynik Smart Topology zawiera wyłącznie trójkąty, więc quad z meshy-t2 lub meshy-t2.5 zwraca 400. Przy texture_model: meshy-n1, quad zwraca 400, gdy model przechodzi remesh, co domyślnie robi meshy-6-lite.
Name
decimation_mode
Type
integer
Description
Adaptacyjna liczba ścianek, według poziomu. Gdy go ustawisz, Meshy ignoruje target_polycount.
Dostępne wartości:
- 1: ultra
- 2: wysoki
- 3: średni
- 4: niski
Name
save_pre_remeshed_model
Type
boolean
domyślne false
Description
Czy przechowywać również plik GLB modelu sprzed fazy remesh. Meshy zwraca go w model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Docelowa liczba ścianek. Wynik może różnić się od wartości docelowej, w zależności od geometrii modelu.
Ma zastosowanie w dwóch odrębnych przypadkach:
- Remesh: Gdy should_remesh ma wartość true dla modelu standard, Meshy decymuje siatkę do mniej więcej tej liczby. Jeśli ustawisz decimation_mode, Meshy użyje go i zignoruje target_polycount.
- Smart Topology: Gdy model_type to smart-topology, a ai_model to meshy-t2 lub meshy-t2.5, Meshy generuje model przy tej liczbie ścianek. Remesh nie jest wykonywany i should_remesh nie jest potrzebne.
Zakres i wartość domyślna zależą od 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.

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, ponieważ nie wpływa on na wynik. Jego wartości sterowały symetrią podczas generowania:
- off: brak symetrii
- auto: symetria dobrana na podstawie geometrii wejściowej
- on: wymuszona symetria
Name
pose_mode
Type
string
domyślne ""
Description
Poza wygenerowanego modelu.
Dostępne wartości:
- a-pose: poza A
- t-pose: poza T
- "" (pusty ciąg): brak konkretnej pozy
Name
is_a_t_pose
Type
boolean
⚠ przestarzałe
domyślne false
Description
Zamiast tego użyj pose_mode. Czy wygenerować model w pozie A lub T.
Name
surface_mode
Type
string
⚠ przestarzałe
Description
Zamiast tego użyj ai_model. Nie wpływa na wynik, ponieważ wybierany przez niego sposób generowania modelu jest wycofany.
Akceptowane wartości to organic i hard. Każda inna wartość zwraca 400.
Name
image_enhancement
Type
boolean
domyślne true
Description
Czy zoptymalizować obraz wejściowy przed generowaniem. false zachowuje dokładny wygląd obrazu wejściowego, bez przetwarzania stylu.
Działa tylko z meshy-6, meshy-7.1 lub latest. Przy meshy-6-lite lub model_type: smart-topology, zwraca 400.
Name
remove_lighting
Type
boolean
domyślne true
Description
Czy usunąć blaski i cienie z tekstury koloru bazowego. Wynik jest czystszy i lepiej sprawdza się pod własnym oświetleniem.
Działa tylko z modelem tekstur Meshy 6, a model tekstur, który go nie obsługuje, zwraca 400 dla true. Przy model_type: smart-topology, lub przy ai_model: meshy-6-lite i jego domyślnym modelu tekstur, wysłanie go zwraca 400.
Name
moderation
Type
boolean
domyślne false
Description
Czy przeskanować te dane wejściowe pod kątem szkodliwych treści przed generowaniem:
- image_url
- texture_image_url
- texture_prompt
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 formaty, które wymienisz, co może skrócić zadanie. Jeśli pominiesz ten parametr, Meshy generuje każdy format oprócz 3mf, który otrzymasz tylko, jeśli go wymienisz.
Dostępne wartości:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
domyślne false
Description
Czy oszacować rzeczywistą wysokość obiektu za pomocą wizji AI i dostosować do niej rozmiar modelu. Meshy umieszcza punkt początkowy na dole, chyba że ustawisz origin_at.
Name
alpha_thumbnail
Type
boolean
domyślne false
Description
Czy wygenerować również podgląd z przezroczystym tłem (RGBA), zwracany w alpha_thumbnail_url po pobraniu zadania. thumbnail_url nie ulega zmianie.
Name
multi_view_thumbnails
Type
boolean
domyślne false
Description
Czy wygenerować również podglądy z przodu, prawej strony, tyłu i lewej strony, zwracane w thumbnail_urls po pobraniu zadania. thumbnail_url nie ulega zmianie i nadal pokazuje widok z przodu. Wydłuża to zadanie o około 5 sekund.

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 identyfikator nowego zadania Obraz na 3D.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje, jaki problem został wykryty. Na przykład:
- Brak parametru: Nie wysłano ani image_url, ani input_task_id.
- Nieprawidłowe zadanie wejściowe: input_task_id nie jest zadaniem Tekst na obraz ani Obraz na obraz ze statusem SUCCEEDED, które wygenerowało dokładnie jeden obraz.
- Nieprawidłowy format obrazu: Obraz image_url nie jest plikiem JPG, JPEG, PNG ani WebP.
- Niedostępny adres URL: Meshy nie może pobrać obrazu image_url, ponieważ adres URL zwraca 404 lub przekracza limit czasu.
- Obraz zbyt duży: Obraz image_url lub texture_image_url przekracza 20 MB.
- Nieprawidłowy rozmiar obrazu: Obraz image_url lub texture_image_url ma bok krótszy niż 32 piksele lub więcej niż 178 956 970 pikseli (szerokość × wysokość).
- Nieprawidłowy Data URI: Ciąg base64 jest zniekształcony.
- Nieprawidłowa kombinacja parametrów: enable_pbr ma wartość true, a should_texture ma wartość false.
- Nieobsługiwany model dla Ultra: geometry_resolution ma wartość 2k lub 4k, z ai_model, który tego nie obsługuje.
- Nieobsługiwany model dla opcji obrazu: jedna z poniższych sytuacji:
  - image_enhancement wysłano z ai_model: "meshy-6-lite" lub model_type: "smart-topology".
  - remove_lighting wysłano z model_type: "smart-topology", lub z ai_model: "meshy-6-lite" i jego domyślnym modelem tekstur.
- Nieprawidłowy model tekstur: texture_model nie jest jedną z dostępnych wartości.
- Model tekstur niedostępny: texture_model ma wartość meshy-6 z ai_model innym niż meshy-6. Wyślij meshy-7, meshy-n1 lub meshy-6-lite, albo pomiń ten parametr.
- Nieobsługiwana opcja dla modelu tekstur: Żądanie wymaga od modelu tekstur opcji, której on nie obsługuje, na przykład enable_pbr: true z meshy-n1 lub tekstury 4k z meshy-6-lite. Zobacz Modele.
Popraw żądanie, a następnie wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Klucz API jest brakujący lub 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 konto osiągnęło limit kredytów. Sprawdź saldo kredytów, a następnie spróbuj ponownie.
- Plan darmowy: Utworzenie zadania wymaga płatnego planu. Uaktualnij 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
404 - Not Found
Description
input_task_id nie pasuje do żadnego z Twoich zadań. Sprawdź identyfikator zadania, a następnie wyślij żądanie ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Odczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

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

Pobierz zadanie Obraz na 3D

Zwraca zadanie Obraz na 3D na podstawie jego ID.

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": null,
  "consumed_credits": 30
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi tworzenia.

Zwraca

Obiekt zadania Obraz na 3D.

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

Usuwanie zadania Obraz na 3D

Trwale usuwa zadanie Obraz na 3D, łącznie z jego modelami i danymi. Nie możesz cofnąć usunięcia.

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 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 użyte 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 usunięcie go 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 w statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie zwraca jego kredytów.

Zwraca

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

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

Lista zadań Obraz na 3D

Zwraca listę Twoich 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": null,
    "consumed_credits": 30
  }
]

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ń Obraz na 3D.

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

Przesyłaj strumieniowo zadanie Obraz na 3D

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

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.
// 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",
  "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": null,
  "consumed_credits": 30
}

Parametry

Name
id
Type
path
Description
Identyfikator zadania z odpowiedzi tworzenia.

Zwraca

Strumień obiektów zadania Obraz na 3D jako zdarzeń 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 Obraz na 3D

Obiekt zadania Obraz na 3D opisuje jedno generowanie modelu 3D na podstawie obrazu. Zawiera status, postęp (progress) oraz pliki modelu, gdy zadanie zakończy się powodzeniem.

Właściwości

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
Identyfikator zadania. Traktuj go jako nieprzezroczysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, zawsze image-to-3d.
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, a nie pustego ciągu znaków.
- Name
  glb
  Type
  string
  Description
  Plik GLB.
- Name
  fbx
  Type
  string
  Description
  Plik FBX.
- Name
  obj
  Type
  string
  Description
  Plik OBJ.
- Name
  usdz
  Type
  string
  Description
  Plik USDZ.
- Name
  mtl
  Type
  string
  Description
  Plik MTL, zwracany razem z plikiem OBJ, gdy model ma tekstury.
- Name
  stl
  Type
  string
  Description
  Plik STL.
- Name
  3mf
  Type
  string
  Description
  Plik 3MF. Obecny tylko wtedy, gdy target_formats zawiera 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Plik GLB sprzed operacji remesh. Obecny 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
Adres URL do pobrania obrazu podglądu modelu 3D. Gdy obecne jest thumbnail_urls, jest to ten sam obraz co thumbnail_urls.front. Meshy zachowuje to pole dla zachowania kompatybilności wstecznej.
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
thumbnail_urls
Type
object
Description
Adresy URL do pobrania podglądów modelu 3D z czterech stron. Każda wartość to podpisany adres URL do obrazu PNG 512×512, wyrenderowanego z tymi samymi materiałami i oświetleniem co thumbnail_url. Użyj ich do podglądu modelu z kilku kątów, na przykład w potoku wsadowym (batch), bez konieczności pobierania pliku GLB.
Obecne tylko wtedy, gdy zadanie zostało utworzone z multi_view_thumbnails: true, a zadanie osiągnęło status SUCCEEDED. Zadania utworzone bez multi_view_thumbnails: true nie zawierają tego pola.
- Name
  front
  Type
  string
  Description
  Widok z przodu, pod kątem 0° wokół osi pionowej. Odpowiada thumbnail_url.
- Name
  right
  Type
  string
  Description
  Widok z prawej strony, pod kątem 90°.
- Name
  back
  Type
  string
  Description
  Widok z tyłu, pod kątem 180°.
- Name
  left
  Type
  string
  Description
  Widok z lewej strony, pod kątem 270°.
Name
texture_prompt
Type
string
Description
Prompt tekstowy, który kierował teksturą.
Name
texture_image_url
Type
string
Description
Adres URL do pobrania obrazu, który kierował teksturą.
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, 2k lub 4k. Zadanie standard nie zawiera tego pola.
Name
progress
Type
integer
Description
Ile zadania zostało wykonane, w procentach. Wynosi 0 do momentu rozpoczęcia zadania i 100, gdy zakończy się powodzeniem.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach Unix. Wynosi 0 do momentu rozpoczęcia zadania.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach Unix.
Name
expires_at
Type
timestamp
Description
Czas wygaśnięcia wyniku zadania, w milisekundach Unix.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach Unix. Wynosi 0 do momentu zakończenia zadania.
Name
status
Type
string
Description
Status zadania, jeden z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
texture_urls
Type
array
Description
Mapy tekstur wygenerowane przez zadanie, jako tablica obiektów. Zazwyczaj zawiera jeden obiekt, z następującymi polami:
- Name
  base_color
  Type
  string
  Description
  Adres URL do pobrania mapy koloru podstawowego.
- Name
  metallic
  Type
  string
  Description
  Adres URL do pobrania mapy metaliczności. Pole jest nieobecne, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Adres URL do pobrania mapy normalnych. Pole jest nieobecne, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Adres URL do pobrania mapy chropowatości. Pole jest nieobecne, gdy zadanie zostało utworzone z enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Adres URL do pobrania mapy emisji. Meshy dołącza ją tylko wtedy, gdy zadanie zostało utworzone ze wszystkimi poniższymi warunkami:
  
  ai_model: meshy-6, z domyślnym modelem tekstury
  
  enable_pbr: true
  
  texture_resolution ustawioną na 2k lub 4k
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym w kolejce. Wartość 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. Wynosi null, chyba że status to FAILED. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie. Obecne, gdy status to PENDING, IN_PROGRESS lub SUCCEEDED. Wynosi 0 dla zadania FAILED, ponieważ Meshy zwraca kredyty, gdy zadanie kończy się niepowodzeniem.