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. İlk olarak, şekli değerlendirebilmeniz için dokusuz bir 3D ağ oluşturmak üzere bir preview görevi (mode: "preview") oluşturun. Ardından, tamamlanan önizlemenin görev kimliğini ağa doku uygulamak için bir refine görevine (mode: "refine") geçirin. Her iki adım da aynı uç noktayı paylaşır.

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

Metinden 3D'ye Önizleme Görevi Oluşturma

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

Görev arka planda çalışır. Genellikle ne kadar sürdüğü hakkında bilgi için İşlem Süreleri sayfasına bakın.

Parametreler

Name
mode
Type
string
Zorunlu
Description
Bir önizleme 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. 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: ai_model (meshy-t2) ile Smart Topology modelini seçin.
- lowpoly (kullanımdan kaldırıldı, 30 Ekim 2026'da hizmetten kaldırılacak): Daha temiz poligonlar için optimize edilmiş low-poly ağ oluşturur. Bunun yerine Meshy T2'yi öneriyoruz: meshy-t2 ile smart-topology.
smart-topology seçildiğinde should_remesh ve decimation_mode yok sayılır ve yalnızca topology: triangle kabul edilir.
lowpoly, 30 Ekim 2026 tarihinde hizmetten kaldırılacaktır. Bu tarihten sonra model_type: "lowpoly" içeren istekler hata döndürecektir. Meshy T2'ye geçmenizi öneririz (ai_model: "meshy-t2" ile model_type: "smart-topology"). 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üzey sayısı.
Name
geometry_resolution
Type
string
varsayılan standard
Description
Geometri oluşturma aşaması. 2k, Ultra aşamasını 2048³'te çalıştırır; 4k 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ğ 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: Dörtgen ağırlıklı bir ağ oluşturur.
- triangle: Azaltılmış bir üçgen ağ oluşturur.
Smart Topology çıktısı yalnızca üçgendir. ai_model: meshy-t2 ile birlikte quad istemek hata döndürür.
Name
decimation_mode
Type
integer
Description
Bir poligon sayısı seviyesi ayarlayarak uyarlanabilir azaltmayı etkinleştirin. Ayarlandığında, target_polycount yok sayılır.
Kullanılabilir değerler:
- 1: Uyarlanabilir — ultra poligon sayısı.
- 2: Uyarlanabilir — yüksek poligon sayısı.
- 3: Uyarlanabilir — orta poligon sayısı.
- 4: Uyarlanabilir — düşük poligon sayısı.

Name
target_polycount
Type
integer
Description
Çıktıdaki hedef poligon (yüzey) sayısı. Gerçek sayı, geometriye bağlı olarak hedeften sapabilir.
target_polycount, iki bağımsız durumda etkili olur:
- Yeniden ağ — bir standard modelde should_remesh: true ile. Ağ, yaklaşık olarak bu sayıya yeniden ağlanır (azaltılır). Aralık 100 ile 300.000 arası, varsayılan 30.000. decimation_mode ayarlanmışsa, öncelik ona aittir 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 gerekmez. 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 işlemi sırasında simetri davranışını kontrol eder.
Geçerli değerler:
- off: Simetriyi devre dışı bırakır.
- auto: Giriş geometrisine dayanarak 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 hatalara neden olabilir. Kullanılabilir değerler: realistic, sculpture.
Sculpture tarzı kendi PBR haritaları setini oluşturduğundan, Sculpture tarzı kullanılırken enable_pbr'nin false olarak ayarlanması gerekir.
Name
moderation
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, giriş içeriği potansiyel olarak zararlı içerik açısından otomatik olarak taranır. Zararlı içerik tespit edilirse, görev 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 önizlemenin ş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şmeden kalır.
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üşü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 Metinden 3D'ye görevinin id'sini içerir.

Hata Modları

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 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 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ştur

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.

Görev arka planda çalışır. Genellikle ne kadar sürdüğü hakkında bilgi için İşlem Süreleri sayfasına bakın.

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 hariç (bu durumda emisyon haritası üretilmez) bir emisyon haritası da dahil edilir. meshy-6-lite, meshy-7.1 ve latest emisyon haritası üretmez; ai_model ayarlanmamış bir meshy-t2 önizlemesinin refine işlemi de ü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'u için 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. İkisi birden ayarlandığında texture_resolution önceliklidir.
Name
texture_prompt
Type
string
Description
Dokulandırma sürecine rehberlik etmek için ek bir metin promptu sağlayın. En fazla 800 karakter.
Name
texture_image_url
Type
string
Description
Dokulandırma sürecine rehberlik etmek için 2 boyutlu bir görsel sağlayın. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.
Maksimum dosya boyutu: 20 MB.
Görseli sağlamanın iki yolu vardır:
- Herkese açık erişilebilir URL: Herkese açık internetten erişilebilen bir URL
- Data URI: Görselin base64 ile kodlanmış bir data URI'si. Bir data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>
Orijinal asset ile yüklenen görsel arasında önemli geometri farklılıkları varsa görsel dokulandırma en iyi şekilde çalışmayabilir. Dokulandırma sürecine rehberlik etmek için texture_image_url veya texture_prompt parametrelerinden yalnızca biri kullanılabilir. Her iki parametre de sağlanırsa, modeli dokulandırmak için varsayılan olarak texture_prompt kullanılacaktır.
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 atlayın; bu, bir önizlemeyi ve onun refine işlemini baştan sona 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 tam olarak önizleme görevinde olduğu gibi çözümlenir (şu anda Meshy 7.1), bu nedenle bir latest önizlemesi ve onun latest refine işlemi her zaman aynı doku modelinde buluşur.
Name
moderation
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, girdi içeriği otomatik olarak potansiyel olarak zararlı içerik açısından taranır. Zararlı içerik tespit edilirse görev oluşturma aşamasına geçmez.
Hem texture_prompt metni hem de texture_image_url görseli taranacaktır.
Name
remove_lighting
Type
boolean
varsayılan true
Description
Temel renk dokusundan vurguları ve gölgeleri kaldırarak, özel aydınlatma kurulumlarında daha iyi çalışan daha temiz bir sonuç üretir.
Yalnızca ai_model değeri meshy-6 olduğunda etkili olur. meshy-7.1 ve latest bu parametreyi kabul eder ancak yok sayar; ai_model ayarlanmamış bir meshy-t2 önizlemesinin refine işlemi de aynı şekilde davranır. Bunu meshy-6-lite ile ayarlamak hata döndürür.
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ü 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, hizmet nesnenin gerçek dünyadaki 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ığı sürece 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 Metinden 3D'ye görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. 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 yapay zeka modeli, istenen refine modeliyle uyumsuz.
- remove_lighting için desteklenmeyen model: remove_lighting, ai_model: "meshy-6-lite" ile birlikte ayarlanmış.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yetersiz kredi.
Name
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 Al

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 birlikte hangi özelliklerin yer aldığını 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
Preview
Refine

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 kimliği.

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şlatmış olduğu bir görev için krediler iade edilemez, bu nedenle ç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.

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

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundayken ise 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, Text to 3D 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 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ıralar.
- -created_at: Oluşturulma zamanına göre azalan sırada sıralar.

Döndürülenler

Text to 3D Görev Nesneleri'nin 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

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

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 izlenecek Metinden 3D'ye görevi için benzersiz tanımlayıcı.

Döndürülenler

Metinden 3D'ye Görev Nesneleri'nin 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
}

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 preview ve refine olmak üzere iki aşaması vardır. Preview aşaması yalnızca 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 kimlikleri için k-sıralanabilir bir UUID kullansak da, id'nin biçimi hakkında herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Metinden 3D'ye 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 biçim oluşturulmamışsa, bu biçime ait özellik boş bir dize döndürülmek yerine 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 aracılığıyla 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ın oluşturulan modeller üzerinde işlevsel bir etkisi yoktur.
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 desteklenmez.
Name
texture_richness
Type
string
⚠ kullanımdan kaldırıldı
Description
Geriye dönük uyumluluk için korunmaktadır. Bu alanın oluşturulan modeller üzerinde işlevsel bir etkisi yoktur.
Name
texture_prompt
Type
string
Description
Refine aşamasında dokulama sürecine rehberlik etmek için sağlanan ek metin prompt'u.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
Description
Kullanımdan kaldırıldı; bunun yerine geometry_resolution değerini okuyun.
Name
geometry_resolution
Type
string
Description
Preview görevinin çalıştığı Ultra katmanı (2k veya 4k); standard için atlanır.
Name
texture_image_url
Type
string
Description
Dokulama sürecine rehberlik etmek için kullanılan doku görüntüsüne 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'nin ş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 takdirde 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 olur. Görev başarılı olduğunda bu değer 100 olur.
Name
started_at
Type
timestamp
Description
Görevin başlatıldığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa bu özellik 0 olur.
Bir zaman damgası, RFC 3339 standardını takip ederek 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma, GMT saatiyle 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 olur.
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'si aşağıdaki özelliklere sahiptir:
- Name
  base_color
  Type
  string
  Description
  Temel renk haritası görüntüsüne indirilebilir URL.
- Name
  metallic
  Type
  string
  Description
  Metalik harita görüntüsüne indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa, bu özellik atlanır.
- Name
  normal
  Type
  string
  Description
  Normal harita görüntüsüne 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örüntüsüne indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa, bu özellik atlanır.
- Name
  emission
  Type
  string
  Description
  Yayılım haritası görüntüsüne indirilebilir URL.
  Görev enable_pbr: false ile oluşturulduysa, ai_model değeri meshy-6-lite, meshy-7.1 veya latest ise ya da görev ai_model ayarlanmadan bir meshy-t2 preview'ını refine ediyorsa, 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öndürür (başarısızlık durumunda krediler iade edilir).

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
}