Görselden 3D'ye API

Bir görseli, dokulu ya da dokusuz olarak, seçtiğiniz formatlarda 3D modele dönüştürün. Görseli gönderin ya da bir Metinden görsele veya Görselden görsele görevinin çıktısını kullanın.

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

Görselden 3D'ye görevi oluşturma

Bir Görselden 3D'ye görevi oluşturur. Görev arka planda çalışır. Bir görevin genelde ne kadar sürdüğü için bkz. İşlem süreleri.

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

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
image_url göndermiyorsanız zorunludur. Girdi olarak kullanmak istediğiniz görseli üreten bir Metinden görsele veya Görselden görsele görevinin kimliği. Bu görev, API ile oluşturduğunuz, durumu SUCCEEDED olan ve tam olarak bir görsel üretmiş bir görev olmalıdır.

Name
image_url
Type
string
Zorunlu
Description
input_task_id göndermiyorsanız zorunludur. 3D modele dönüştürülecek görsel; herkese açık bir URL veya data:image/jpeg;base64,<your base64-encoded image data> gibi base64 ile kodlanmış bir data URI olarak verilir. İkisini birden gönderirseniz Meshy input_task_id'yi kullanır.
Görsel en fazla 20 MB boyutunda, her bir kenarı en az 32 piksel ve en fazla 178.956.970 piksel (genişlik × yükseklik) olan bir JPG, JPEG, PNG veya WebP dosyası olmalıdır.

Name
model_type
Type
string
varsayılan standard
Description
Oluşturulacak 3D ağın türü.
Kullanılabilir değerler:
- standard: yüksek detaylı bir ağ
- smart-topology: ai_model (meshy-t2 veya meshy-t2.5) ile seçtiğiniz bir Smart Topology modelinden oluşturulan bir ağ
smart-topology ile Meshy, should_remesh, save_pre_remeshed_model ve decimation_mode parametrelerini yok sayar ve yalnızca topology: triangle değerini kabul eder.
Name
ai_model
Type
string
varsayılan latest
Description
3D modeli oluşturan yapay zeka modeli. Kullanılabilir değerler model_type'a bağlıdır.
Standart modeller (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (kullanımdan kaldırıldı): bunun yerine meshy-7.1 kullanın
Smart Topology modelleri (model_type: smart-topology), target_polycount ile ayarlayabileceğiniz bir yüzey sayısında üçgenler üretir:
- meshy-t2: daha temiz topology ve doğal olarak ayrılmış parçalar
- meshy-t2.5 (varsayılan): oyun varlıkları için daha keskin detay
Projenize, örneğin bir oyun karakteri veya 3D baskı için hangi modelin uygun olduğunu görmek için bkz. Modeller.
Name
geometry_resolution
Type
string
varsayılan standard
Description
Geometri oluşturma aşaması.
Kullanılabilir değerler:
- standard
- 2k: Ultra aşamasını 2048³ çözünürlükte çalıştırır
- 4k: en fazla yüzey detayı için Ultra aşamasını 4096³ çözünürlükte çalıştırır
2k için meshy-7.1, latest veya kullanımdan kaldırılan meshy-7 gereklidir. 4k için meshy-7.1 veya latest gereklidir.
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 aynıdır.
Name
should_texture
Type
boolean
varsayılan true
Description
Doku oluşturulup oluşturulmayacağı. true dokulu bir model döndürür, false ise dokulandırmayı atlayıp dokusuz bir ağ döndürür.

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

Name
texture_model
Type
string
varsayılan depends on ai_model
Description
3D modeli aynı görev içinde dokulandıran yapay zeka modeli. ai_model'iniz için varsayılan doku modelini kullanmak üzere boş bırakın. Kredi maliyetini değiştirmez.
Kullanılabilir değerler:
- meshy-7: PBR haritaları ve 8K'ya kadar dokularla Meshy 7
- meshy-n1: yalnızca referans görsellerden 2K temel renk dokusu üreten Meshy N1
- meshy-6-lite: en düşük maliyetli 2K doku üreten Meshy 6 Lite
- meshy-6: Meshy 6, yalnızca ai_model: meshy-6 için varsayılan olarak
Her ai_model, meshy-7, meshy-n1 ve meshy-6-lite değerlerini kabul eder. Seçilen doku modelinin desteklemediği bir seçenek 400 döndürür. meshy-n1 ile oluşturulan model 7.999.999 üçgeni aşarsa görev başarısız olur ve Meshy kredilerini iade eder. should_texture: false ile Meshy texture_model'i yok sayar, ancak bilinmeyen bir değer yine de 400 döndürür.
Her doku modelinin ne yaptığı ve hangisini seçmeniz gerektiği için bkz. Modeller.
Name
enable_pbr
Type
boolean
varsayılan false
Description
Temel rengin yanı sıra PBR haritalarının (metalik, pürüzlülük ve normal) da oluşturulup oluşturulmayacağı. true için should_texture: true gereklidir; should_texture: false ile 400 döndürür. texture_model: meshy-n1 ile true, 400 döndürür.
Meshy 6 doku modeli, texture_resolution: 8k hariç olmak üzere bir emisyon haritası da oluşturur.
Name
texture_resolution
Type
string
varsayılan 2k
Description
Temel renk dokusunun boyutu. Daha büyük bir doku daha fazla yüzey detayı yakalar.
Kullanılabilir değerler:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k ve 8k için Meshy 7 veya Meshy 6 doku modeli gereklidir; diğerleriyle 400 döndürür. 8k'de Meshy bir emisyon haritası üretmez.
Name
hd_texture
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine texture_resolution kullanın. hd_texture: true, texture_resolution: "4k" ile aynıdır. İkisini birden gönderirseniz Meshy texture_resolution'ı kullanır.
Name
texture_prompt
Type
string
Description
Dokuya yön veren, en fazla 800 karakterlik metin. Daha uzun metin 400 döndürür. texture_model: meshy-n1 ile gönderilmesi 400 döndürür.
Name
texture_image_url
Type
string
Description
Dokuya yön veren bir görsel; herkese açık bir URL veya data:image/jpeg;base64,<your base64-encoded image data> gibi base64 ile kodlanmış bir data URI olarak verilir. Görsel en fazla 20 MB boyutunda, her bir kenarı en az 32 piksel ve en fazla 178.956.970 piksel (genişlik × yükseklik) olan bir JPG, JPEG, PNG veya WebP dosyası olmalıdır.
Meshy, dokuya yalnızca texture_prompt ve texture_image_url'den biriyle yön verir. İkisini birden gönderirseniz Meshy texture_prompt'u kullanır. Dokulandırmanın kredi maliyeti için bkz. Fiyatlandırma.
texture_model: meshy-n1 ile Meshy, bu görseli ön görünüm olarak kullanarak dokulandırır; boş bırakırsanız girdi görselini kullanır.
Görselin şekli 3D modelin geometrisinden büyük ölçüde farklıysa bir görselden dokulandırma iyi çalışmayabilir.

Name
should_remesh
Type
boolean
varsayılan true (meshy-6-lite), false (other models)
Description
Yeniden ağ aşamasının çalıştırılıp çalıştırılmayacağı. En yüksek kaliteli 3D model için bunu false olarak ayarlayın.

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

Name
topology
Type
string
varsayılan triangle
Description
Yeniden ağlandırılmış modelin yüzey türü.
Kullanılabilir değerler:
- quad: dörtgen ağırlıklı bir ağ
- triangle: sadeleştirilmiş bir üçgen ağ
Smart Topology çıktısı yalnızca üçgenlerden oluşur, bu yüzden meshy-t2 veya meshy-t2.5 ile quad, 400 döndürür. texture_model: meshy-n1 ile, model yeniden ağlandırıldığında quad, 400 döndürür; meshy-6-lite bunu varsayılan olarak yapar.
Name
decimation_mode
Type
integer
Description
Seviyeye göre uyarlanabilir yüzey sayısı. Bunu ayarladığınızda Meshy target_polycount'u yok sayar.
Kullanılabilir değerler:
- 1: ultra
- 2: yüksek
- 3: orta
- 4: düşük
Name
save_pre_remeshed_model
Type
boolean
varsayılan false
Description
Yeniden ağ aşamasından önceki modelin bir GLB'sinin de saklanıp saklanmayacağı. Meshy bunu model_urls.pre_remeshed_glb içinde döndürür.

Name
target_polycount
Type
integer
Description
Hedeflenen yüzey sayısı. Sonuç, modelin geometrisine bağlı olarak hedeften farklı olabilir.
İki ayrı durumda geçerlidir:
- Yeniden ağ: should_remesh, bir standard modelde true olduğunda Meshy ağı yaklaşık bu sayıya kadar sadeleştirir. decimation_mode ayarlarsanız Meshy bunu kullanır ve target_polycount'u yok sayar.
- Smart Topology: model_type, smart-topology ve ai_model, meshy-t2 veya meshy-t2.5 olduğunda Meshy modeli bu yüzey sayısında oluşturur. Yeniden ağ çalışmaz ve should_remesh'e ihtiyacınız yoktur.
Aralık ve varsayılan değer duruma bağlıdır:
Durum Aralık Varsayılan
Yeniden ağ 100 ile 300000 30000
meshy-t2 100 ile 15000 4000
meshy-t2.5 100 ile 30000 15000
Aralığın dışındaki bir değer 400 döndürür.
Low-poly bir oyun varlığı için, standart bir modeli yeniden ağlandırmak yerine bir Smart Topology modeli kullanın. Bkz. Modeller.

Durum	Aralık	Varsayılan
Yeniden ağ	`100` ile `300000`	`30000`
`meshy-t2`	`100` ile `15000`	`4000`
`meshy-t2.5`	`100` ile `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ kullanımdan kaldırıldı
varsayılan auto
Description
Çıktıyı etkilemediği için boş bırakın. Değerleri, oluşturma sırasında simetriyi kontrol ediyordu:
- off: simetri yok
- auto: girdi geometrisinden seçilen simetri
- on: zorunlu simetri
Name
pose_mode
Type
string
varsayılan ""
Description
Oluşturulan model için poz.
Kullanılabilir değerler:
- a-pose: A pozu
- t-pose: T pozu
- "" (boş dize): belirli bir poz yok
Name
is_a_t_pose
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine pose_mode kullanın. Modelin A veya T pozunda oluşturulup oluşturulmayacağı.
Name
surface_mode
Type
string
⚠ kullanımdan kaldırıldı
Description
Bunun yerine ai_model kullanın. Seçtiği model oluşturma yöntemi kullanımdan kaldırıldığı için çıktıyı etkilemez.
Kabul edilen değerler organic ve hard'dır. Diğer herhangi bir değer 400 döndürür.
Name
image_enhancement
Type
boolean
varsayılan true
Description
Oluşturmadan önce girdi görselinin optimize edilip edilmeyeceği. false, stil işleme yapmadan girdi görselinin tam görünümünü korur.
Yalnızca meshy-6, meshy-7.1 veya latest ile çalışır. meshy-6-lite veya model_type: smart-topology ile 400 döndürür.
Name
remove_lighting
Type
boolean
varsayılan true
Description
Temel renk dokusundan vurguların ve gölgelerin kaldırılıp kaldırılmayacağı. Sonuç daha temizdir ve kendi ışıklandırmanız altında daha iyi çalışır.
Yalnızca Meshy 6 doku modeliyle etkilidir; bunu desteklemeyen bir doku modeli, true için 400 döndürür. model_type: smart-topology ile, veya ai_model: meshy-6-lite ve onun varsayılan doku modeliyle, gönderilmesi 400 döndürür.
Name
moderation
Type
boolean
varsayılan false
Description
Oluşturmadan önce şu girdilerin zararlı içerik açısından taranıp taranmayacağı:
- image_url
- texture_image_url
- texture_prompt
Meshy zararlı içerik tespit ederse istek 400 döndürür ve Meshy bir görev oluşturmaz.
Name
target_formats
Type
string[]
Description
Oluşturulacak dosya formatları. Meshy yalnızca listelediğiniz formatları oluşturur ve döndürür; bu da görevi kısaltabilir. Boş bırakırsanız Meshy, yalnızca listelediğinizde elde edeceğiniz 3mf hariç her formatı oluşturur.
Kullanılabilir değerler:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
varsayılan false
Description
Nesnenin gerçek dünyadaki yüksekliğinin yapay zeka görüşüyle tahmin edilip modelin buna göre yeniden boyutlandırılıp boyutlandırılmayacağı. origin_at ayarlamadığınız sürece Meshy orijini alta yerleştirir.
Name
alpha_thumbnail
Type
boolean
varsayılan false
Description
Görevi aldığınızda alpha_thumbnail_url içinde döndürülen, saydam arka planlı (RGBA) bir önizlemenin de oluşturulup oluşturulmayacağı. thumbnail_url değişmez.
Name
multi_view_thumbnails
Type
boolean
varsayılan false
Description
Görevi aldığınızda thumbnail_urls içinde döndürülen ön, sağ, arka ve sol önizlemelerin de oluşturulup oluşturulmayacağı. thumbnail_url değişmez ve ön görünümü göstermeye devam eder. Bu, göreve yaklaşık 5 saniye ekler.

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

Name
origin_at
Type
string
varsayılan bottom
Description
Modelin orijininin nereye konulacağı, bottom veya center.

Dönüş değerleri

Yanıtın result alanı, yeni Görselden 3D'ye görevinin kimliğini tutar.

Hata durumları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunu bulduğunu belirtir. Örneğin:
- Eksik parametre: Ne image_url ne de input_task_id gönderildi.
- Geçersiz girdi görevi: input_task_id, tam olarak bir görsel üretmiş, SUCCEEDED durumunda bir Metinden görsele veya Görselden görsele görevi değil.
- Geçersiz görsel formatı: image_url görseli bir JPG, JPEG, PNG veya WebP dosyası değil.
- Erişilemeyen URL: URL 404 döndürdüğü veya zaman aşımına uğradığı için Meshy, image_url görselini indiremiyor.
- Görsel çok büyük: image_url veya texture_image_url görseli 20 MB'ın üzerinde.
- Geçersiz görsel boyutu: image_url veya texture_image_url görselinin bir kenarı 32 pikselden kısa veya 178.956.970 pikselden (genişlik × yükseklik) fazla.
- Geçersiz data URI: base64 dizesi hatalı biçimlendirilmiş.
- Geçersiz parametre kombinasyonu: enable_pbr, true ve should_texture, false.
- Ultra için desteklenmeyen model: geometry_resolution, 2k veya 4k ve bunu çalıştıramayan bir ai_model.
- Görsel seçenekleri için desteklenmeyen model: şunlardan biri:
  - image_enhancement, ai_model: "meshy-6-lite" veya model_type: "smart-topology" ile gönderildi.
  - remove_lighting, model_type: "smart-topology" ile, veya ai_model: "meshy-6-lite" ve onun varsayılan doku modeliyle gönderildi.
- Geçersiz doku modeli: texture_model, kullanılabilir değerlerden biri değil.
- Doku modeli kullanılamıyor: texture_model, meshy-6 dışında bir ai_model ile meshy-6 olarak gönderildi. meshy-7, meshy-n1 veya meshy-6-lite gönderin ya da boş bırakın.
- Doku modeli için desteklenmeyen seçenek: İstek, doku modelinden desteklemediği bir seçenek istiyor; örneğin meshy-n1 ile enable_pbr: true veya meshy-6-lite ile 4k doku. Bkz. Modeller.
İsteği düzeltip tekrar gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi limitine ulaştı. Kredi bakiyenizi kontrol edip tekrar deneyin.
- Ücretsiz plan: Bir görev oluşturmak ücretli bir plan gerektirir. Abonelik ayarlarınızdan planınızı yükseltip tekrar deneyin.
Name
403 - Forbidden
Description
İçerik denetimi, prompt'u veya bir girdi görselini engelledi. Girdiyi değiştirip tekrar deneyin.
Name
404 - Not Found
Description
input_task_id, görevlerinizden hiçbiriyle eşleşmiyor. Görev kimliğini kontrol edip isteği tekrar gönderin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyip tekrar deneyin. Bkz. Hız sınırları.

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

Image to 3D görevi al

Belirtilen ID'ye sahip bir Görselden 3D'ye görevini döndürür.

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
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev ID'si.

Dönüş Değerleri

Görselden 3D'ye görev nesnesi.

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

Bir Görselden 3D'ye görevini sil

Bir Görselden 3D'ye görevini, modelleri ve verileriyle birlikte kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin kimliği.

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döndürür ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu nedenle görevi 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örevi silmek kredilerini iade etmez.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundayken ise 409 Conflict döner.

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

Image to 3D görevlerini listele

Görselden 3D'ye görevlerinizin 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": null,
    "consumed_credits": 30
  }
]

Parametreler

Name
page_num
Type
integer
varsayılan 1
Description
Döndürülecek sayfa numarası, en fazla 255. Daha büyük bir değer 400 döndürür.
Name
page_size
Type
integer
varsayılan 10
Description
Sayfa başına görev sayısı, en fazla 100.
Name
sort_by
Type
string
Description
Sıralama düzeni.
Kullanılabilir değerler:
- +created_at: önce en eski
- -created_at: önce en yeni

Döndürülenler

Görselden 3D'ye görev nesnelerinin sayfalanmış bir listesi.

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

Image to 3D görevini akışla alma

Bir Image to 3D görevinin güncellemelerini Server-Sent Events (SSE) olarak akışa yayınlar.

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
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından gelen görev ID'si.

Dönüş Değerleri

Server-Sent Events olarak bir Image to 3D görev nesneleri akışı.

Her olay, Get uç noktasının döndürdüğü ile aynı biçimde, görev nesnesinin tamamını içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.

Image to 3D görev nesnesi

Bir Image to 3D görev nesnesi, bir görselden bir 3D modelin oluşturulma sürecini tanımlar. Görevin durumunu, progress değerini ve görev başarılı olduğunda model dosyalarını tutar.

Özellikler

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
Görev kimliği. Bunu opak bir dize olarak kabul edin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman image-to-3d.
Name
model_urls
Type
object
Description
Oluşturulan 3D model için, her dosya biçimi için bir tane olmak üzere indirme URL'leri. Görevin oluşturmadığı bir biçimin, boş bir dize yerine hiç anahtarı yoktur.
- Name
  glb
  Type
  string
  Description
  GLB dosyası.
- Name
  fbx
  Type
  string
  Description
  FBX dosyası.
- Name
  obj
  Type
  string
  Description
  OBJ dosyası.
- Name
  usdz
  Type
  string
  Description
  USDZ dosyası.
- Name
  mtl
  Type
  string
  Description
  Model dokulara sahip olduğunda bir OBJ dosyasıyla birlikte döndürülen MTL dosyası.
- Name
  stl
  Type
  string
  Description
  STL dosyası.
- Name
  3mf
  Type
  string
  Description
  3MF dosyası. Yalnızca target_formats içinde 3mf bulunduğunda mevcuttur.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Yeniden ağ işleminden önceki GLB dosyası. Yalnızca görevi hem should_remesh: true hem de save_pre_remeshed_model: true ile oluşturduğunuzda mevcuttur.
Name
thumbnail_url
Type
string
Description
3D modelin önizleme görseli için indirme URL'si. thumbnail_urls mevcut olduğunda, bu thumbnail_urls.front ile aynı görseldir. Meshy, geriye dönük uyumluluk için bunu korur.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url değerinin şeffaf arka planlı (RGBA) bir sürümü için indirme URL'si. Yalnızca görevi alpha_thumbnail: true ile oluşturduğunuzda ve Meshy şeffaf önizlemeyi render ettiğinde mevcuttur.
Name
thumbnail_urls
Type
object
Description
3D modelin dört taraftan önizlemeleri için indirme URL'leri. Her değer, thumbnail_url ile aynı malzemeler ve aydınlatmayla render edilmiş 512×512 bir PNG için imzalı bir URL'dir. Bunları, örneğin bir toplu işlem hattında GLB'yi indirmeden modeli birkaç açıdan önizlemek için kullanın.
Yalnızca görevi multi_view_thumbnails: true ile oluşturduğunuzda ve görev SUCCEEDED durumuna ulaştığında mevcuttur. multi_view_thumbnails: true olmadan oluşturulan görevler bu alanı içermez.
- Name
  front
  Type
  string
  Description
  Dikey eksen etrafında 0°'de önden görünüm. thumbnail_url ile eşleşir.
- Name
  right
  Type
  string
  Description
  90°'de sağdan görünüm.
- Name
  back
  Type
  string
  Description
  180°'de arkadan görünüm.
- Name
  left
  Type
  string
  Description
  270°'de soldan görünüm.
Name
texture_prompt
Type
string
Description
Dokuya yön veren metin prompt'u.
Name
texture_image_url
Type
string
Description
Dokuya yön veren görsel için indirme URL'si.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
Description
Bunun yerine geometry_resolution değerini okuyun.
Name
geometry_resolution
Type
string
Description
Görevin çalıştığı Ultra katmanı, 2k veya 4k. Bir standard görev bu alanı içermez.
Name
progress
Type
integer
Description
Görevin yüzde olarak ne kadarının tamamlandığı. Görev başlayana kadar 0, başarılı olduğunda 100 değerindedir.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0 değerindedir.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
expires_at
Type
timestamp
Description
Görevin sonucunun süresinin dolacağı zaman, Unix milisaniye cinsinden.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar 0 değerindedir.
Name
status
Type
string
Description
Görev durumu, PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biri.
Name
texture_urls
Type
array
Description
Görevin oluşturduğu doku haritaları, bir nesne dizisi olarak. Genellikle şu alanlara sahip tek bir nesne tutar:
- Name
  base_color
  Type
  string
  Description
  Temel renk haritası için indirme URL'si.
- Name
  metallic
  Type
  string
  Description
  Metalik harita için indirme URL'si. Görevi enable_pbr: false ile oluşturduğunuzda bu alan bulunmaz.
- Name
  normal
  Type
  string
  Description
  Normal harita için indirme URL'si. Görevi enable_pbr: false ile oluşturduğunuzda bu alan bulunmaz.
- Name
  roughness
  Type
  string
  Description
  Pürüzlülük haritası için indirme URL'si. Görevi enable_pbr: false ile oluşturduğunuzda bu alan bulunmaz.
- Name
  emission
  Type
  string
  Description
  Emisyon haritası için indirme URL'si. Meshy bunu yalnızca görevi aşağıdakilerin tümüyle oluşturduğunuzda içerir:
  
  ai_model: meshy-6, varsayılan doku modeliyle
  
  enable_pbr: true
  
  2k veya 4k değerinde bir texture_resolution
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önceki görevlerin sayısı. Değer yalnızca görev PENDING durumundayken anlamlıdır.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Durum FAILED olmadığı sürece null değerindedir. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı. Durum PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED bir görev için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.