Jak korzystać z Image to 3D Model API: Kompletny przewodnik 2026

API Obraz na model 3D zamienia pojedyncze zdjęcie w gotowy do produkcji model 3D w kilka sekund — bez ręcznego modelowania. Ręczne tworzenie każdego zasobu jest powolne i kosztowne, a dla studiów gier, aplikacji AR i zespołów e-commerce szybko staje się wąskim gardłem opóźniającym premiery. API obrazu na model 3D Meshy usuwa to tarcie: wyślij obraz, przekonwertuj go na model 3D w kilka sekund i pobierz w pełni teksturowaną siatkę w formatach takich jak GLB, FBX i OBJ. Ten przewodnik przeprowadzi Cię przez cały proces — od utworzenia klucza API po pobranie pierwszego modelu — z gotowym do skopiowania kodem, który uruchomisz w kilka minut.

Czym jest API Obraz na model 3D?

W swej istocie API Obraz na model 3D to endpoint REST oparty na sztucznej inteligencji Meshy do konwersji obrazu na model 3D. Wysyłasz pojedynczy obraz (JPG, JPEG lub PNG) jako publiczny URL lub ciąg base64, a API zwraca teksturowany model 3D — zawierający geometrię i tekstury koloru bazowego — w standardowych formatach, takich jak GLB, FBX, OBJ, USDZ, STL i 3MF. Opcjonalne dodatki obejmują mapy PBR, tekstury do 4K oraz miniatury podglądu z wielu kątów.

Działające na naszym najnowszym modelu Meshy 6, API pozwala konfigurować topologię i liczbę wielokątów, ustawiać tryby pozy oraz kierować teksturowaniem za pomocą podpowiedzi tekstowej lub obrazu referencyjnego — idealne do generowania zasobów do gier, AR/VR, druku 3D i wizualizacji produktów.

Czego potrzebujesz, aby korzystać z API Obraz na model 3D?

Nie potrzebujesz wiele, aby skorzystać z tego przewodnika. Upewnij się, że masz:

• Konto Meshy — zarejestruj się za darmo jeśli go nie masz. Wygenerujesz swój klucz API z panelu w Kroku 1.

• Klucz API — używany do uwierzytelniania każdego żądania. Przejdziemy przez proces jego tworzenia, a Ty możesz użyć darmowego klucza trybu testowego, aby śledzić przewodnik bez wydawania kredytów.

• Obraz wejściowy — wyraźny plik .jpg, .jpeg lub .png hostowany pod publicznie dostępnym adresem URL (lub zakodowany jako base64). Czyste tło i wyraźnie widoczny obiekt dają najlepsze rezultaty.

• Sposób na wykonywanie żądań HTTP — curl (używany w poniższych przykładach), Postman lub dowolna biblioteka HTTP w wybranym języku programowania. Podstawowa znajomość REST API i JSON jest pomocna, ale nie wymagana.

To wszystko — nie jest potrzebne doświadczenie w modelowaniu 3D. Zaczynajmy.

Jak przekonwertować obraz na model 3D za pomocą API (przewodnik krok po kroku)

Krok 1: Skonfiguruj ustawienia API

Wszystko, czego potrzebujesz, aby rozpocząć budowę, znajduje się na stronie ustawień API. To centrum sterowania API Meshy, które ma trzy kluczowe sekcje:

• Klucze API — generuj i zarządzaj kluczami uwierzytelniającymi Twoje żądania.

• Webhooki — otrzymuj automatyczne powiadomienia, gdy Twoje zadania się zakończą.

• Użycie — śledź w czasie rzeczywistym pozostały stan kredytów i zużycie API.

Omówmy każdą z nich.

Uzyskaj swój klucz API

Zanim zaczniesz wysyłać żądania, potrzebujesz klucza API do bezpiecznego uwierzytelniania. Na stronie ustawień API kliknij Generuj klucz API. Każdy klucz ma format msy-<losowy-ciąg>.

Wskazówka: Po wygenerowaniu przechowuj swój klucz API w bezpiecznym miejscu (np. menedżerze haseł lub zmiennej środowiskowej). Traktuj go jak hasło — nigdy nie umieszczaj go w systemie kontroli wersji ani nie ujawniaj w kodzie po stronie klienta.

Klucz API trybu testowego

Podczas programowania i testowania możesz użyć klucza API trybu testowego, aby eksplorować API bez zużywania swoich kredytów:

msy_dummy_api_key_for_test_mode_12345678

Ten specjalny klucz ma następujące cechy:

• Może być używany do wysyłania żądań do wszystkich endpointów API Meshy.

• Podczas korzystania z tego klucza nie są zużywane żadne kredyty.

• Wszystkie prawidłowe żądania zwracają ten sam przykładowy wynik zadania, niezależnie od parametrów wejściowych.

• Struktura danych odpowiedzi jest dokładnie taka sama jak w produkcyjnym API.

Dzięki temu jest idealny do testowania integracji przed przełączeniem na prawdziwy klucz API.

Skonfiguruj webhooki (opcjonalnie)

Generowanie modelu 3D zajmuje trochę czasu, więc zamiast wielokrotnie odpytować API, aby sprawdzić, czy zadanie zostało zakończone, możesz pozwolić Meshy powiadomić Cię w momencie jego zakończenia. Do tego służą webhooki.

W sekcji Webhooki na stronie ustawień dodaj adres URL endpointu, na który Meshy ma wysyłać powiadomienia o zdarzeniach. Gdy zadanie zmieni status (na przykład po zakończeniu lub niepowodzeniu), Meshy wysyła żądanie HTTP POST na Twój adres URL z danymi zadania w ładunku.

Wskazówka: Webhooki są zalecanym podejściem w produkcji. Zmniejszają liczbę niepotrzebnych wywołań API i pozwalają aplikacji reagować na wyniki w czasie rzeczywistym. Do szybkich testów odpytywanie również działa dobrze. Aby przetestować kod webhooka lokalnie, skieruj go na adres URL proxy z usługi takiej jak smee.io.

Wypróbuj bez kodu — API Playground (opcjonalnie)

Masz już swój klucz API? Zanim napiszesz jakikolwiek kod, możesz uruchomić prawdziwe zadanie Obraz na 3D bezpośrednio w przeglądarce.

Otwórz meshy.ai/api-playground, wybierz Image to 3D z lewego panelu i wypełnij trzy rzeczy:

1. Authorization — wklej swój klucz API (msy-xxxxxxxxxx)

2. Image — prześlij plik .jpg, .jpeg lub .png ze swojego komputera

3. Kliknij Send

Playground przesyła zadanie i automatycznie odpyta o wyniki. Po zakończeniu zobaczysz podgląd modelu 3D i linki do pobrania bezpośrednio w przeglądarce — bez potrzeby pisania kodu.

Pro tip: Panel surowego żądania/odpowiedzi po prawej stronie pokazuje dokładnie, co API wysyła i zwraca. Możesz skopiować zawartość bezpośrednio — pobierz task_id z odpowiedzi, a model_urls po zakończeniu zadania. Użyjesz obu w następnych krokach.

Krok 2: Prześlij zadanie Obraz na 3D

Mając gotowy klucz API, uruchom zadanie za pomocą pojedynczego żądania POST:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Otrzymasz odpowiedź podobną do tej:

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

Ta wartość result to Twój task_id — zapisz go. Będziesz go potrzebować w następnym kroku, aby sprawdzić postęp i pobrać model.

Opcjonalnie: Aby otrzymać automatyczne powiadomienie po zakończeniu zadania, dodaj pole webhook_url do treści JSON — na przykład "webhook_url": "https://yourapp.com/webhooks/meshy". Zobacz Krok 3, Opcja B, aby dowiedzieć się, jak to działa.

Krok 3: Uzyskaj wyniki

Twoje zadanie nie kończy się natychmiast — Meshy przetwarza je w tle. Masz dwa sposoby na uzyskanie wyniku:

Opcja A: Odpytywanie o status (najprostsze)

Wysyłaj żądanie GET co 5 sekund, aż status zmieni się na SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

Odpowiedź wygląda tak:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Kilka pól, które warto znać:

• model_urls zawiera link do pobrania dla każdego wygenerowanego formatu. Domyślnie obejmuje to glb, fbx, obj, usdz, stl i mtl (plik materiału sparowany z obj).

• model_url to skrót do linku GLB — przydatny, gdy potrzebujesz tylko GLB.

• consumed_credits pokazuje, ile kredytów zużyło zadanie (wynosi 0 dla nieudanych zadań, ponieważ kredyty są zwracane).

• thumbnail_url jest zawsze obecny i wskazuje na miniaturę z widoku z przodu.

• thumbnail_urls pojawia się tylko wtedy, gdy multi_view_thumbnails: true i zawiera widoki z przodu, prawej, tyłu i lewej strony.

• alpha_thumbnail_url pojawia się tylko wtedy, gdy alpha_thumbnail: true i zawiera miniaturę z przezroczystym tłem.

Możliwe wartości status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Opcja B: Webhook (zalecane w produkcji)

Jeśli ustawiłeś webhook_url w Kroku 2, Meshy automatycznie wyśle POST z ukończonym obiektem zadania na Twój adres URL — bez potrzeby odpytywania.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Którego użyć? Odpytywanie jest w porządku do prototypowania i jednorazowych zadań. Używaj webhooków w produkcji — są bardziej niezawodne i oszczędzają wywołania API.

Krok 4: Pobierz swój model 3D

Gdy status to SUCCEEDED, pobierz adresy URL do pobrania z model_urls i pobierz potrzebny format:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Flaga -o model.glb zapisuje plik w bieżącym katalogu roboczym pod tą nazwą — użyj pełnej ścieżki (np. -o /path/to/model.glb), aby zapisać go w innym miejscu.

Domyślnie każde zadanie zwraca GLB, FBX, OBJ, USDZ, STL i MTL (plik materiału dla OBJ). 3MF jest opcjonalny — otrzymujesz go tylko wtedy, gdy jawnie o niego poprosisz za pomocą target_formats (patrz tabela parametrów poniżej).

⚠️ Linki wygasają po 3 dniach (plany Enterprise otrzymują stałe linki). Pobierz i przechowuj swoje modele niezwłocznie — linki nie będą działać po wygaśnięciu, a zadanie będzie trzeba uruchomić ponownie.

Gotowy, aby użyć tego modelu w swoim narzędziu DCC? Zobacz przewodnik Bridge to Blender — Meshy ma również mosty do Unity, Unreal, Maya i innych.

Jak uzyskać najlepsze wyniki konwersji obrazu na 3D?

• Użyj pojedynczego, wyraźnie widocznego obiektu. Jeden główny obiekt, wyśrodkowany i w pełni w kadrze, daje AI najczystszą referencję — unikaj zagraconych scen, mocnego kadrowania i ekstremalnych kątów.

• Preferuj czyste, niezagracające tło. Jednolite lub proste tła pomagają modelowi oddzielić obiekt od otoczenia.

• Użyj równomiernego, rozproszonego oświetlenia. Ostre cienie i silne światła mogą utrwalić mylące szczegóły w wygenerowanej teksturze.

• Zacznij od wysokiej rozdzielczości, ostrego obrazu. Więcej szczegółów na wejściu oznacza więcej szczegółów na wyjściu — rozmyte lub niskiej rozdzielczości dane wejściowe dają bardziej miękkie modele.

Z jakich języków programowania mogę korzystać z API Obraz na model 3D?

Dowolny język, który może wykonywać żądania HTTP — wysyłasz POST z JSON i odpytać za pomocą GET. Typowe opcje:

• Python — użyj biblioteki requests lub httpx

• JavaScript / TypeScript — użyj fetch (wbudowane) lub axios

• Go — użyj net/http z biblioteki standardowej

• cURL — świetny do szybkich testów z terminala

Gotowe do skopiowania przykłady kodu dla wszystkich czterech znajdziesz również w API Playground.

Ile kredytów kosztuje zadanie Obraz na 3D?

Koszt zależy od wersji modelu i tego, czy generujesz tekstury. Domyślna konfiguracja (meshy-6 z teksturowaniem) kosztuje 30 kredytów za zadanie:

Nieudane zadania są automatycznie zwracane — consumed_credits zwraca 0. Zawsze sprawdzaj Cennik w celu uzyskania aktualnych stawek.

Jakie parametry akceptuje API Obraz na model 3D?

Wyślij POST do /openapi/v1/image-to-3d z tymi parametrami: Wymagane (jeden z):

Opcjonalne:

Następne kroki z API Obraz na model 3D

Masz teraz kompletny proces: utwórz klucz API, prześlij obraz, odpyta lub użyj webhooka, aby uzyskać wynik, a następnie pobierz model. Te same cztery kroki skalują się od szybkiego prototypu do produkcyjnego potoku, który automatycznie zamienia tysiące obrazów w zasoby 3D. Pobierz swój klucz ze strony ustawień API i wyślij swój pierwszy model już dziś. Wolisz zacząć od podpowiedzi zamiast zdjęcia? Użyj API Tekst na model 3D.

Często zadawane pytania

Jak przekonwertować obraz na model 3D za pomocą API?

Wyślij żądanie POST do /openapi/v1/image-to-3d ze swoim image_url i kluczem API, a następnie odpyta zadanie (lub użyj webhooka), aż jego status będzie SUCCEEDED. Odpowiedź zwraca linki do pobrania wygenerowanego modelu. Pełny czteroetapowy proces — klucz, przesłanie, pobranie, pobranie — został opisany w przewodniku krok po kroku powyżej.

Jakie formaty wyjściowe (STL, GLB, OBJ) obsługuje API?

Każde zadanie domyślnie zwraca GLB, FBX, OBJ, USDZ, STL i MTL, a 3MF jest dostępny na żądanie za pomocą target_formats. GLB jest najlepszy do sieci i AR, FBX i OBJ do narzędzi DCC i silników gier, USDZ do AR na iOS, a STL do druku 3D.

Jakie formaty obrazów mogę przesłać?

API Obraz na model 3D obsługuje obrazy JPG, JPEG i PNG o rozmiarze do 100 MB — większym niż limit 20 MB w interfejsie Meshy Workspace. Aby uzyskać najdokładniejsze wyniki, użyj PNG z przezroczystym lub czystym białym tłem, co pomaga API wyizolować obiekt i wygenerować wyższej jakości model 3D.

Czy mogę otrzymać teksturowany model 3D z API?

Tak. Teksturowanie jest domyślnie włączone ("should_texture": true). Aby dodać mapy PBR (metaliczność, chropowatość, normalne), ustaw "enable_pbr": true — na meshy-6/latest obejmuje to również mapę emisji. Aby uzyskać teksturę koloru bazowego w 4K, ustaw "hd_texture": true (obsługiwane tylko na meshy-6/latest; mapy PBR pozostają w 2K). Możesz również kierować stylem tekstury za pomocą texture_prompt lub texture_image_url.

Czy mogę wygenerować model 3D gotowy do druku 3D (STL)?

Tak — STL jest generowany domyślnie, więc konwersja obrazu na STL 3D nie wymaga dodatkowych parametrów: po prostu pobierz model_urls.stl po zakończeniu zadania. To sprawia, że procesy obrazu na wydruk 3D są proste, ponieważ STL jest standardowym formatem oczekiwanym przez slicery. Jeśli chcesz tylko STL, ustaw "target_formats": ["stl"], aby pominąć inne formaty i skrócić czas generowania.

Które plany obejmują dostęp do API?

Dostęp do API jest dostępny w planach Pro, Studio i Enterprise — to funkcja od planu Pro wzwyż. Darmowy plan Starter nie obejmuje dostępu do API. Szczegóły znajdziesz w Cenniku.

Jak długo ważne są linki do pobrania?

Linki do pobrania są ważne przez 3 dni w planach Pro i Studio. Klienci Enterprise otrzymują stałe linki. Zapisz swoje pliki niezwłocznie — wygasłe linki nie mogą zostać odzyskane, a zadanie będzie trzeba uruchomić ponownie.

Czy mogę uruchomić wiele zadań jednocześnie?

Tak, równoczesne żądania są obsługiwane. Jeśli otrzymasz błąd 429 Too Many Requests, Twoje konto osiągnęło limit szybkości — zastosuj wykładnicze opóźnienie i ponów próbę. Strona Limity szybkości zawiera limity dla Twojego planu.

Zadanie pokazuje FAILED — co robić?

Sprawdź task_error.message, aby znaleźć przyczynę. Typowe:

Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną Meshy.