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şlamanız için gereken tüm bilgileri bulacaksınız.

Metinden 3D'ye, iki aşamalı bir iş akışı kullanır. İlk olarak, şekli değerlendirebilmeniz için dokusuz bir 3D ağ oluşturmak amacıyla bir önizleme görevi (mode: "preview") oluşturun. Ardından, tamamlanan önizlemenin görev kimliğini bir ince ayar görevine (mode: "refine") geçirerek ağa doku uygulayın. Her iki adım da aynı uç noktayı paylaşır.

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

Text to 3D Ön İzleme Görevi Oluştur

Bu uç nokta, bir metin prompt'undan dokusuz bir 3D ağ (yalnızca geometri) oluşturan bir Text to 3D ön izleme görevi oluşturur. Bu, iki adımlı iş akışının ilk adımıdır. Ön izleme başarılı olduktan sonra, dokulandırma için bir düzeltme (refine) görevi oluşturmak üzere döndürülen görev kimliğini kullanın. Yanıt şemasının tamamı için Text to 3D Görev Nesnesi bölümüne bakın.

Parametreler

  • Name
    mode
    Type
    string
    Zorunlu
    Description

    Bir ön izleme 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 açıklayın. En fazla 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: ai_model (meshy-t2) ile Smart Topology modelini seçin.
    • lowpoly (kullanımdan kaldırıldı): Daha temiz poligonlar için optimize edilmiş low-poly ağ oluşturur. 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 kimliği. Kullanılabilir değerler model_type'a bağlıdır.

    Standart oluşturma (model_type: standard):

    • meshy-5, meshy-6, meshy-7, latest (Meshy 7)

    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üzey sayısı.
  • Name
    ultra_mode
    Type
    boolean
    varsayılan false
    Description

    Daha ince yüzey detayına sahip, daha yüksek doğrulukta geometri için Ultra oluşturmayı etkinleştirir. Oluşturma daha uzun sürer ve 5 kredi ekler.

    Yalnızca ai_model değeri meshy-7 (veya latest) olduğunda ve yalnızca preview modunda desteklenir.

  • Name
    should_remesh
    Type
    boolean
    varsayılan false (meshy-6, meshy-7), 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

    Oluşturulan modelin topology'sini belirtin.

    Kullanılabilir değerler:

    • quad: Dörtgen ağırlıklı bir ağ oluşturur.
    • triangle: Sadeleştirilmiş (decimated) bir üçgen ağ oluşturur.

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

  • Name
    decimation_mode
    Type
    integer
    Description

    Bir poligon sayısı seviyesi belirleyerek uyarlanabilir sadeleştirmeyi (decimation) 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
    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ğ (Remesh) — bir standard model üzerinde should_remesh: true ile. Ağ, yaklaşık bu sayıya yeniden ağlanır (sadeleştirilir). Aralık 100 ile 300.000 arası, varsayılan 30.000. decimation_mode ayarlanmışsa, öncelik onda olur ve target_polycount yok sayılır.
    • Smart Topology — model_type: smart-topology ve ai_model: meshy-t2 ile. Model doğrudan bu yüzey sayısında oluşturulur; yeniden ağ çalışmaz ve should_remesh gerekli değildir. Aralık 100 ile 15.000 arası, varsayılan 4.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 oluşturma sürecinde simetri davranışını kontrol eder.

    Geçerli değerler:

    • off: Simetriyi devre dışı bırakır.
    • auto: Girdi 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 poz mode'unu 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ğundan, Sculpture stili kullanılırken enable_pbr değeri 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 içindeki 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 kısaltabilir. 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 ön izlemenin ş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, hizmet nesnenin gerçek dünyadaki yüksekliğini otomatik olarak tahmin etmek için yapay zeka görüsünü 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 Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik parametre: Gerekli bir parametre (örn. 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.
  • 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/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 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",
  "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 Text to 3D Refine Görevi Oluşturma

Bu uç nokta, tamamlanmış bir preview ağına doku uygulayan bir Text to 3D refine görevi oluşturur. Başarılı bir preview 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 preview görevinin id'si.

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

  • Name
    enable_pbr
    Type
    boolean
    varsayılan false
    Description

    Temel renge ek olarak PBR haritaları (metallic, roughness, normal) üretir. ai_model değeri meshy-6 olduğunda, texture_resolution: 8k hariç, bir emission haritası da dahil edilir (8k'de emission haritası üretilmez). meshy-7 (ve latest) emission haritası üretmez.

  • Name
    texture_resolution
    Type
    string
    varsayılan 2k
    Description

    Temel renk dokusu çö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 için geçerlidir.

    4k ve 8k, ai_model olarak meshy-6, meshy-7 veya latest gerektirir. 8k'de emission 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" değerine eşdeğerdir. Her ikisi de ayarlandığında texture_resolution önceliklidir.

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    texture_image_url
    Type
    string
    Description

    Dokulandırma sürecini yönlendirmek için 2 boyutlu bir görüntü sağlayın. Şu anda .jpg, .jpeg ve .png biçimlerini destekliyoruz.

    Görüntüyü sağlamanın iki yolu vardır:

    • Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL
    • Data URI: Görüntünün base64 ile kodlanmış bir data URI'si. Data URI örneği: data:image/jpeg;base64,<your base64-encoded image data>

    Orijinal asset ile yüklenen görüntü arasında önemli geometri farklılıkları varsa görüntü dokulandırma optimal şekilde çalışmayabilir. Dokulandırma sürecini yönlendirmek 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 latest
    Description

    Refine için kullanılacak modelin ID'si. Kullanılabilir değerler: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    latest, burada preview görevindeki ile tamamen aynı şekilde çözümlenir (şu anda Meshy 7), böylece bir latest preview ve buna karşılık gelen latest refine her zaman aynı doku modelinde buluşur.

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

    Hem texture_prompt metni hem de texture_image_url görüntüsü taranır.

  • Name
    remove_lighting
    Type
    boolean
    varsayılan true
    Description

    Temel renk dokusundan vurgu ve gölgeleri kaldırarak özel aydınlatma kurulumları altında daha iyi çalışan daha temiz bir sonuç üretir.

    Yalnızca ai_model değeri meshy-6 olduğunda etkili olur. meshy-7 (ve latest) üzerinde parametre kabul edilir ancak yok sayılır.

  • Name
    target_formats
    Type
    string[]
    Description

    Çıktıya hangi 3D dosya biçimlerinin dahil edileceğini belirtir. Yalnızca istenen biçimler üretilir ve döndürülür; bu da görev tamamlanma süresini azaltabilir. Belirtilmediğinde, desteklenen tüm biçimler dahil edilir.

    Kullanılabilir değerler: glb, obj, fbx, stl, usdz, 3mf

    Belirtilmediğinde, 3mf hariç tüm biçimler üretilir. 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'ın ş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ünya yüksekliğini otomatik olarak tahmin etmek için yapay zeka görüşünü kullanır ve modeli buna göre yeniden boyutlandırır. origin_at açıkça ayarlanmadıkça 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 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 değerini içerir.

Hata Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Geçersiz görev ID'si: preview_task_id geçersiz veya mevcut değil.
    • Görev hazır değil: Preview görevi henüz başarılı olmadı.
    • Model uyuşmazlığı: Preview görevinin yapay zeka modeli, istenen refine modeliyle uyumsuz.
  • 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
    404 - Not Found
    Description

    preview_task_id tarafından belirtilen preview 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

Metinden 3D'ye Görev Alma

Bu uç nokta, geçerli bir görev id verildiğinde bir Metinden 3D'ye görevi almanıza olanak tanır. 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 önizleme hem de iyileştirme görevleri için çalışır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Alınacak Metinden 3D'ye görevin benzersiz tanımlayıcısı.

Dönenler

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

ModÖrnek Model
ÖnizlemeÖnizleme modeli
İyileştirmeİyileştirilmiş model

İstek

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

Yanıt

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

Metinden 3D'ye Görev Silme

Bu uç nokta, bir Metinden 3D'ye görevini, ilgili tüm modeller ve veriler dahil olmak üzere 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.

Dönen Değerler

Başarı durumunda 200 OK döner.

İstek

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

Yanıt

// Returns 200 Ok on success.
GET/openapi/v2/text-to-3d

Metinden 3D'ye Görevleri 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 değer 50 öğedir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralama yapılacak alan.

    Mevcut değerler:

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

Dönen Değerler

Metinden 3D'ye Görev Nesneleri listesini sayfalı olarak döndürür.

İstek

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

Yanıt

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

Metinden 3D'ye Görevini Yayınla

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Metinden 3D'ye görevi için gerçek zamanlı güncellemeler yayınlar.

Parametreler

  • Name
    id
    Type
    path
    Description

    Yayınlanacak Metinden 3D'ye görevinin benzersiz tanımlayıcısı.

Dönen Değerler

Server-Sent Events olarak Metinden 3D'ye Görev Nesneleri akışını döndürür.

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

İstek

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

Yanıt Akışı

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

Metinden 3D'ye Görev Nesnesi

Metinden 3D'ye Görev nesnesi, Meshy'nin bir metin girdisinden 3D model oluşturmak için takip ettiği bir iş birimidir. Metinden 3D'ye API'sinin iki aşaması vardır: önizleme ve iyileştirme. Önizleme aşaması, yalnızca ağ içeren bir 3D model oluşturmak içindir ve iyileştirme aşaması, önizleme aşamasının sonucuna dayalı olarak 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ı. Görev kimlikleri için k-sıralanabilir UUID kullanıyoruz, ancak kimliğin formatı hakkında herhangi bir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

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

  • Name
    model_urls
    Type
    object
    Description

    Meshy tarafından üretilen dokulu 3D model dosyasının indirilebilir URL'si. Bir format üretilmediğinde, boş bir dize döndürmek yerine o formatın özelliği atlanır.

    • Name
      glb
      Type
      string
      Description

      GLB dosyasının indirilebilir URL'si.

    • Name
      fbx
      Type
      string
      Description

      FBX dosyasının indirilebilir URL'si.

    • Name
      usdz
      Type
      string
      Description

      USDZ dosyasının indirilebilir URL'si.

    • Name
      obj
      Type
      string
      Description

      OBJ dosyasının indirilebilir URL'si.

    • Name
      mtl
      Type
      string
      Description

      MTL dosyasının indirilebilir URL'si.

    • Name
      stl
      Type
      string
      Description

      STL dosyasının indirilebilir URL'si.

    • Name
      3mf
      Type
      string
      Description

      3MF dosyasının indirilebilir URL'si. Sadece 3mf target_formats aracılığıyla istendiğinde mevcut olur.

  • Name
    prompt
    Type
    string
    Description

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

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

    Geriye dönük uyumluluk için korunmuştur. Bu alanın üretilen modeller üzerinde işlevsel bir etkisi yoktur.

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

    Önizleme görevini oluşturmak için kullanılan değiştirilmemiş art_style. Meshy-6 tarafından desteklenmez.

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

    Geriye dönük uyumluluk için korunmuştur. Bu alanın üretilen modeller üzerinde işlevsel bir etkisi yoktur.

  • Name
    texture_prompt
    Type
    string
    Description

    İyileştirme aşamasında dokulama sürecini yönlendirmek için sağlanan ek metin prompt.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Önizleme görevi ultra_mode ile oluşturulduğunda yankılanır. Sadece meshy-7 (veya latest) önizleme görevleri için ultra_mode açıkça ayarlandığında mevcut olur; aksi takdirde atlanır.

  • Name
    texture_image_url
    Type
    string
    Description

    Dokulama sürecini yönlendirmek için kullanılan doku görüntüsünün indirilebilir URL'si.

  • Name
    thumbnail_url
    Type
    string
    Description

    Model dosyasının küçük resim görüntüsünün indirilebilir URL'si.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    thumbnail_url'un şeffaf arka planlı (RGBA) bir sürümünün indirilebilir URL'si. Sadece görev alpha_thumbnail: true ile oluşturulduğunda ve şeffaf önizleme başarıyla render edildiğinde mevcut olur; aksi takdirde bu alan atlanır.

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

    Önizleme videosunun indirilebilir URL'si. Gelecek 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ıyla tamamlandığında, bu 100 olur.

  • Name
    started_at
    Type
    timestamp
    Description

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

    Bir zaman damgası, 1 Ocak 1970 UTC'den itibaren geçen milisaniye sayısını temsil eder ve RFC 3339 standardını takip eder. Örneğin, Cuma, 1 Eylül 2023 12:00:00 PM 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 zaman damgası, milisaniye cinsinden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı zamanın zaman damgası, milisaniye cinsinden. 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'den biridir.

  • Name
    texture_urls
    Type
    array
    Description

    Görevden üretilen doku URL nesnelerinin bir dizisi. Normalde bu sadece 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örüntüsünün indirilebilir URL'si.

    • Name
      metallic
      Type
      string
      Description

      Metalik harita görüntüsünün indirilebilir URL'si.

      Görev enable_pbr: false ile oluşturulduysa, bu özellik atlanır.

    • Name
      normal
      Type
      string
      Description

      Normal harita görüntüsünün indirilebilir URL'si.

      Görev enable_pbr: false ile oluşturulduysa, bu özellik atlanır.

    • Name
      roughness
      Type
      string
      Description

      Pürüzlülük haritası görüntüsünün indirilebilir URL'si.

      Görev enable_pbr: false ile oluşturulduysa, bu özellik atlanır.

    • Name
      emission
      Type
      string
      Description

      Emisyon haritası görüntüsünün indirilebilir URL'si.

      Görev enable_pbr: false ile oluşturulduysa veya ai_model meshy-5 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 ise anlamlıdır.

  • Name
    task_error
    Type
    object
    Description

    Başarısız görevler için hata detayları. Tam task_error nesne 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 mevcut olur. FAILED görevler için 0 döner (başarısızlık durumunda krediler iade edilir).

Örnek Metinden 3D'ye Görev Nesnesi

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