Metinden 3D'ye API

Kendi uygulamanızda metin istemlerinden 3D modeller oluşturun.

Metinden 3D'ye iki adımda çalışır. İlk olarak, şekli kontrol edebilmeniz için dokusuz bir 3D ağ oluşturmak üzere bir preview görevi oluşturun (mode: "preview"). Ardından, ağa doku uygulamak için başarılı önizlemenin görev kimliğini bir refine görevine gönderin (mode: "refine"). Her iki adım da aynı uç noktayı kullanır.

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

Bir Text to 3D preview görevi oluşturma

Bir metin promptundan dokusuz bir 3D ağ (yalnızca geometri) oluşturan bir Metinden 3D'ye preview görevi oluşturur. Bu, iki adımlı iş akışının ilk adımıdır. Preview başarılı olduktan sonra, ağa doku kazandırmak için görev kimliğini bir refine görevinde gönderin. Bkz. Bir Text to 3D refine görevi oluşturma. Yanıtın tam şeması için bkz. Text to 3D görev nesnesi.

Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü için bkz. İşleme süreleri.

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

Parametreler

Name
mode
Type
string
Zorunlu
Description
İki adımlı iş akışının adımı. Bir preview görevi oluşturmak için preview gönderin.
Name
prompt
Type
string
Zorunlu
Description
Oluşturulacak nesneyi açıklayan, en fazla 800 karakter uzunluğunda metin. Daha uzun metin 400 döndürür.
Name
model_type
Type
string
varsayılan standard
Description
Oluşturulacak 3D ağın türü.
Kullanılabilir değerler:
- standard: yüksek detaylı bir 3D ağ
- smart-topology: bir Smart Topology ağı. Modeli ai_model ile seçin (meshy-t2 veya meshy-t2.5).
smart-topology ile Meshy, should_remesh ve decimation_mode parametrelerini yok sayar ve yalnızca topology: triangle kabul eder.
Name
ai_model
Type
string
varsayılan latest
Description
3D modeli oluşturan AI modeli. Kullanılabilir değerler model_type'a bağlıdır.
Standart modeller (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 gönderin
Smart Topology modelleri (model_type: smart-topology):
- meshy-t2: daha temiz topology, doğal olarak ayrılmış parçalar, triangle çıktı ve target_polycount ile ayarladığınız bir yüz sayısı
- meshy-t2.5 (varsayılan): oyun asset'leri için daha keskin detay, triangle çıktı ve target_polycount ile ayarladığınız bir yüz sayısı
Name
geometry_resolution
Type
string
varsayılan standard
Description
Geometri oluşturma aşaması. Yalnızca preview görevleri için geçerlidir. Bu parametreyle yapılan bir refine 400 döndürür.
Kullanılabilir değerler:
- standard
- 2k: Ultra aşamasını 2048³ çözünürlükte çalıştırır
- 4k: Ultra aşamasını, daha ince yüzey detayı için 4096³ çözünürlükte çalıştırır
2k için meshy-7.1, latest veya kullanımdan kaldırılan meshy-7 gerekir. 4k için meshy-7.1 veya latest gerekir. Diğer modeller 400 döndürür.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine geometry_resolution gönderin. ultra_mode: true, geometry_resolution: "2k" ile aynıdır.
Name
should_remesh
Type
boolean
varsayılan true (meshy-6-lite), false (other models)
Description
Oluşturmadan sonra modelin yeniden ağ haline getirilip getirilmeyeceği. En yüksek kaliteli 3D model için false gönderin.

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

Name
topology
Type
string
varsayılan triangle
Description
Yeniden ağ haline getirilen modelin yüz türü.
Kullanılabilir değerler:
- quad: quad ağırlıklı bir ağ
- triangle: küçültülmüş bir triangle ağ
Smart Topology çıktısı yalnızca triangle'dır. ai_model meshy-t2 veya meshy-t2.5 ile quad göndermek 400 döndürür.
Name
decimation_mode
Type
integer
Description
Seviyeye göre uyarlanabilir yüz sayısı. Bunu ayarladığınızda Meshy, target_polycount'u yok sayar.
Kullanılabilir değerler:
- 1: ultra
- 2: yüksek
- 3: orta
- 4: düşük

Name
target_polycount
Type
integer
Description
Hedeflenen yüz sayısı. Sonuç, geometriye bağlı olarak hedeften farklı olabilir. Bu, iki ayrı durumda geçerlidir:
- Yeniden ağ: bir standard modelde should_remesh: true ile. Meshy, ağı yaklaşık bu sayıya göre yeniden ağ haline getirir (küçültür). decimation_mode ayarlarsanız, Meshy bunu kullanır ve target_polycount'u yok sayar.
- Smart Topology: model_type: smart-topology ve ai_model meshy-t2 veya meshy-t2.5 ile. Meshy, modeli doğrudan bu yüz sayısında oluşturur. Herhangi bir yeniden ağ işlemi çalışmaz ve should_remesh'e ihtiyacınız yoktur.
Aşağıdaki tabloda her durum için aralık ve varsayılan değer gösterilmektedir:
Durum Aralık Varsayılan
Yeniden ağ 100 ile 300000 arası 30000
meshy-t2 100 ile 15000 arası 4000
meshy-t2.5 100 ile 30000 arası 15000
Aralık dışındaki bir değer 400 döndürür.

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

Name
symmetry_mode
Type
string
⚠ kullanımdan kaldırıldı
varsayılan auto
Description
Bunu kullanmayın. Bu parametre çıktıyı etkilemez.
Kullanılabilir değerler:
- off: simetriyi devre dışı bırakır
- auto: giriş geometrisine göre simetri uygular
- on: oluşturma sırasında simetriyi zorunlu kılar
Name
pose_mode
Type
string
varsayılan ""
Description
Oluşturulan modelin pozu.
Kullanılabilir değerler:
- a-pose: bir A pozu
- t-pose: bir T pozu
- "" (boş dize): belirli bir poz yok
Name
is_a_t_pose
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine pose_mode gönderin. Modelin A pozunda mı yoksa T pozunda mı oluşturulacağı.
Name
art_style
Type
string
⚠ kullanımdan kaldırıldı
varsayılan realistic
Description
Bunu kullanmayın. Meshy bunu yok sayar.
Name
moderation
Type
boolean
varsayılan false
Description
Oluşturmadan önce prompt'un zararlı içerik açısından taranıp taranmayacağı. Meshy zararlı içerik tespit ederse, istek 400 döndürür ve Meshy bir görev oluşturmaz.
Name
target_formats
Type
string[]
Description
Oluşturulacak dosya formatları. Meshy yalnızca bu formatları oluşturur ve döndürür; bu da görevi kısaltabilir. Bunu belirtmezseniz, Meshy yalnızca talep ettiğinizde oluşturduğu 3mf hariç tüm formatları oluşturur.
Kullanılabilir değerler:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
varsayılan false
Description
Görevi aldığınızda alpha_thumbnail_url içinde döndürülen, şeffaf arka planlı (RGBA) bir preview'in da oluşturulup oluşturulmayacağı. thumbnail_url değişmez.
Name
auto_size
Type
boolean
varsayılan false
Description
Nesnenin gerçek dünyadaki yüksekliğinin AI görüşüyle tahmin edilip edilmeyeceği ve modelin buna göre yeniden boyutlandırılıp boyutlandırılmayacağı. origin_at ayarlamadığınız sürece Meshy, orijini alta yerleştirir.

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

Name
origin_at
Type
string
varsayılan bottom
Description
Modelin orijininin nereye yerleştirileceği, bottom veya center.

Dönüş değerleri

Yanıtın result alanı, yeni Text to 3D görevinin kimliğini tutar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik parametre: prompt veya mode gibi gerekli bir parametre eksik.
- Prompt çok uzun: prompt karakter sınırını aşıyor.
- Ultra için desteklenmeyen model: geometry_resolution, 2k veya 4k değerinde ve ai_model bunu çalıştıramıyor.
İsteği düzeltin, ardından yeniden gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı. Kredi bakiyenizi kontrol edin, ardından yeniden deneyin.
- Ücretsiz plan: Bir görev oluşturmak için ücretli bir plan gerekir. Planınızı abonelik ayarlarınızdan yükseltin, ardından yeniden deneyin.
Name
403 - Forbidden
Description
İçerik moderasyonu, prompt'u veya bir giriş görselini engelledi. Girişi değiştirin, ardından yeniden deneyin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyin, ardından yeniden deneyin. Bkz. Hız sınırları.

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

Bir Metinden 3D'ye refine görevi oluşturun

Tamamlanmış bir preview görevinin ağını dokulandıran bir Metinden 3D'ye refine görevi oluşturur. Başarılı bir preview görevinin ID'sini preview_task_id olarak gönderin. Bkz. Bir Metinden 3D'ye preview görevi oluşturun. Bu, iki adımlı iş akışının ikinci adımıdır.

Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü için bkz. İşlem süreleri.

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

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parametreler

Name
mode
Type
string
Zorunlu
Description
İki adımlı iş akışının adımı. Bir refine görevi oluşturmak için refine gönderin.
Name
preview_task_id
Type
string
Zorunlu
Description
Dokulandırılacak preview görevinin ID'si. Preview görevinin durumu SUCCEEDED olmalıdır.
Name
enable_pbr
Type
boolean
varsayılan false
Description
Temel renkle birlikte PBR haritalarının da (metalik, pürüzlülük ve normal) oluşturulup oluşturulmayacağı.
ai_model meshy-6 ile Meshy, texture_resolution: 8k hariç olmak üzere bir emisyon haritası da oluşturur. meshy-6-lite, meshy-7, meshy-7.1 ve latest bir emisyon haritası oluşturmaz. ai_model ayarlamayan bir meshy-t2 veya meshy-t2.5 preview'ının refine'ı da oluşturmaz. ai_model: meshy-n1 ile true değeri 400 döndürür.
Name
texture_resolution
Type
string
varsayılan 2k
Description
Temel renk dokusunun çözünürlüğü. Yalnızca refine görevleri için geçerlidir. Bu parametreyle bir preview 400 döndürür.
Kullanılabilir değerler:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Daha yüksek çözünürlükler daha fazla yüzey detayı yakalar. 4k ve 8k, ai_model olarak meshy-6, meshy-7.1 veya latest gerektirir. meshy-n1 ile 400 döndürür. 8k çözünürlükte Meshy bir emisyon haritası oluşturmaz.
Name
hd_texture
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
Bunun yerine texture_resolution gönderin. hd_texture: true, texture_resolution: "4k" ile aynıdır. İkisini birden gönderirseniz Meshy texture_resolution'ı kullanır.
Name
texture_prompt
Type
string
Description
Dokulandırmaya yön veren, en fazla 800 karakterlik metin. Daha uzun metin 400 döndürür. texture_prompt veya texture_image_url gönderin, ikisini birden değil. İkisini birden gönderirseniz Meshy texture_prompt'u kullanır. ai_model: meshy-n1 ile gönderilmesi 400 döndürür.
Name
texture_image_url
Type
string
Description
Dokulandırmaya yön veren, genel bir URL veya base64 ile kodlanmış bir data URI olarak 2D görsel; örneğin data:image/jpeg;base64,<your base64-encoded image data>.
Görsel, en fazla 20 MB boyutunda, her kenarı en az 32 piksel ve en fazla 178.956.970 piksel (genişlik × yükseklik) olan bir .jpg, .jpeg, .png veya .webp dosyası olmalıdır.
ai_model: meshy-n1 ile Meshy, bu görseli ön görünüm olarak kullanarak dokulandırma yapar.
Görseldeki şekil modelden çok farklıysa görselden dokulandırma iyi çalışmayabilir.
Name
ai_model
Type
string
varsayılan inherited from the preview task
Description
Ağı dokulandıran AI modeli.
Kullanılabilir değerler:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: yalnızca bir referans görselden 2K temel renk dokusu. Metin prompt'u yok, PBR haritaları yok, 4K veya 8K yok.
- meshy-7 (kullanımdan kaldırıldı): bunun yerine meshy-7.1 gönderin
Preview'ın ve refine'ının baştan sona aynı model üzerinde çalışması için preview görevinin modelini kullanmak üzere boş bırakın. Geçersiz kılmak için bir değer gönderin. Açık bir latest, preview görevinde olduğu gibi çözümlenir; bu nedenle bir latest preview ve onun latest refine'ı her zaman aynı doku modelini kullanır.
meshy-n1 ile Meshy, texture_image_url'den dokulandırma yapar. Bu olmadan Meshy, bir meshy-7.1 veya latest preview'ının sakladığı referans görseli kullanır. Siz texture_image_url göndermedikçe başka herhangi bir preview 400 döndürür. Preview'da en fazla 7.999.999 üçgen olabilir. Quad'lara remesh edilmiş bir preview 400 döndürür.
Name
moderation
Type
boolean
varsayılan false
Description
Oluşturmadan önce texture_prompt ve texture_image_url'in zararlı içerik açısından taranıp taranmayacağı. Meshy zararlı içerik tespit ederse istek 400 döndürür ve Meshy bir görev oluşturmaz.
Name
remove_lighting
Type
boolean
varsayılan true
Description
Temel renk dokusundan parlama ve gölgelerin kaldırılıp kaldırılmayacağı. Daha temiz sonuç, özel aydınlatma altında daha iyi çalışır.
Yalnızca ai_model meshy-6 olduğunda etkilidir. meshy-7.1 ve latest bunu kabul eder ancak dikkate almaz; ai_model ayarlamayan bir meshy-t2 veya meshy-t2.5 preview'ının refine'ı da aynı şekilde davranır. meshy-6-lite ile gönderilmesi 400 döndürür. meshy-n1 ile true değeri 400 döndürür.
Name
target_formats
Type
string[]
Description
Oluşturulacak dosya biçimleri. Meshy yalnızca bu biçimleri oluşturur ve döndürür; bu da görevi kısaltabilir. Boş bırakırsanız Meshy, yalnızca talep ettiğinizde oluşturduğu 3mf dışındaki her biçimi oluşturur.
Kullanılabilir değerler:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
varsayılan false
Description
Saydam arka planlı (RGBA) bir önizlemenin de render edilip edilmeyeceği; görevi aldığınızda alpha_thumbnail_url içinde döndürülür. thumbnail_url değişmez.
Name
auto_size
Type
boolean
varsayılan false
Description
Nesnenin gerçek dünyadaki yüksekliğinin AI görüsüyle tahmin edilip modelin buna göre yeniden boyutlandırılıp boyutlandırılmayacağı. origin_at ayarlamadığınız sürece Meshy orijini alta yerleştirir.

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

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

Dönüş değerleri

Yanıtın result alanı, yeni Metinden 3D'ye görevinin ID'sini tutar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunu bulduğunu belirtir. Örneğin:
- Geçersiz görev ID'si: preview_task_id geçersiz veya preview görevlerinizden biriyle eşleşmiyor.
- Görev hazır değil: Preview görevi henüz başarılı olmadı.
- Model uyuşmazlığı: Preview görevinin AI modeli, talep edilen refine modeliyle çalışmıyor.
- remove_lighting için desteklenmeyen model: remove_lighting, ai_model: "meshy-6-lite" ile gönderildi.
- Meshy N1 için referans görsel yok: ai_model: meshy-n1, texture_image_url olmadan gönderildi ve preview'da Meshy N1'in kullanabileceği bir referans görsel yok. texture_image_url gönderin.
- Meshy N1 için quad preview: ai_model: meshy-n1, quad'lara remesh edilmiş bir preview için gönderildi. Başka bir ai_model ile refine edin.
- Meshy N1 için çok fazla üçgen: ai_model: meshy-n1 ile preview'da 7.999.999'dan fazla üçgen var. Başka bir ai_model ile refine edin.
- Meshy N1 için desteklenmeyen seçenek: ai_model: meshy-n1, şu seçeneklerden biriyle birlikte gönderildi:
  - texture_prompt
  - enable_pbr: true
  - 4k veya 8k olan texture_resolution
  - texture_resolution olmadan hd_texture: true
  - remove_lighting: true
İsteği düzeltin, ardından yeniden gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı. Kredi bakiyenizi kontrol edin, ardından yeniden deneyin.
- Ücretsiz plan: Bir görev oluşturmak ücretli bir plan gerektirir. Abonelik ayarlarınızdan planınızı yükseltin, ardından yeniden deneyin.
Name
403 - Forbidden
Description
İçerik moderasyonu, prompt'u veya bir girdi görselini engelledi. Girdiyi değiştirin, ardından yeniden deneyin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyin, ardından yeniden deneyin. Bkz. Hız sınırları.

GET/openapi/v2/text-to-3d/:id

Bir Metinden 3D'ye görevi al

Kimliğine göre bir Metinden 3D'ye görevi döndürür. Hem preview hem de refine görevleri için çalışır.

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": null,

  "consumed_credits": 20
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Metinden 3D'ye görev nesnesi.

Örnekler

Aşağıdaki tabloda her bir mode için örnek bir model gösterilmektedir.

Mode	Örnek model
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Bir Metinden 3D'ye görevini sil

Bir Metinden 3D'ye görevini, modelleri ve verileri dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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 keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin ID'si.

Görev durumu

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

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döner ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu yüzden onu silmek hem kredileri hem de sonucu kaybetmenize neden olur. SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Nihai bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

Dönüş değerleri

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

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

Text to 3D görevlerini listele

Text to 3D görevlerinizin 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": null,

    "consumed_credits": 20
  }
]

Parametreler

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

Döndürülenler

Text to 3D görev nesnelerinin sayfalanmış bir listesi.

GET/openapi/v2/text-to-3d/:id/stream

Bir Metinden 3D'ye görevini akışla izleme

Bir Metinden 3D'ye görevinin güncellemelerini Server-Sent Events (SSE) olarak akışla sunar.

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.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "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": null,

"consumed_credits": 20
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Metinden 3D'ye görev nesnelerinin Server-Sent Events olarak akışı.

Her olay, Get uç noktasının döndürdüğü biçimle aynı şekilde tam görev nesnesini içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.

Metinden 3D'ye görev nesnesi

Bir Metinden 3D'ye görev nesnesi, bir metin prompt'undan 3D model üreten bir görevi tanımlar. Görev başarılı olduğunda durumu, progress'i ve model dosyalarını tutar. Metinden 3D'ye işleminin preview ve refine olmak üzere iki aşaması vardır. Bir preview görevi yalnızca ağdan oluşan bir 3D model üretir, bir refine görevi ise preview sonucundan dokulu bir 3D model üretir.

Özellikler

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": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
Görev ID'si. Bunu opak bir dize olarak kabul edin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, bir preview görevi için text-to-3d-preview veya bir refine görevi için text-to-3d-refine.
Name
model_urls
Type
object
Description
Oluşturulan 3D model için indirme URL'leri, her dosya biçimi için bir tane. Görevin oluşturmadığı bir biçim için boş bir dize yerine anahtar bulunmaz.
- Name
  glb
  Type
  string
  Description
  GLB dosyası.
- Name
  fbx
  Type
  string
  Description
  FBX dosyası.
- Name
  usdz
  Type
  string
  Description
  USDZ dosyası.
- Name
  obj
  Type
  string
  Description
  OBJ dosyası.
- Name
  mtl
  Type
  string
  Description
  MTL dosyası.
- Name
  stl
  Type
  string
  Description
  STL dosyası.
- Name
  3mf
  Type
  string
  Description
  3MF dosyası. Yalnızca target_formats içinde 3mf bulunduğunda mevcuttur.
Name
prompt
Type
string
Description
Görevi oluşturmak için gönderdiğiniz prompt, değiştirilmeden.
Name
texture_prompt
Type
string
Description
Refine aşamasında dokulandırmaya rehberlik etmesi için gönderdiğiniz metin prompt'u.
Name
ultra_mode
Type
boolean
⚠ kullanımdan kaldırıldı
Description
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 bu alan bulunmaz.
Name
texture_image_url
Type
string
Description
Dokulandırmaya rehberlik etmesi için gönderdiğiniz görsel için indirme URL'si.
Name
thumbnail_url
Type
string
Description
3D modelin bir küçük resmi için indirme URL'si.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url değerinin saydam arka planlı (RGBA) bir sürümü için indirme URL'si. Yalnızca görevi alpha_thumbnail: true ile oluşturduğunuzda ve Meshy saydam önizlemeyi render ettiğinde mevcuttur.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0, başarılı olduğunda 100 değerindedir.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0 değerindedir.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
finished_at
Type
timestamp
Description
Görevin bittiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir.
Name
status
Type
string
Description
Görev durumu, PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biri.
Name
texture_urls
Type
array
Description
Oluşturulan doku haritaları için indirme URL'leri, bir nesne dizisi olarak. Genellikle bir nesne tutar. Her nesnede şu alanlar bulunur:
- Name
  base_color
  Type
  string
  Description
  Temel renk haritası.
- Name
  metallic
  Type
  string
  Description
  Metalik harita. Görevi enable_pbr: false ile oluşturduğunuzda bulunmaz.
- Name
  normal
  Type
  string
  Description
  Normal harita. Görevi enable_pbr: false ile oluşturduğunuzda bulunmaz.
- Name
  roughness
  Type
  string
  Description
  Pürüzlülük haritası. Görevi enable_pbr: false ile oluşturduğunuzda bulunmaz.
- Name
  emission
  Type
  string
  Description
  Emisyon haritası. Şu durumların herhangi birinde bulunmaz:
  
  Görevi enable_pbr: false ile oluşturdunuz.
  
  ai_model değeri meshy-6-lite, meshy-7, meshy-7.1 veya latest.
  
  texture_resolution değeri 8k.
  
  Görev, ai_model ayarlanmadan bir meshy-t2 veya meshy-t2.5 preview'ını refine ediyor.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önde olan görevlerin sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Durum FAILED olmadıkça null değerindedir. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı. Durum PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. Bir FAILED görevi için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.