Jak používat Image to 3D Model API: Kompletní průvodce 2026

API Image to 3D Model API promění jednu fotografii na produkčně připravený 3D model během několika sekund – bez nutnosti ručního modelování. Ruční modelování každého assetu je pomalé a nákladné a pro herní studia, AR aplikace a e‑commerce týmy se rychle stává úzkým hrdlem, které zpožďuje uvedení na trh. Meshy API pro převod obrázku na 3D model toto tření odstraňuje: pošlete obrázek, převede se na 3D model během sekund a stáhnete plně texturovanou síť ve formátech jako GLB, FBX a OBJ. Tento průvodce vás provede celým pracovním postupem – od vytvoření API klíče až po stažení prvního modelu – s kódem, který můžete zkopírovat a spustit během několika minut.

Co je Image to 3D Model API?

Ve svém jádru je Image to 3D Model API REST endpoint poháněný umělou inteligencí Meshy pro převod obrázku na 3D model. Pošlete jeden obrázek (JPG, JPEG nebo PNG) jako veřejnou URL nebo base64 řetězec a API vrátí texturovaný 3D model – včetně geometrie a základní barevné textury – ve standardních formátech jako GLB, FBX, OBJ, USDZ, STL a 3MF. Volitelné doplňky zahrnují PBR mapy, textury až do 4K a náhledové miniatury z více úhlů.

API poháněné naším nejnovějším modelem Meshy 6 umožňuje konfigurovat topologii a počet polygonů, nastavit režimy póz a řídit texturování textovým promptem nebo referenčním obrázkem – ideální pro generování assetů pro hry, AR/VR, 3D tisk a vizualizaci produktů.

Co potřebujete k použití Image to 3D API?

K následování tohoto průvodce nepotřebujete mnoho. Ujistěte se, že máte:

• Meshy účet – zaregistrujte se zdarma pokud jej nemáte. Svůj API klíč vygenerujete z dashboardu v Kroku 1.

• API klíč – používá se k autentizaci každého požadavku. Projdeme si vytvoření jednoho a můžete použít bezplatný testovací klíč k následování bez utrácení kreditů.

• Vstupní obrázek – čistý .jpg, .jpeg nebo .png hostovaný na veřejně přístupné URL (nebo zakódovaný jako base64). Čisté pozadí a jasně viditelný objekt poskytují nejlepší výsledky.

• Způsob provádění HTTP požadavků – curl (použitý v příkladech níže), Postman nebo jakákoli HTTP knihovna ve vámi zvoleném jazyce. Základní znalost REST API a JSON je užitečná, ale není vyžadována.

To je vše – není potřeba žádná zkušenost s 3D modelováním. Pojďme začít.

Jak převést obrázek na 3D model pomocí API (podrobný průvodce)

Krok 1: Nastavení API

Vše, co potřebujete k zahájení tvorby, najdete na stránce nastavení API. Toto je vaše řídicí centrum pro Meshy API a má tři klíčové sekce:

• API klíče – generujte a spravujte klíče, které autentizují vaše požadavky.

• Webhooky – nechte se automaticky upozornit, když vaše úkoly skončí.

• Využití – sledujte svůj zbývající kreditní zůstatek a spotřebu API v reálném čase.

Pojďme si každou projít.

Získejte svůj API klíč

Než začnete provádět jakékoli požadavky, potřebujete API klíč k bezpečné autentizaci. Na stránce nastavení API klikněte na Generovat API klíč. Každý klíč má formát msy-<náhodný-řetězec>.

Tip: Po vygenerování uložte svůj API klíč na bezpečné místo (např. správce hesel nebo proměnnou prostředí). Zacházejte s ním jako s heslem – nikdy jej neukládejte do správy zdrojového kódu ani nevystavujte v klientském kódu.

Testovací API klíč

Během vývoje a testování můžete použít testovací API klíč k prozkoumání API bez spotřebovávání vašich kreditů:

msy_dummy_api_key_for_test_mode_12345678

Tento speciální klíč má následující vlastnosti:

• Lze jej použít k provádění požadavků na všechny Meshy API endpointy.

• Při použití tohoto klíče nejsou spotřebovávány žádné kredity.

• Všechny platné požadavky vracejí stejný vzorový výsledek úkolu, bez ohledu na vstupní parametry.

• Struktura dat odpovědi odpovídá přesně produkčnímu API.

Díky tomu je ideální pro testování vaší integrace před přepnutím na váš skutečný API klíč.

Nastavení webhooků (volitelné)

Generování 3D modelu chvíli trvá, takže místo opakovaného dotazování API na stav úkolu můžete nechat Meshy, aby vás upozornilo v okamžiku, kdy je hotovo. K tomu slouží webhooky.

V sekci Webhooky na stránce nastavení přidejte URL endpointu, na který má Meshy posílat oznámení o událostech. Když úkol změní stav (například když se dokončí nebo selže), Meshy odešle HTTP POST požadavek na vaši URL s podrobnostmi o úkolu v těle zprávy.

Tip: Webhooky jsou doporučeným přístupem pro produkci. Snižují zbytečná API volání a umožňují vaší aplikaci reagovat na výsledky v reálném čase. Pro rychlé testy stále funguje dotazování. Chcete-li otestovat kód webhooku lokálně, nasměrujte jej na proxy URL ze služby jako smee.io.

Vyzkoušejte to bez kódu – API Playground (volitelné)

Už máte svůj API klíč? Než začnete psát kód, můžete spustit skutečný úkol Image to 3D přímo ve svém prohlížeči.

Otevřete meshy.ai/api-playground, vyberte Image to 3D z levého panelu a vyplňte tři věci:

1. Authorization – vložte svůj API klíč (msy-xxxxxxxxxx)

2. Image – nahrajte .jpg, .jpeg nebo .png ze svého počítače

3. Klikněte na Send

Playground odešle úkol a automaticky dotazuje výsledky. Jakmile je hotovo, uvidíte náhled 3D modelu a odkazy ke stažení přímo v prohlížeči – bez nutnosti kódu.

Pro tip: Panel s nezpracovaným požadavkem/odpovědí napravo ukazuje přesně, co API odesílá a vrací. Obsah můžete přímo zkopírovat – vezměte task_id z odpovědi a model_urls, jakmile úkol skončí. Obojí použijete v dalších krocích.

Krok 2: Odeslání úkolu Image to 3D

S připraveným API klíčem spusťte úkol jediným POST požadavkem:

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

Dostanete zpět odpověď jako tato:

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

Hodnota result je vaše task_id – uložte si ji. Budete ji potřebovat v dalším kroku ke kontrole průběhu a získání modelu.

Volitelné: Chcete-li být automaticky upozorněni, když úkol skončí, přidejte do JSON těla pole webhook_url – například "webhook_url": "https://yourapp.com/webhooks/meshy". Jak to funguje, viz Krok 3, Možnost B.

Krok 3: Získání výsledků

Váš úkol není dokončen okamžitě – Meshy jej zpracovává na pozadí. Máte dva způsoby, jak získat výsledek:

Možnost A: Dotazování na stav (nejjednodušší)

Odesílejte GET požadavek každých 5 sekund, dokud se status nezmění na SUCCEEDED:

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

Odpověď vypadá takto:

{
  "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
}

Několik polí, která stojí za to znát:

• model_urls obsahuje odkaz ke stažení pro každý vygenerovaný formát. Ve výchozím nastavení to zahrnuje glb, fbx, obj, usdz, stl a mtl (soubor materiálu, který se páruje s obj).

• model_url je zkratka na GLB odkaz – užitečné, když potřebujete pouze GLB.

• consumed_credits ukazuje, kolik kreditů úkol spotřeboval (u neúspěšných úkolů je 0, protože kredity jsou vráceny).

• thumbnail_url je vždy přítomen a ukazuje na miniaturu z předního pohledu.

• thumbnail_urls se objeví pouze když multi_view_thumbnails: true a obsahuje pohledy zepředu, zprava, zezadu a zleva.

• alpha_thumbnail_url se objeví pouze když alpha_thumbnail: true a obsahuje miniaturu s průhledným pozadím.

Možné hodnoty status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Možnost B: Webhook (doporučeno pro produkci)

Pokud jste v Kroku 2 nastavili webhook_url, Meshy automaticky odešle POST s dokončeným objektem úkolu na vaši URL – není potřeba dotazování.

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

💡 Který mám použít? Dotazování je vhodné pro prototypování a jednorázové úkoly. V produkci používejte webhooky – je to spolehlivější a šetří API volání.

Krok 4: Stažení 3D modelu

Jakmile je status SUCCEEDED, vezměte URL pro stažení z model_urls a stáhněte požadovaný formát:

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

Příznak -o model.glb uloží soubor do vašeho aktuálního pracovního adresáře pod tímto názvem – použijte úplnou cestu (např. -o /cesta/k/model.glb) pro uložení jinam.

Ve výchozím nastavení každý úkol vrací GLB, FBX, OBJ, USDZ, STL a MTL (soubor materiálu pro OBJ). 3MF je volitelný – získáte jej pouze tehdy, když jej explicitně požadujete pomocí target_formats (viz tabulka parametrů níže).

⚠️ Odkazy vyprší za 3 dny (Enterprise plány mají trvalé odkazy). Stáhněte a uložte své modely včas – odkazy po vypršení nebudou fungovat a budete muset úkol spustit znovu.

Jste připraveni použít tento model ve svém DCC nástroji? Podívejte se na průvodce Bridge to Blender – Meshy má také mosty pro Unity, Unreal, Maya a další.

Jak dosáhnout nejlepších výsledků převodu obrázku na 3D?

• Použijte jeden, jasně viditelný objekt. Jeden hlavní objekt, vycentrovaný a plně v záběru, poskytuje AI nejčistší referenci – vyhněte se rušným scénám, silnému ořezu a extrémním úhlům.

• Preferujte čisté, nezaplněné pozadí. Pevné nebo jednoduché pozadí pomáhá modelu oddělit objekt od okolí.

• Použijte rovnoměrné, difúzní osvětlení. Tvrdé stíny a silné odlesky mohou do vygenerované textury vnést zavádějící detaily.

• Začněte s vysoce rozlišeným, ostrým obrázkem. Více detailů na vstupu znamená více detailů na výstupu – rozmazané nebo nízkorozlišené vstupy produkují měkčí modely.

Které programovací jazyky mohu použít s Image to 3D API?

Jakýkoli jazyk, který umí provádět HTTP požadavky – pošlete POST s JSON a dotazujte se pomocí GET. Běžné možnosti:

• Python – použijte knihovnu requests nebo httpx

• JavaScript / TypeScript – použijte fetch (vestavěný) nebo axios

• Go – použijte net/http ze standardní knihovny

• cURL – skvělé pro rychlé testování z terminálu

Ukázky kódu připravené ke kopírování pro všechny čtyři najdete také v API Playground.

Kolik kreditů stojí úkol Image to 3D?

Cena závisí na verzi modelu a na tom, zda generujete textury. Výchozí nastavení (meshy-6 s texturováním) stojí 30 kreditů za úkol:

Neúspěšné úkoly jsou automaticky vráceny – consumed_credits vrací 0. Aktuální sazby vždy zkontrolujte na Ceníku.

Jaké parametry přijímá Image to 3D API?

Pošlete POST na /openapi/v1/image-to-3d s těmito parametry: Povinné (jeden z):

Volitelné:

Další kroky s Image to 3D API

Nyní máte kompletní pracovní postup: vytvořte API klíč, odešlete obrázek, dotazujte se nebo použijte webhook pro výsledek, poté stáhněte svůj model. Stejné čtyři kroky se škálují od rychlého prototypu až po produkční pipeline, která automaticky převádí tisíce obrázků na 3D assety. Získejte svůj klíč na stránce nastavení API a nasaďte svůj první model ještě dnes. Preferujete začít s promptem místo fotografie? Použijte Text to 3D Model API.

Často kladené otázky

Jak převedu obrázek na 3D model pomocí API?

Pošlete POST požadavek na /openapi/v1/image-to-3d s vaším image_url a API klíčem, poté dotazujte úkol (nebo použijte webhook), dokud jeho status není SUCCEEDED. Odpověď vrátí odkazy ke stažení vygenerovaného modelu. Celý čtyřkrokový tok – klíč, odeslání, získání, stažení – je popsán v podrobném průvodci výše.

Jaké výstupní formáty (STL, GLB, OBJ) API podporuje?

Každý úkol ve výchozím nastavení vrací GLB, FBX, OBJ, USDZ, STL a MTL, přičemž 3MF je k dispozici na vyžádání pomocí target_formats. GLB je nejlepší pro web a AR, FBX a OBJ pro DCC nástroje a herní enginy, USDZ pro iOS AR a STL pro 3D tisk.

Jaké formáty obrázků mohu nahrát?

Image to 3D API podporuje obrázky JPG, JPEG a PNG do velikosti 100 MB – větší než limit 20 MB v uživatelském rozhraní Meshy Workspace. Pro nejpřesnější výsledky použijte PNG s průhledným nebo čistým bílým pozadím, což pomáhá API izolovat objekt a vygenerovat kvalitnější 3D model.

Mohu z API získat texturovaný 3D model?

Ano. Texturování je ve výchozím nastavení povoleno ("should_texture": true). Chcete-li přidat PBR mapy (kovovost, drsnost, normála), nastavte "enable_pbr": true – na meshy-6/latest to také zahrnuje emisní mapu. Pro 4K základní barevnou texturu nastavte "hd_texture": true (podporováno pouze na meshy-6/latest; PBR mapy zůstávají ve 2K). Styl textury můžete také řídit pomocí texture_prompt nebo texture_image_url.

Mohu vygenerovat 3D model připravený pro 3D tisk (STL)?

Ano – STL je generován ve výchozím nastavení, takže převod obrázku na 3D STL nevyžaduje žádné další parametry: stačí vzít model_urls.stl, když úkol skončí. To zjednodušuje pracovní postupy pro 3D tisk, protože STL je standardní formát, který slicery očekávají. Pokud chcete pouze STL, nastavte "target_formats": ["stl"], čímž přeskočíte ostatní formáty a zkrátíte dobu generování.

Které plány zahrnují přístup k API?

Přístup k API je k dispozici v plánech Pro, Studio a Enterprise – jedná se o funkci od Pro výše. Bezplatný plán Starter přístup k API nezahrnuje. Podrobnosti najdete na Ceníku.

Jak dlouho jsou odkazy ke stažení platné?

Odkazy ke stažení jsou platné 3 dny u plánů Pro a Studio. Zákazníci Enterprise mají trvalé odkazy. Ukládejte své soubory včas – prošlé odkazy nelze obnovit a budete muset úkol spustit znovu.

Mohu spouštět více úkolů současně?

Ano, souběžné požadavky jsou podporovány. Pokud narazíte na chybu 429 Too Many Requests, váš účet dosáhl svého limitu rychlosti – implementujte exponenciální backoff a opakování. Na stránce Rate Limits najdete limity pro váš plán.

Úkol zobrazuje FAILED – co mám dělat?

Zkontrolujte task_error.message pro příčinu. Běžné chyby:

Pokud problém přetrvává, kontaktujte podporu Meshy.