Image to 3D Model API Kullanımı: 2026 Kapsamlı Rehberi

Image to 3D Model API, tek bir fotoğrafı saniyeler içinde üretime hazır bir 3D modele dönüştürür—manuel modelleme gerektirmez. Her varlığı elle modellemek yavaş ve maliyetlidir; oyun stüdyoları, AR uygulamaları ve e-ticaret ekipleri için bu durum hızla lansmanları geciktiren bir darboğaz haline gelir. Meshy'nin görüntüden 3D modele API'si bu sürtüşmeyi ortadan kaldırır: bir görsel gönderin, saniyeler içinde 3D modele dönüştürün ve GLB, FBX ve OBJ gibi formatlarda tamamen dokulu bir ağ indirin. Bu kılavuz, API anahtarınızı oluşturmaktan ilk modelinizi indirmeye kadar tüm iş akışını, dakikalar içinde çalıştırabileceğiniz kopyala-yapıştır kodlarla adım adım anlatır.

Image to 3D Model API Nedir?

Özünde, Image to 3D Model API, Meshy'nin görüntüden 3D model yapay zekası tarafından desteklenen bir REST uç noktasıdır. Tek bir görseli (JPG, JPEG veya PNG) herkese açık bir URL veya base64 dizesi olarak gönderirsiniz ve API, GLB, FBX, OBJ, USDZ, STL ve 3MF gibi standart formatlarda geometri ve temel renk dokularını içeren dokulu bir 3D model döndürür. İsteğe bağlı eklentiler arasında PBR haritaları, 4K'ya kadar dokular ve çok açılı önizleme k��çük resimleri bulunur.

En yeni Meshy 6 modelimiz tarafından desteklenen API, topoloji ve çokgen sayılarını yapılandırmanıza, poz modlarını ayarlamanıza ve bir metin istemi veya referans görseli ile dokulandırmayı yönlendirmenize olanak tanır—oyunlar, AR/VR, 3D baskı ve ürün görselleştirme için varlıklar üretmek için idealdir.

Image to 3D API'sini Kullanmak İçin Neye İhtiyacınız Var?

Bu kılavuzu takip etmek için fazla bir şeye ihtiyacınız yok. Aşağıdakilere sahip olduğunuzdan emin olun:

• Bir Meshy hesabı — hesabınız yoksa ücretsiz kaydolun. API anahtarınızı 1. Adımda kontrol panelinden oluşturacaksınız.

• Bir API anahtarı — her isteğin kimliğini doğrulamak için kullanılır. Bir tane oluşturmayı adım adım göstereceğiz ve kredi harcamadan takip etmek için ücretsiz test modu anahtarını kullanabilirsiniz.

• Bir giriş görseli — herkese açık bir URL'de barındırılan (veya base64 olarak kodlanmış) net bir .jpg, .jpeg veya .png dosyası. Temiz bir arka plan ve açıkça görülebilen bir konu en iyi sonuçları verir.

• HTTP istekleri yapmanın bir yolu — curl (aşağıdaki örneklerde kullanılmıştır), Postman veya tercih ettiğiniz dildeki herhangi bir HTTP kütüphanesi. REST API'leri ve JSON hakkında temel bilgi yardımcı olur ancak gerekli değildir.

Bu kadar—3D modelleme deneyimi gerekmez. Hadi başlayalım.

API ile Görselden 3D Modele Dönüştürme (Adım Adım Kılavuz)

Adım 1: API Ayarlarınızı Yapın

Oluşturmaya başlamak için ihtiyacınız olan her şey API ayarları sayfasında bulunur. Burası Meshy API'si için kontrol merkezinizdir ve üç ana bölümü vardır:

• API Anahtarları — isteklerinizin kimliğini doğrulayan anahtarları oluşturun ve yönetin.

• Webhook'lar — görevleriniz bittiğinde otomatik olarak bildirim alın.

• Kullanım — kalan kredi bakiyenizi ve API tüketiminizi gerçek zamanlı olarak takip edin.

Her birini inceleyelim.

API Anahtarınızı Alın

Herhangi bir istek yapmadan önce, güvenli bir şekilde kimlik doğrulaması için bir API anahtarına ihtiyacınız vardır. API ayarları sayfasında API Anahtarı Oluştur'a tıklayın. Her anahtar msy-<rastgele-dize> formatını takip eder.

İpucu: Oluşturulduktan sonra API anahtarınızı güvenli bir yerde (ör. bir parola yöneticisi veya ortam değişkeni) saklayın. Ona bir parola gibi davranın—asla kaynak kontrolüne eklemeyin veya istemci tarafı kodunda açığa çıkarmayın.

Test Modu API Anahtarı

Geliştirme ve test sırasında, kredilerinizi tüketmeden API'yi keşfetmek için test modu API anahtarını kullanabilirsiniz:

msy_dummy_api_key_for_test_mode_12345678

Bu özel anahtar aşağıdaki özelliklere sahiptir:

• Tüm Meshy API uç noktalarına istek yapmak için kullanılabilir.

• Bu anahtarı kullanırken hiçbir kredi tüketilmez.

• Geçerli tüm istekler, giriş parametrelerinden bağımsız olarak aynı örnek görev sonucunu döndürür.

• Yanıt veri yapısı üretim API'siyle tamamen aynıdır.

Bu, gerçek API anahtarınıza geçmeden önce entegrasyonunuzu test etmek için mükemmeldir.

Webhook'ları Ayarlayın (İsteğe Bağlı)

Bir 3D model oluşturmak zaman alır, bu nedenle bir görevin bitip bitmediğini kontrol etmek için API'yi tekrar tekrar sorgulamak yerine, Meshy'nin işlem bittiğinde sizi anında bilgilendirmesine izin verebilirsiniz. Webhook'lar tam olarak bunun içindir.

Ayarlar sayfasındaki Webhook'lar bölümünde, Meshy'nin olay bildirimleri göndermesi gereken bir uç nokta URL'si ekleyin. Bir görev durum değiştirdiğinde (örneğin, tamamlandığında veya başarısız olduğunda), Meshy, yükünde görev ayrıntılarıyla birlikte URL'nize bir HTTP POST isteği gönderir.

İpucu: Webhook'lar üretim için önerilen yaklaşımdır. Gereksiz API çağrılarını azaltır ve uygulamanızın sonuçlara gerçek zamanlı olarak tepki vermesini sağlar. Hızlı testler için sorgulama yine de iyi çalışır. Webhook kodunu yerel olarak test etmek için smee.io gibi bir hizmetten bir proxy URL'sine yönlendirin.

Kod Olmadan Deneyin — API Oyun Alanı (İsteğe Bağlı)

Zaten API Anahtarınız var mı? Herhangi bir kod yazmadan önce, doğrudan tarayıcınızda gerçek bir Görselden 3D'ye görevi çalıştırabilirsiniz.

meshy.ai/api-playground adresini açın, sol panelden Image to 3D'yi seçin ve üç şeyi doldurun:

1. Authorization — API Anahtarınızı yapıştırın (msy-xxxxxxxxxx)

2. Image — bilgisayarınızdan bir .jpg, .jpeg veya .png dosyası yükleyin

3. Send'e basın

Oyun Alanı görevi gönderir ve sonuçları otomatik olarak sorgular. İşlem bittiğinde, 3D model önizlemesini ve indirme bağlantılarını doğrudan tarayıcıda göreceksiniz—kod gerekmez.

Profesyonel ipucu: Sağdaki ham istek/yanıt paneli, API'nin tam olarak ne gönderip döndürdüğünü gösterir. İçeriği doğrudan kopyalayabilirsiniz—yanıttan task_id'yi ve görev bittiğinde model_urls'i alın. Sonraki adımlarda her ikisini de kullanacaksınız.

Adım 2: Bir Görselden 3D'ye Görev Gönderin

API anahtarınız hazır olduğunda, tek bir POST isteği ile bir görev başlatın:

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

Bunun gibi bir yanıt alacaksınız:

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

Bu result değeri sizin task_id'nizdir—kaydedin. İlerlemesini kontrol etmek ve modelinizi almak için sonraki adımda buna ihtiyacınız olacak.

İsteğe bağlı: Görev bittiğinde otomatik olarak bildirim almak için JSON gövdesine bir webhook_url alanı ekleyin—örneğin "webhook_url": "https://yourapp.com/webhooks/meshy". Nasıl çalıştığı için 3. Adım, Seçenek B'ye bakın.

Adım 3: Sonuçlarınızı Alın

Göreviniz anında bitmez—Meshy onu arka planda işler. Sonucu almak için iki yolunuz vardır:

Seçenek A: Durumu Sorgulayın (En Basiti)

status SUCCEEDED olana kadar her 5 saniyede bir GET isteği gönderin:

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

Yanıt şöyle görünür:

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

Bilmeniz gereken birkaç alan:

• model_urls, oluşturulan her format için bir indirme bağlantısı içerir. Varsayılan olarak bu, glb, fbx, obj, usdz, stl ve mtl'yi ( obj ile eşleşen malzeme dosyası) içerir.

• model_url, yalnızca GLB'ye ihtiyacınız olduğunda kullanışlı olan GLB bağlantısına bir kısayoldur.

• consumed_credits, görevin kaç kredi kullandığını gösterir (başarısız görevler için 0'dır, çünkü krediler iade edilir).

• thumbnail_url her zaman mevcuttur ve önden görünüm küçük resmini işaret eder.

• thumbnail_urls yalnızca multi_view_thumbnails: true olduğunda görünür ve ön, sağ, arka ve sol görünümleri içerir.

• alpha_thumbnail_url yalnızca alpha_thumbnail: true olduğunda görünür ve şeffaf arka planlı küçük resmi tutar.

Olası status değerleri: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Seçenek B: Webhook (Üretim İçin Önerilir)

2. Adımda bir webhook_url ayarladıysanız, Meshy tamamlanan görev nesnesini otomatik olarak URL'nize POST'layacaktır—sorgulamaya gerek yok.

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

💡 Hangisini kullanmalıyım? Sorgulama, prototip oluşturma ve tek seferlik görevler için uygundur. Üretimde webhook'ları kullanın—daha güvenilirdir ve API çağrılarından tasarruf sağlar.

Adım 4: 3D Modelinizi İndirin

status SUCCEEDED olduğunda, model_urls'den indirme URL'lerini alın ve ihtiyacınız olan formatı indirin:

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

-o model.glb bayrağı dosyayı geçerli çalışma dizininize bu adla kaydeder—başka bir yere kaydetmek için tam bir yol kullanın (ör. -o /path/to/model.glb).

Varsayılan olarak, her görev GLB, FBX, OBJ, USDZ, STL ve MTL (OBJ için malzeme dosyası) döndürür. 3MF isteğe bağlıdır—yalnızca target_formats aracılığıyla açıkça talep ettiğinizde alırsınız (aşağıdaki parametre tablosuna bakın).

⚠️ Bağlantılar 3 gün içinde sona erer (Kurumsal planlar kalıcı bağlantılar alır). Modellerinizi hemen indirin ve saklayın—bağlantılar süresi dolduktan sonra çalışmaz ve görevi yeniden çalıştırmanız gerekir.

Bu modeli DCC aracınızda kullanmaya hazır mısınız? Bridge to Blender kılavuzuna bakın—Meshy'nin ayrıca Unity, Unreal, Maya ve daha fazlası için köprüleri vardır.

En iyi görüntüden 3D'ye sonuçları nasıl alınır?

• Tek, net bir şekilde görülebilen bir konu kullanın. Ortalanmış ve tamamen çerçeve içinde olan tek bir ana nesne, yapay zekaya en temiz referansı verir—karmaşık sahnelerden, ağır kırpmalardan ve aşırı açılardan kaçının.

• Temiz, dağınık olmayan bir arka plan tercih edin. Düz veya basit arka planlar, modelin konuyu çevresinden ayırmasına yardımcı olur.

• Eşit, dağınık aydınlatma kullanın. Sert gölgeler ve güçlü vurgular, oluşturulan dokuya yanıltıcı ayrıntılar ekleyebilir.

• Yüksek çözünürlüklü, keskin bir görüntü ile başlayın. Giren ne kadar ayrıntılıysa çıkan da o kadar ayrıntılı olur—bulanık veya düşük çözünürlüklü girdiler daha yumuşak modeller üretir.

Image to 3D API ile hangi programlama dillerini kullanabilirim?

HTTP isteği yapabilen herhangi bir dil—JSON ile bir POST gönderir ve GET ile sorgularsınız. Yaygın seçenekler:

• Python — requests veya httpx kütüphanesini kullanın

• JavaScript / TypeScript — fetch (yerleşik) veya axios kullanın

• Go — standart kütüphaneden net/http kullanın

• cURL — terminalden hızlı testler için harika

Dördü için de kopyalamaya hazır kod örneklerini API Oyun Alanı'nda bulabilirsiniz.

Bir Image to 3D görevinin maliyeti kaç kredidir?

Maliyet, model sürümüne ve doku oluşturup oluşturmadığınıza bağlıdır. Varsayılan kurulum (meshy-6 dokulu) görev başına 30 kredi tutarındadır:

Başarısız görevler otomatik olarak iade edilir—consumed_credits 0 döndürür. En güncel oranlar için her zaman Fiyatlandırma sayfasını kontrol edin.

Image to 3D API hangi parametreleri kabul eder?

/openapi/v1/image-to-3d adresine bu parametrelerle bir POST gönderin: Gerekli (biri):

İsteğe bağlı:

Image to 3D API ile Sonraki Adımlar

Artık tam iş akışına sahipsiniz: bir API anahtarı oluşturun, bir görsel gönderin, sonuç için sorgulayın veya bir webhook kullanın, ardından modelinizi indirin. Aynı dört adım, hızlı bir prototipten binlerce görseli otomatik olarak 3D varlıklara dönüştüren bir üretim hattına kadar ölçeklenir. Anahtarınızı API ayarları sayfasından alın ve ilk modelinizi bugün gönderin. Bir fotoğraf yerine bir istemle başlamayı mı tercih edersiniz? Text to 3D Model API'sini kullanın.

Sıkça Sorulan Sorular

API aracılığıyla bir görseli 3D modele nasıl dönüştürebilirim?

image_url ve API anahtarınızla /openapi/v1/image-to-3d adresine bir POST isteği gönderin, ardından status SUCCEEDED olana kadar görevi sorgulayın (veya bir webhook kullanın). Yanıt, oluşturulan model için indirme bağlantılarını döndürür. Dört adımlı tam akış—anahtar, gönderme, alma, indirme—yukarıdaki adım adım kılavuzda ele alınmıştır.

API hangi çıktı formatlarını (STL, GLB, OBJ) destekliyor?

Her görev varsayılan olarak GLB, FBX, OBJ, USDZ, STL ve MTL döndürür; 3MF ise target_formats aracılığıyla talep üzerine kullanılabilir. GLB web ve AR için, FBX ve OBJ DCC araçları ve oyun motorları için, USDZ iOS AR için ve STL 3D baskı için en iyisidir.

Hangi görsel formatlarını yükleyebilirim?

Image to 3D API, 100 MB'a kadar JPG, JPEG ve PNG görsellerini destekler—bu, Meshy Çalışma Alanı arayüzündeki 20 MB sınırından daha büyüktür. En doğru sonuçlar için, API'nin konuyu izole etmesine ve daha yüksek kaliteli bir 3D model oluşturmasına yardımcı olan şeffaf veya temiz beyaz arka planlı bir PNG kullanın.

API'den dokulu bir 3D model alabilir miyim?

Evet. Dokulandırma varsayılan olarak etkindir ("should_texture": true). PBR haritaları (metalik, pürüzlülük, normal) eklemek için "enable_pbr": true olarak ayarlayın—meshy-6/latest üzerinde bu ayrıca bir emisyon haritası da içerir. 4K temel renk dokusu için "hd_texture": true olarak ayarlayın (yalnızca meshy-6/latest üzerinde desteklenir; PBR haritaları 2K'da kalır). Ayrıca bir texture_prompt veya texture_image_url ile doku stilini yönlendirebilirsiniz.

3D baskıya hazır (STL) bir 3D model oluşturabilir miyim?

Evet—STL varsayılan olarak oluşturulur, bu nedenle bir görüntüden 3D STL dönüşümü ekstra parametre gerektirmez: görev tamamlandığında model_urls.stl'yi almanız yeterlidir. Bu, görüntüden 3D baskı iş akışlarını basit hale getirir çünkü STL, dilimleyicilerin beklediği standart formattır. Yalnızca STL istiyorsanız, diğer formatları atlamak ve oluşturma süresini kısaltmak için "target_formats": ["stl"] olarak ayarlayın.

Hangi planlar API erişimini içerir?

API erişimi Pro, Studio ve Enterprise planlarında mevcuttur—Pro ve üstü bir özelliktir. Ücretsiz Başlangıç planı API erişimini içermez. Ayrıntılar için Fiyatlandırma sayfasına bakın.

İndirme bağlantıları ne kadar süreyle geçerlidir?

İndirme bağlantıları Pro ve Studio planlarında 3 gün geçerlidir. Kurumsal müşteriler kalıcı bağlantılar alır. Dosyalarınızı hemen kaydedin—süresi dolan bağlantılar kurtarılamaz ve görevi yeniden çalıştırmanız gerekir.

Aynı anda birden fazla görev çalıştırabilir miyim?

Evet, eşzamanlı istekler desteklenir. Bir 429 Too Many Requests hatası alırsanız, hesabınız hız sınırına ulaşmıştır—üstel geri çekilme uygulayın ve yeniden deneyin. Planınızın sınırları için Hız Sınırları sayfasına bakın.

Görev BAŞARISIZ oldu — ne yapmalıyım?

Nedeni için task_error.message'i kontrol edin. Yaygın olanlar:

Sorun devam ederse Meshy desteğine başvurun.