Görselden 3D'ye API

Görselden 3D'ye API, Meshy'nin Görselden 3D'ye özelliklerini kendi uygulamanıza entegre etmenizi sağlayan bir özelliktir. Bu bölümde, bu API ile başlamak için ihtiyacınız olan tüm bilgileri bulacaksınız.

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

Görselden 3D'ye Görevi Oluşturma

Bu uç nokta, yeni bir Görselden 3D'ye görevi oluşturmanıza olanak tanır. Görselden 3D'ye görev nesnesine hangi özelliklerin dahil olduğunu görmek için Görselden 3D'ye Görev Nesnesi bölümüne bakın.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü öğrenmek için İşlem Süreleri bölümüne bakın.

Parametreler

input_task_id veya image_url değerlerinden yalnızca biri gereklidir. İkisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
Çıktısı giriş görseli olarak kullanılacak, tamamlanmış bir görsel oluşturma görevinin ID'si. Bu görev şu görevlerden biri olmalıdır: Metinden görsele veya Görselden görsele. Ayrıca, API üzerinden çalıştırılmış olmalı, durumu SUCCEEDED olmalı ve tam olarak bir görsel üretmiş olmalıdır.

Name
image_url
Type
string
Zorunlu
Description
Meshy'nin model oluşturmada kullanması için bir görsel sağlayın. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.
Maksimum dosya boyutu: 20 MB.
Görseli sağlamanın iki yolu vardır:
- Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL.
- Data URI: Görselin base64 ile kodlanmış bir data URI'si. Data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>.

Name
model_type
Type
string
varsayılan standard
Description
3D ağ oluşturma türünü belirtin.
Kullanılabilir değerler:
- standard: Normal yüksek detaylı 3D ağ oluşturma.
- smart-topology: ai_model (meshy-t2 veya meshy-t2.5) ile bir Smart Topology modeli seçin.
- lowpoly (kullanımdan kaldırıldı, 30 Ekim 2026 tarihinde devre dışı bırakılacak): Daha temiz poligonlar için optimize edilmiş low-poly ağ üretir. Bunun yerine Meshy T2.5'i öneriyoruz: meshy-t2.5 ile smart-topology.
smart-topology seçildiğinde, should_remesh, save_pre_remeshed_model ve decimation_mode yok sayılır ve yalnızca topology: triangle kabul edilir.
lowpoly, 30 Ekim 2026 tarihinde devre dışı bırakılacaktır. Bu tarihten sonra, model_type: "lowpoly" içeren istekler bir hata döndürecektir. Meshy T2.5'e geçmenizi öneririz (ai_model: "meshy-t2.5" ile model_type: "smart-topology"). lowpoly seçildiğinde, ai_model, topology, target_polycount, should_remesh ve save_pre_remeshed_model yok sayılır.
Name
ai_model
Type
string
varsayılan latest
Description
Kullanılacak modelin ID'si. Kullanılabilir değerler model_type değerine bağlıdır.
Standart üretim (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (kullanımdan kaldırıldı): bunun yerine meshy-7.1 kullanın.
Smart Topology üretimi (model_type: smart-topology):
- meshy-t2: Smart Topology modeli — daha temiz topology, doğal olarak ayrılmış parçalar, üçgen çıktı ve target_polycount ile ayarlayabileceğiniz yüzey sayısı.
- meshy-t2.5 (varsayılan): Oyun assetleri için daha keskin detay. Üçgen çıktı ve target_polycount ile ayarlayabileceğiniz yüzey sayısı.
Name
geometry_resolution
Type
string
varsayılan standard
Description
Geometri oluşturma aşaması. 2k, Ultra aşamasını 2048³'te çalıştırır; 4k, en ince yüzey detayı için 4096³'te çalıştırır.
Kullanılabilir değerler: standard, 2k, 4k
meshy-7.1 veya latest gerektirir.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine geometry_resolution kullanın. ultra_mode: true, geometry_resolution: "2k" ile eşdeğerdir.
Name
should_texture
Type
boolean
varsayılan true
Description
Dokuların üretilip üretilmeyeceğini belirler. false olarak ayarlamak doku aşamasını atlar ve dokusuz bir ağ sağlar.

Yalnızca şu durumlarda geçerli should_texture = true

Name
enable_pbr
Type
boolean
varsayılan false
Description
Temel renge ek olarak PBR Haritaları (metallic, roughness, normal) üretin. ai_model değeri meshy-6 olduğunda, texture_resolution: 8k hariç, bir emisyon haritası da dahil edilir. meshy-6-lite, meshy-7.1, meshy-t2 ve latest emisyon haritası üretmez.
Name
texture_resolution
Type
string
varsayılan 2k
Description
Temel renk doku çözünürlüğü. 2k (2048×2048), 4k (4096×4096) veya 8k (8192×8192) değerlerinden biri. Daha yüksek çözünürlükler daha fazla yüzey detayı yakalar.
4k ve 8k, ai_model değeri meshy-6-lite ile kullanılamaz. 8k seçildiğinde emisyon haritası üretilmez.
Name
hd_texture
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine texture_resolution kullanın — texture_resolution: "4k" ile eşdeğerdir. İkisi de ayarlandığında texture_resolution önceliklidir.
Name
texture_prompt
Type
string
Description
Doku oluşturma sürecini yönlendirmek için bir metin prompt'u sağlayın. Maksimum 800 karakter.
Name
texture_image_url
Type
string
Description
Doku oluşturma sürecini yönlendirmek için bir 2D görsel sağlayın. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.
Maksimum dosya boyutu: 20 MB.
Görseli sağlamanın iki yolu vardır:
- Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL
- Data URI: Görselin base64 ile kodlanmış bir data URI'si. Data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>
Orijinal asset ile yüklenen görsel arasında önemli geometri farklılıkları varsa, görsel ile dokulandırma optimal şekilde çalışmayabilir. Doku oluşturma sürecini yönlendirmek için texture_image_url veya texture_prompt değerlerinden yalnızca biri kullanılabilir. Her iki parametre de sağlanırsa, modeli dokulandırmak için varsayılan olarak texture_prompt kullanılacaktır. Metin veya görsel yoluyla dokulandırma, görev başına 10 kredi maliyetindedir.

Name
should_remesh
Type
boolean
varsayılan false (Meshy 6 and Meshy 7 models), true (others)
Description
Yeniden ağ aşamasının etkinleştirilip etkinleştirilmeyeceğini kontrol eder. En yüksek kaliteli model için should_remesh değerini false olarak ayarlamanızı öneririz.

Yalnızca şu durumlarda geçerli should_remesh = true

Name
topology
Type
string
varsayılan triangle
Description
Üretilen modelin topology'sini belirtin.
Kullanılabilir değerler:
- quad: Dörtgen ağırlıklı bir ağ üretin.
- triangle: Azaltılmış bir üçgen ağ üretin.
Smart Topology çıktısı yalnızca üçgen formatındadır. ai_model değeri meshy-t2 veya meshy-t2.5 ile birlikte quad istemek bir hata döndürür.
Name
decimation_mode
Type
integer
Description
Bir poligon sayısı düzeyi belirleyerek uyarlanabilir azaltmayı etkinleştirin. Ayarlandığında, target_polycount yok sayılır.
Kullanılabilir değerler:
- 1: Uyarlanabilir — ultra poligon sayısı.
- 2: Uyarlanabilir — yüksek poligon sayısı.
- 3: Uyarlanabilir — orta poligon sayısı.
- 4: Uyarlanabilir — düşük poligon sayısı.
Name
save_pre_remeshed_model
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, Meshy yeniden ağ aşaması tamamlanmadan önce ek bir GLB dosyası da saklar.

Name
target_polycount
Type
integer
Description
Çıktıdaki hedef poligon (yüzey) sayısı. Gerçek sayı, geometriye bağlı olarak hedeften sapabilir.
target_polycount, iki bağımsız durumda etkili olur:
- Yeniden ağ — bir standard modelde should_remesh: true ile. Ağ, yaklaşık olarak bu sayıya yeniden ağlanır (azaltılır). Aralık 100 ile 300.000 arası, varsayılan 30.000. decimation_mode ayarlanmışsa, o öncelikli olur ve target_polycount yok sayılır.
- Smart Topology — model_type: smart-topology ve ai_model değeri meshy-t2 veya meshy-t2.5 ile. Model doğrudan bu yüzey sayısında üretilir; yeniden ağ çalışmaz ve should_remesh gerekli değildir. meshy-t2 için: aralık 100 ile 15.000 arası, varsayılan 4.000. meshy-t2.5 için: aralık 100 ile 30.000 arası, varsayılan 15.000.

Name
symmetry_mode
Type
string
⚠ kullanımdan kaldırıldı
varsayılan auto
Description
Kullanımdan kaldırıldı. Bu parametre artık çıktıyı etkilemez.
symmetry_mode alanı, model üretim süreci sırasındaki simetri davranışını kontrol eder.
Geçerli değerler:
- off: Simetriyi devre dışı bırakır.
- auto: Giriş geometrisine göre simetriyi otomatik olarak belirler ve uygular.
- on: Üretim sırasında simetriyi zorunlu kılar.
Name
pose_mode
Type
string
varsayılan ""
Description
Üretilen model için poz modunu belirtin.
Kullanılabilir değerler:
- a-pose: Modeli A pozunda üretin.
- t-pose: Modeli T pozunda üretin.
- "" (boş dize): Belirli bir poz uygulanmaz.
Name
is_a_t_pose
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine pose_mode kullanın. Modelin A/T pozunda üretilip üretilmeyeceği.
Name
surface_mode
Type
string
⚠ kullanımdan kaldırıldı
Description
Artık çıktıyı etkilemez. Bu seçenek, o zamandan beri kullanımdan kaldırılmış bir model üretimini seçiyordu; bunun yerine ai_model kullanın.
Kabul edilen değerler organic ve hard'dır; başka herhangi bir değer 400 döndürür.
Name
image_enhancement
Type
boolean
varsayılan true
Description
Daha iyi sonuçlar için giriş görselini optimize eder. Giriş görselinin kesin görünümünü herhangi bir stil işlemesi olmadan korumak için false olarak ayarlayın.
Yalnızca ai_model değeri meshy-6, meshy-7.1 veya latest olduğunda desteklenir. meshy-6-lite ile veya model_type: smart-topology ile ayarlamak bir hata döndürür.
Name
remove_lighting
Type
boolean
varsayılan true
Description
Temel renk dokusundan vurguları ve gölgeleri kaldırarak, özel aydınlatma kurulumlarında daha iyi çalışan daha temiz bir sonuç üretir.
Yalnızca ai_model değeri meshy-6 olduğunda etkili olur. meshy-7.1 ve latest bunu kabul eder ancak yok sayar. meshy-6-lite ile veya model_type: smart-topology ile ayarlamak bir hata döndürür.
Name
moderation
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, giriş içeriği potansiyel olarak zararlı içerik açısından otomatik olarak taranır. Zararlı içerik tespit edilirse, görev üretime geçmez.
image_url, texture_image_url ve texture_prompt girişlerinden gelen içerik taranacaktır.
Name
target_formats
Type
string[]
Description
Çıktıya hangi 3D dosya formatlarının dahil edileceğini belirtir. Yalnızca istenen formatlar üretilir ve döndürülür; bu da görev tamamlanma süresini azaltabilir. Belirtilmediğinde, desteklenen tüm formatlar dahil edilir.
Kullanılabilir değerler: glb, obj, fbx, stl, usdz, 3mf
Belirtilmediğinde, 3mf dışındaki tüm formatlar üretilir. 3mf, yalnızca açıkça belirtildiğinde dahil edilir.
Name
auto_size
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, hizmet nesnenin gerçek dünyadaki yüksekliğini otomatik olarak tahmin etmek ve modeli buna göre yeniden boyutlandırmak için AI görüşünü kullanır. origin_at açıkça ayarlanmadıkça orijin varsayılan olarak bottom olur.
Name
alpha_thumbnail
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, görev ayrıca önizlemenin şeffaf arka planlı (RGBA) bir versiyonunu oluşturur ve bunu GET yanıtında alpha_thumbnail_url olarak döndürür. Mevcut thumbnail_url alanı değişmez.
Name
multi_view_thumbnails
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, görev ayrıca dört ana görünüm küçük resmi (ön, sağ, arka, sol) oluşturur ve bunları GET yanıtında thumbnail_urls altında döndürür. Mevcut thumbnail_url alanı değişmez ve ön görünümü göstermeye devam eder, bu nedenle mevcut istemciler etkilenmez.
Görev gecikmesine yaklaşık 3 saniye ekler.

Yalnızca şu durumlarda geçerli auto_size = true

Name
origin_at
Type
string
varsayılan bottom
Description
auto_size etkinleştirildiğinde orijinin konumu.
Kullanılabilir değerler: bottom, center.

Dönüş Değerleri

Yanıtın result özelliği, yeni oluşturulan Görselden 3D'ye görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: image_url veya input_task_id sağlanmalıdır.
- Geçersiz giriş görevi: input_task_id, tam olarak bir görsel üreten, SUCCEEDED durumunda bir Metinden görsele veya Görselden görsele görevine atıfta bulunmalıdır.
- Geçersiz görsel formatı: Sağlanan image_url, desteklenen bir format değil (.jpg, .jpeg, .png, .webp).
- Erişilemeyen URL: image_url indirilemedi (404 veya timeout).
- Görsel çok büyük: image_url veya texture_image_url görseli 20 MB'ı aşıyor.
- Geçersiz Data URI: base64 dizesi hatalı biçimlendirilmiş.
- Geçersiz parametre kombinasyonu: enable_pbr, yalnızca should_texture true olduğunda desteklenir.
- Low poly için desteklenmeyen model: ai_model: "meshy-6-lite", model_type: "lowpoly" değerini desteklemez.
- Ultra için desteklenmeyen model: geometry_resolution, meshy-7.1 veya latest gerektirir.
- Görsel seçenekleri için desteklenmeyen model: image_enhancement veya remove_lighting, ai_model: "meshy-6-lite" veya model_type: "smart-topology" ile ayarlanmış.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yetersiz kredi.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

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

Image to 3D Görevini Al

Bu uç nokta, geçerli bir görev id'si verildiğinde bir Görselden 3D'ye görevini almanızı sağlar. Görselden 3D'ye görev nesnesiyle birlikte hangi özelliklerin yer aldığını görmek için The Image to 3D Task Object bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak Görselden 3D'ye görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, Görselden 3D'ye görev nesnesini içerir. Ayrıntılar için The Image to 3D Task Object bölümüne bakın.

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

Bir Görselden 3D'ye Görevini Sil

Bu uç nokta, ilişkili tüm modeller ve veriler dahil olmak üzere bir Görselden 3D'ye görevini kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

Name
id
Type
path
Description
Silinecek Görselden 3D'ye görevinin kimliği.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan kredi iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlattığı bir görev için krediler iade edilemez, bu nedenle görevi çalışırken silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son durumda (SUCCEEDED, FAILED veya CANCELED) olan bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olursa 200 OK, görev IN_PROGRESS durumundaysa 409 Conflict döner.

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

Image to 3D Görevlerini Listele

Bu uç nokta, Görselden 3D'ye görevlerinin bir listesini almanızı sağlar.

Parametreler

İsteğe bağlı özellikler

Name
page_num
Type
integer
Description
Sayfalama için sayfa numarası. 1 ile başlar ve varsayılan değeri 1'dir.
Name
page_size
Type
integer
Description
Sayfa boyutu limiti. Varsayılan 10 öğedir. İzin verilen maksimum 100 öğedir.
Name
sort_by
Type
string
Description
Sıralama yapılacak alan. Kullanılabilir değerler:
- +created_at: Oluşturulma zamanına göre artan sırada sıralar.
- -created_at: Oluşturulma zamanına göre azalan sırada sıralar.

Dönüş Değerleri

Image to 3D Görev Nesneleri'nin sayfalanmış bir listesini döndürür.

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

Bir Görselden 3D'ye Görevini Akışla İzleme

Bu uç nokta, Sunucu Tarafından Gönderilen Olaylar (SSE) kullanarak bir Görselden 3D'ye görevi için gerçek zamanlı güncellemeleri akışla iletir.

Parametreler

Name
id
Type
path
Description
Akışla izlenecek Görselden 3D'ye görevi için benzersiz tanımlayıcı.

Döndürülenler

Görselden 3D'ye Görev Nesnelerini Sunucu Tarafından Gönderilen Olaylar olarak bir akış şeklinde döndürür.

PENDING veya IN_PROGRESS durumundaki görevler için yanıt akışı yalnızca gerekli progress ve status alanlarını içerecektir.

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
}

Görselden 3D'ye Görev Nesnesi

Görselden 3D'ye Görev nesnesi, Meshy'nin bir görsel girdisinden 3D model oluşturmak için takip ettiği bir iş birimidir. Nesne aşağıdaki özelliklere sahiptir:

Özellikler

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev kimlikleri için k-sıralanabilir bir UUID kullansak da, id'nin biçimi hakkında herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Görselden 3D'ye görevinin türü. Değer image-to-3d şeklindedir.
Name
model_urls
Type
object
Description
Meshy tarafından oluşturulan dokulu 3D model dosyasına indirilebilir URL. Bir format oluşturulmamışsa, boş bir dize döndürülmek yerine o format için özellik atlanır.
- Name
  glb
  Type
  string
  Description
  GLB dosyasına indirilebilir URL.
- Name
  fbx
  Type
  string
  Description
  FBX dosyasına indirilebilir URL.
- Name
  obj
  Type
  string
  Description
  OBJ dosyasına indirilebilir URL.
- Name
  usdz
  Type
  string
  Description
  USDZ dosyasına indirilebilir URL.
- Name
  mtl
  Type
  string
  Description
  Dokular mevcut olduğunda OBJ dışa aktarımlarıyla birlikte döndürülen MTL dosyasına indirilebilir URL.
- Name
  stl
  Type
  string
  Description
  STL dosyasına indirilebilir URL.
- Name
  3mf
  Type
  string
  Description
  3MF dosyasına indirilebilir URL. Yalnızca target_formats aracılığıyla 3mf istendiğinde mevcuttur.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Remesh işleminden önceki orijinal GLB çıktısına indirilebilir URL.
  Yalnızca görev hem should_remesh: true hem de save_pre_remeshed_model: true ile oluşturulduğunda mevcuttur.
Name
thumbnail_url
Type
string
Description
Model dosyasının küçük resim görseline indirilebilir URL. Mevcut olduğunda thumbnail_urls.front ile eşdeğerdir, geriye dönük uyumluluk için korunmuştur.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url'nin şeffaf arka planlı (RGBA) bir sürümüne indirilebilir URL. Yalnızca görev alpha_thumbnail: true ile oluşturulduğunda ve şeffaf önizleme başarıyla render edildiğinde mevcuttur; aksi halde bu alan atlanır.
Name
thumbnail_urls
Type
object
Description
Oluşturulan 3D modelin dört ana yön görünümü için küçük resimlere indirilebilir URL'ler. Her değer, thumbnail_url ile aynı materyaller ve aydınlatmayla render edilmiş 512×512 bir PNG için imzalı bir URL'dir. GLB'yi indirmeden toplu iş hatlarında modeli birden çok açıdan önizlemek için kullanışlıdır.
Yalnızca görev multi_view_thumbnails: true ile oluşturulduğunda ve SUCCEEDED durumuna ulaştığında mevcuttur. Daha eski görevler ve bu seçenek etkinleştirilmeden oluşturulan görevler bu alanı içermeyecektir.
- Name
  front
  Type
  string
  Description
  Ön görünüm, dikey eksen etrafında 0° döndürme (thumbnail_url ile eşleşir).
- Name
  right
  Type
  string
  Description
  Sağ görünüm, 90° döndürme.
- Name
  back
  Type
  string
  Description
  Arka görünüm, 180° döndürme.
- Name
  left
  Type
  string
  Description
  Sol görünüm, 270° döndürme.
Name
texture_prompt
Type
string
Description
Dokulandırma sürecine rehberlik etmek için kullanılan metin prompt'u.
Name
texture_image_url
Type
string
Description
Dokulandırma sürecine rehberlik etmek için kullanılan doku görseline indirilebilir URL.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
Description
Kullanımdan kaldırıldı; bunun yerine geometry_resolution değerini okuyun.
Name
geometry_resolution
Type
string
Description
Görevin çalıştığı Ultra katmanı (2k veya 4k); standard için atlanır.
Name
progress
Type
integer
Description
Görevin ilerleme durumu. Görev henüz başlamadıysa bu özellik 0 olacaktır. Görev başarılı olduğunda bu değer 100 olur.
Name
started_at
Type
timestamp
Description
Görevin başlatıldığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa bu özellik 0 olacaktır.
Bir zaman damgası, RFC 3339 standardını takip ederek 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma, 12:00:00 GMT, 1693569600000 olarak temsil edilir. Bu, Meshy API'deki tüm zaman damgaları için geçerlidir.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.
Name
expires_at
Type
timestamp
Description
Görev sonucunun süresinin dolacağı zamanın milisaniye cinsinden zaman damgası.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zamanın milisaniye cinsinden zaman damgası. Görev henüz tamamlanmadıysa bu özellik 0 olacaktır.
Name
status
Type
string
Description
Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biridir.
Name
texture_urls
Type
array
Description
Görevden oluşturulan doku URL nesnelerinden oluşan bir dizi. Normalde bu yalnızca bir doku URL nesnesi içerir. Her doku URL'si aşağıdaki özelliklere sahiptir:
- Name
  base_color
  Type
  string
  Description
  Temel renk haritası görseline indirilebilir URL.
- Name
  metallic
  Type
  string
  Description
  Metalik harita görseline indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa bu özellik atlanır.
- Name
  normal
  Type
  string
  Description
  Normal harita görseline indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa bu özellik atlanır.
- Name
  roughness
  Type
  string
  Description
  Pürüzlülük haritası görseline indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa bu özellik atlanır.
- Name
  emission
  Type
  string
  Description
  Emisyon haritası görseline indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa veya ai_model değeri meshy-6-lite, meshy-7.1, meshy-t2 ya da latest ise bu özellik atlanır.
Name
preceding_tasks
Type
integer
Description
Önceki görevlerin sayısı.
Bu alanın değeri yalnızca görev durumu PENDING olduğunda anlamlıdır.
Name
task_error
Type
object
Description
Başarısız görevler için hata detayları. Tam task_error nesnesi referansı için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. Görev durumu PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED görevler için 0 döndürülür (başarısızlık durumunda krediler iade edilir).

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
}