Metinden 3D'ye API

Metinden 3D'ye API, Meshy'nin Metinden 3D'ye yeteneklerini 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.

Metinden 3D'ye, iki adımlı bir iş akışı kullanır. Öncelikle, şekli değerlendirebilmeniz için dokusuz bir 3D ağ oluşturmak üzere bir preview görevi (mode: "preview") oluşturun. Ardından, tamamlanan preview görevinin görev kimliğini bir refine görevine (mode: "refine") aktararak ağa doku uygulayın. Her iki adım da aynı uç noktayı paylaşır.

POST/openapi/v2/text-to-3d

Bir Text to 3D Preview Görevi Oluştur

Bu uç nokta, bir metin promptundan dokusuz bir 3D ağ (yalnızca geometri) üreten bir Text to 3D preview görevi oluşturur. Bu, iki adımlı iş akışının ilk adımıdır. Preview başarılı olduktan sonra, dönen görev ID'sini kullanarak dokulandırma için bir refine görevi oluşturun. Yanıt şemasının tamamı için The Text to 3D Task Object bölümüne bakın.

Parametreler

  • Name
    mode
    Type
    string
    Zorunlu
    Description

    Bir preview görevi oluştururken bu alan "preview" olarak ayarlanmalıdır.

  • Name
    prompt
    Type
    string
    Zorunlu
    Description

    3D modelin ne tür bir nesne olduğunu tanımlayın. Maksimum 800 karakter.

  • 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: Smart Topology modelini ai_model (meshy-t2) ile seçin.
    • lowpoly (kullanımdan kaldırıldı): Daha temiz poligonlar için optimize edilmiş low-poly ağ üretir. Bunun yerine smart-topology kullanmanızı öneririz.

    smart-topology seçildiğinde, should_remesh ve decimation_mode yok sayılır ve yalnızca topology: triangle kabul edilir.

    lowpoly seçildiğinde, ai_model, topology, target_polycount ve should_remesh yok sayılır.

  • Name
    ai_model
    Type
    string
    varsayılan latest
    Description

    Kullanılacak modelin ID'si. Kullanılabilir değerler model_type'a bağlıdır.

    Standart oluşturma (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 oluşturma (model_type: smart-topology):

    • meshy-t2 (varsayılan): Smart Topology modeli — daha temiz topology, doğal olarak ayrılmış parçalar, üçgen çıktı ve target_polycount ile ayarlayabileceğiniz bir yüz sayısı.
  • Name
    geometry_resolution
    Type
    string
    varsayılan standard
    Description

    Geometri oluşturma geçişi. 2k, Ultra geçişini 2048³'te çalıştırır; 4k ise en ince yüzey detayı için bunu 4096³'te çalıştırır.

    Kullanılabilir değerler: standard, 2k, 4k

    Yalnızca preview modunda desteklenir. 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_remesh
    Type
    boolean
    varsayılan false (Meshy 6 and Meshy 7 models), true (others)
    Description

    Yeniden ağ oluşturma aşamasının etkinleştirilip etkinleştirilmeyeceğini kontrol eder. En yüksek kaliteli model için should_remesh'i false olarak ayarlamanızı öneririz.

Yalnızca şu durumlarda geçerli should_remesh = true
  • Name
    topology
    Type
    string
    varsayılan triangle
    Description

    Oluşturulan modelin topology'sini belirtin.

    Kullanılabilir değerler:

    • quad: Çoğunlukla quad olan bir ağ oluşturur.
    • triangle: Küçültülmüş bir üçgen ağ oluşturur.

    Smart Topology çıktısı yalnızca üçgendir. quad'ı ai_model: meshy-t2 ile birlikte istemek bir hata döndürür.

  • Name
    decimation_mode
    Type
    integer
    Description

    Bir poligon sayısı seviyesi belirleyerek uyarlanabilir küçültmeyi etkinleştirin. Bu 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
    target_polycount
    Type
    integer
    Description

    Çıktıdaki hedef poligon (yüz) sayısı. Gerçek sayı, geometriye bağlı olarak hedeften farklılık gösterebilir.

    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 küçültülerek (decimate) yeniden ağlanır. Aralık 100 ile 300.000 arasındadır, varsayılan 30.000'dir. decimation_mode ayarlanmışsa, öncelik ona verilir ve target_polycount yok sayılır.
    • Smart Topology — model_type: smart-topology ve ai_model: meshy-t2 ile. Model doğrudan bu yüz sayısında oluşturulur; yeniden ağ çalıştırılmaz ve should_remesh gerekli değildir. Aralık 100 ile 15.000 arasındadır, varsayılan 4.000'dir.
  • 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 oluşturma 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: Oluşturma sırasında simetriyi zorunlu kılar.
  • Name
    pose_mode
    Type
    string
    varsayılan ""
    Description

    Oluşturulan model için pose mode'u belirtin.

    Kullanılabilir değerler:

    • a-pose: Modeli A pozunda oluşturur.
    • t-pose: Modeli T pozunda oluşturur.
    • "" (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 oluşturulup oluşturulmayacağı.

  • Name
    art_style
    Type
    string
    ⚠ kullanımdan kaldırıldı
    varsayılan realistic
    Description

    Meshy-6 tarafından desteklenmez. Meshy-6 kullanan istekler art_style'ı yok sayar ve bazı kombinasyonlar hataya neden olabilir. Kullanılabilir değerler: realistic, sculpture.

    Sculpture stili kendi PBR haritaları kümesini oluşturduğu için, Sculpture stili kullanılırken enable_pbr false olarak ayarlanmalıdır.

  • Name
    moderation
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, girdi içeriği potansiyel olarak zararlı içerik açısından otomatik olarak taranır. Zararlı içerik tespit edilirse, görev oluşturma aşamasına geçmez.

    prompt'tan gelen metin taranacaktır.

  • Name
    target_formats
    Type
    string[]
    Description

    Çıktıya hangi 3D dosya formatlarının dahil edileceğini belirtir. Yalnızca istenen formatlar oluşturulur 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 oluşturulur. 3mf, yalnızca açıkça belirtildiğinde dahil edilir.

  • Name
    alpha_thumbnail
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, görev ayrıca preview'in şeffaf arka planlı (RGBA) bir sürümünü render eder ve bunu GET yanıtında alpha_thumbnail_url olarak döndürür. Mevcut thumbnail_url alanı değişmez.

  • Name
    auto_size
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, servis nesnenin gerçek dünyadaki yüksekliğini otomatik olarak tahmin etmek için AI görüşü kullanır ve modeli buna göre yeniden boyutlandırır. origin_at açıkça ayarlanmadığı sürece orijin varsayılan olarak bottom olacaktır.

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 Text to 3D görevinin id'sini içerir.

Hata Durumları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik parametre: Gerekli bir parametre (örneğin, prompt, mode) eksik.
    • Geçersiz parametre: art_style izin verilen değerlerden biri değil.
    • Prompt çok uzun: prompt, karakter sınırını aşıyor.
    • Low poly için desteklenmeyen model: ai_model: "meshy-6-lite", model_type: "lowpoly"'yi desteklemiyor.
    • Ultra için desteklenmeyen model: geometry_resolution, meshy-7.1 veya latest gerektirir.
  • 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 yeterli kredi yok.

  • Name
    429 - Too Many Requests
    Description

    Hız sınırınızı aştınız.

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/v2/text-to-3d

Bir Metinden 3D'ye Refine Görevi Oluşturma

Bu uç nokta, tamamlanmış bir önizleme ağına doku uygulayan bir Metinden 3D'ye refine görevi oluşturur. Başarılı bir önizleme görevinden alınan preview_task_id değerini sağlamanız gerekir. Bu, iki adımlı iş akışının ikinci adımıdır.

Parametreler

  • Name
    mode
    Type
    string
    Zorunlu
    Description

    Bir refine görevi oluştururken bu alan "refine" olarak ayarlanmalıdır.

  • Name
    preview_task_id
    Type
    string
    Zorunlu
    Description

    İlgili önizleme görevi kimliği.

    Verilen önizleme görevinin durumu SUCCEEDED olmalıdır.

  • Name
    enable_pbr
    Type
    boolean
    varsayılan false
    Description

    Temel renge ek olarak PBR haritaları (metalik, pürüzlülük, normal) oluşturur. ai_model değeri meshy-6 olduğunda, texture_resolution: 8k durumu hariç bir emisyon haritası da dahil edilir (bu durumda emisyon haritası üretilmez). meshy-6-lite, meshy-7.1 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. Yalnızca refine mode'unda geçerlidir.

    4k ve 8k, ai_model olarak meshy-6, meshy-7.1 veya latest gerektirir. 8k çözünürlükte 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. Her ikisi de ayarlandığında, texture_resolution önceliklidir.

  • Name
    texture_prompt
    Type
    string
    Description

    Dokulandırma sürecine yön vermek için ek bir metin prompt'u sağlayın. En fazla 800 karakter.

  • Name
    texture_image_url
    Type
    string
    Description

    Dokulandırma sürecine yön vermek için 2 boyutlu bir görsel sağlayın. Şu anda .jpg, .jpeg ve .png formatlarını destekliyoruz.

    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,<your base64-encoded image data>

    Orijinal varlık ile yüklenen görsel arasında önemli geometri farklılıkları varsa görsel dokulandırma optimum şekilde çalışmayabilir. Dokulandırma sürecine yön vermek için texture_image_url veya texture_prompt parametrelerinden yalnızca biri kullanılabilir. Her iki parametre de sağlanırsa, model varsayılan olarak texture_prompt kullanılarak dokulandırılır.

  • Name
    ai_model
    Type
    string
    varsayılan inherited from the preview task
    Description

    Refine işlemi için kullanılacak modelin kimliği.

    Kullanılabilir değerler:

    • 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.

    Önizleme görevi tarafından kullanılan modeli devralmak için bu parametreyi belirtmeyin; bu, bir önizlemeyi ve onun refine işlemini uçtan uca aynı modelde tutar. Bu devralmayı geçersiz kılmak için açık bir değer geçirin.

    Açık bir latest değeri burada, önizleme görevindeki ile tamamen aynı şekilde çözümlenir (şu anda Meshy 7.1), bu nedenle bir latest önizleme ve onun latest refine işlemi her zaman aynı doku modeline denk gelir.

  • Name
    moderation
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, girdi içeriği potansiyel olarak zararlı içerik açısından otomatik olarak taranır. Zararlı içerik tespit edilirse, görev üretim aşamasına geçmez.

    texture_prompt metni ve texture_image_url görseli her ikisi de taranır.

  • Name
    remove_lighting
    Type
    boolean
    varsayılan true
    Description

    Temel renk dokusundaki vurgu 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 etkilidir; diğer modeller bunu göz ardı eder.

  • Name
    target_formats
    Type
    string[]
    Description

    Çıktıya hangi 3D dosya formatlarının dahil edileceğini belirtir. Yalnızca istenen formatlar oluşturulup 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 hariç tüm formatlar oluşturulur. 3mf yalnızca açıkça belirtildiğinde dahil edilir.

  • Name
    alpha_thumbnail
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, görev ayrıca önizlemenin şeffaf arka planlı (RGBA) bir sürümünü oluşturur ve bunu GET yanıtında alpha_thumbnail_url olarak döndürür. Mevcut thumbnail_url alanı değişmez.

  • Name
    auto_size
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, servis nesnenin gerçek dünya yüksekliğini otomatik olarak tahmin etmek için AI görüsü kullanır ve modeli buna göre yeniden boyutlandırır. origin_at açıkça belirtilmedikçe orijin varsayılan olarak bottom olur.

Yalnızca şu durumlarda geçerli auto_size = true
  • Name
    origin_at
    Type
    string
    varsayılan bottom
    Description

    auto_size etkinken orijinin konumu.

    Kullanılabilir değerler: bottom, center.

Dönüş Değerleri

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

Hata Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemezdi. Yaygın nedenler:

    • Geçersiz görev kimliği: preview_task_id geçersiz veya mevcut değil.
    • Görev hazır değil: Önizleme görevi henüz başarılı olmadı.
    • Model uyuşmazlığı: Önizleme görevinin AI modeli, istenen refine modeliyle uyumlu değil.
  • 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 yeterli kredi yok.

  • Name
    404 - Not Found
    Description

    preview_task_id ile belirtilen önizleme görevi bulunamadı.

  • Name
    429 - Too Many Requests
    Description

    Hız sınırınızı aştınız.

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

Bir Metinden 3D'ye Görevini Getir

Bu uç nokta, geçerli bir görev id'si verildiğinde bir Metinden 3D'ye görevini almanızı sağlar. Metinden 3D'ye görev nesnesiyle hangi özelliklerin dahil olduğunu görmek için Metinden 3D'ye Görev Nesnesi bölümüne bakın.

Bu uç nokta hem preview hem de refine görevleri için çalışır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Alınacak Metinden 3D'ye görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, Metinden 3D'ye görev nesnesini içerir. Ayrıntılar için Metinden 3D'ye Görev Nesnesi bölümüne bakın.

Örnekler

ModeÖrnek Model
PreviewPreview model
RefineRefined model

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}
DELETE/openapi/v2/text-to-3d/:id

Bir Metinden 3D'ye Görevini Sil

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

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek Metinden 3D'ye görevinin ID'si.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan krediler 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ışma sırasında silmek hem kredileri hem de sonucu kaybetmenize neden 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öndürür.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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/v2/text-to-3d

Text to 3D Görevlerini Listele

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

Parametreler

  • Name
    page_num
    Type
    integer
    varsayılan 1
    Description

    Sayfalama için sayfa numarası.

  • Name
    page_size
    Type
    integer
    varsayılan 10
    Description

    Sayfa boyutu sınırı. İzin verilen maksimum 100 öğedir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralanacak alan.

    Kullanılabilir değerler:

    • +created_at: Oluşturulma zamanına göre artan sırada sırala.
    • -created_at: Oluşturulma zamanına göre azalan sırada sırala.

Dönüş Değerleri

The Text to 3D Task Objects sayfalanmış bir listesini döndürür.

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

Bir Metinden 3D'ye Görevini Akışla İletme

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Metinden 3D'ye görevi için gerçek zamanlı güncellemeleri akışla iletir.

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışla iletilecek Metinden 3D'ye görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

Metinden 3D'ye Görev Nesnelerinin Server-Sent Events olarak bir akışını 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/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

The Text to 3D Task Object

Text to 3D Task nesnesi, metin girdisinden bir 3D model oluşturmak için Meshy'nin takip ettiği bir iş birimidir. Text to 3D API'sinin iki aşaması vardır: preview ve refine. Preview aşaması sadece ağ içeren bir 3D model oluşturmak içindir, refine aşaması ise preview aşamasının sonucuna dayanarak dokulu bir 3D model oluşturmak içindir.

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 id'leri için k-sıralanabilir bir UUID kullansak da, id'nin formatı hakkında hiçbir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Text to 3D görevinin türü. Olası değerler, preview aşaması görevleri için text-to-3d-preview ve refine aşaması görevleri için text-to-3d-refine'dır.

  • 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 formata ait özellik atlanır.

    • Name
      glb
      Type
      string
      Description

      GLB dosyasına indirilebilir URL.

    • Name
      fbx
      Type
      string
      Description

      FBX dosyasına indirilebilir URL.

    • Name
      usdz
      Type
      string
      Description

      USDZ dosyasına indirilebilir URL.

    • Name
      obj
      Type
      string
      Description

      OBJ dosyasına indirilebilir URL.

    • Name
      mtl
      Type
      string
      Description

      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 üzerinden 3mf talep edildiğinde bulunur.

  • Name
    prompt
    Type
    string
    Description

    Görevi oluşturmak için kullanılan, değiştirilmemiş prompt budur.

  • Name
    negative_prompt
    Type
    string
    ⚠ kullanımdan kaldırıldı
    Description

    Geriye dönük uyumluluk için korunmaktadır. Bu alan, oluşturulan modeller üzerinde işlevsel bir etkiye sahip değildir.

  • Name
    art_style
    Type
    string
    ⚠ kullanımdan kaldırıldı
    Description

    Preview görevini oluşturmak için kullanılan, değiştirilmemiş art_style. Meshy-6 tarafından desteklenmemektedir.

  • Name
    texture_richness
    Type
    string
    ⚠ kullanımdan kaldırıldı
    Description

    Geriye dönük uyumluluk için korunmaktadır. Bu alan, oluşturulan modeller üzerinde işlevsel bir etkiye sahip değildir.

  • Name
    texture_prompt
    Type
    string
    Description

    Refine aşaması sırasında dokulama işlemine yön vermek için sağlanan ek metin promptu.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ kullanımdan kaldırıldı
    Description

    Kullanımdan kaldırıldı; bunun yerine geometry_resolution alanını okuyun.

  • Name
    geometry_resolution
    Type
    string
    Description

    Preview görevinin çalıştığı Ultra katmanı (2k veya 4k); standard için atlanır.

  • Name
    texture_image_url
    Type
    string
    Description

    Dokulama işlemine yön vermek için kullanılan doku görseline indirilebilir URL.

  • Name
    thumbnail_url
    Type
    string
    Description

    Model dosyasının küçük resmine indirilebilir URL.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    thumbnail_url'in şeffaf arka planlı (RGBA) sürümüne indirilebilir URL. Yalnızca görev alpha_thumbnail: true ile oluşturulduğunda ve şeffaf önizleme başarıyla oluşturulduğunda bulunur; aksi halde bu alan atlanır.

  • Name
    video_url
    Type
    string
    ⚠ kullanımdan kaldırıldı
    Description

    Önizleme videosuna indirilebilir URL. Gelecekteki bir sürümde kaldırılacaktır.

  • Name
    progress
    Type
    integer
    Description

    Görevin ilerlemesi. Görev henüz başlamadıysa, bu özellik 0 olacaktır. Görev başarılı olduğunda, bu değer 100 olacaktır.

  • Name
    started_at
    Type
    timestamp
    Description

    Görevin başladığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa, bu özellik 0 olacaktır.

    Bir zaman damgası, RFC 3339 standardına uygun olarak, 1 Ocak 1970 UTC'den itibaren geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma günü GMT 12:00:00, 1693569600000 olarak temsil edilir. Bu, Meshy API'sindeki 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
    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 nesnelerinin bir dizisi. Normalde bu, yalnızca bir doku URL nesnesi içerir. Her doku URL'sinin aşağıdaki özellikleri vardır:

    • Name
      base_color
      Type
      string
      Description

      Ana 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 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 ayrıntıları. Tam task_error nesne referansı için Hatalar sayfasına 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 bulunur. FAILED görevler için 0 döner (başarısızlık durumunda kredi geri ödenir).

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}