Auto Split API

Bir 3D modeli ayrı ayrı basılabilir parçalara bölün — otomatik olarak, belirttiğiniz parçalara göre veya renk bölgesine göre — isteğe bağlı bağlayıcılarla; bir kesimin bıraktığı ince bölgeler her zaman güçlendirilir, böylece her parça sağlam şekilde basılır.

Bölme sonucu, girdi dokusunu korumaz. Auto Split, doku içeren girdileri kabul eder, bu nedenle modeli should_texture: false ile yeniden oluşturmanıza gerek yoktur. Kesilen parçaları yeniden oluşturur ve her birine düz bir köşe (vertex) rengi atar; dışa aktarılan hiçbir formata girdi doku haritası taşınmaz.

POST/openapi/v1/print/split

Bir Auto Split Görevi Oluşturun

Bu uç nokta, yeni bir Auto Split görevi oluşturur. Bu görev, önceki bir görevin modelini ayrı ayrı yazdırılabilir parçalara böler ve her parçanın dosya içinde kendi nesnesi olduğu segmentlere ayrılmış modeli döndürür.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü öğrenmek için İşlem Süreleri bölümüne bakın.

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
Modeli bölünecek, başarıyla tamamlanmış bir görevin kimliği. Desteklenen görev türleri: Görselden 3D'ye, Çoklu görselden 3D'ye, Metinden 3D'ye (önizleme), Yeniden ağ, Dönüştür ve Yeniden boyutlandır. Görevin durumu SUCCEEDED olmalı ve modeli Meshy 6 veya Meshy 7 ile oluşturulmuş olmalıdır (ai_model meshy-6, meshy-7, meshy-7.1 veya latest). Low-poly ve Smart Topology (meshy-t2, meshy-t2.5) modelleri desteklenmez. Dokulu bir model kabul edilir, ancak dokusu sonuca aktarılmaz.

Name
mode
Type
string
varsayılan auto
Description
Modelin parçalara nasıl bölüneceği.
Kullanılabilir değerler:
- auto: Kesimleri Meshy belirler. prompt dikkate alınmaz.
- by_parts: prompt içinde adlandırdığınız yapısal parçalar boyunca keser, örneğin baş, kollar ve gövde.
- by_color: prompt içinde adlandırdığınız renk bölgeleri boyunca keser. Yüklenen bir görselden oluşturulmuş bir girdi gerektirir (Görselden 3D'ye veya Çoklu görselden 3D'ye); diğer girdiler 400 ile reddedilir. Renk bölgesi sınırları, girdi modelin dokusundan değil, kaynak görselden gelir. Çoklu görselden 3D'ye için Auto Split, ilk kaynak görseli kullanır.

Yalnızca şu durumlarda geçerli mode = by_parts or by_color

Name
prompt
Type
string
Zorunlu
Description
Bölünecek parçaları, herhangi bir dilde açıklar. Meshy bundan 1 ila 10 parça adı okur, bu yüzden modeli tanımlamak yerine parçaları adlandırın, örneğin split into the figure and the base veya head, torso, left arm, right arm, legs. Tek bir parçayı adlandırmak da uygundur: adlandırmadığınız her şey kalan tek bir parça olur, böylece the head, modeli baş ve geri kalanı olarak böler; tıpkı web uygulamasında olduğu gibi. En fazla 600 karakter. Hiç bölme istemeyen veya 10'dan fazla parça adlandıran bir açıklama 400 ile reddedilir ve hiçbir ücret alınmaz. Meshy açıklamadan herhangi bir parça adı okuyamazsa, bunun yerine seçtiğiniz mode'da modelin referans görselinde tanımladığı parçalar boyunca böler: görev yine de çalışır ve ücretlendirilir, ve prompt_ignored: true değerini taşır. Modelin referans görseli yoksa veya Meshy içinde ikiden az parça bulursa, bu istek bunun yerine 400 ile reddedilir ve hiçbir ücret alınmaz.

Name
target_formats
Type
array
varsayılan ["glb"]
Description
Bölünmüş modelin dışa aktarılacağı formatlar. Sahne nesnelerini destekleyen formatlar (glb, obj, fbx, usdz, blend, 3mf) her parçayı ayrı bir nesne olarak taşır; stl ayrı nesne kavramına sahip olmadığından, her parçayı layout tarafından düzenlenmiş tek bir katı halinde birleştirir (bir dilimleyicide ayrı ayrı seçilebilir parçalar için 3mf isteyin). glb her zaman üretilir ve model_urls içinde döndürülür; ek olarak istediğiniz diğer formatları listeleyin.
Kullanılabilir değerler: glb, obj, fbx, stl, usdz, blend, 3mf.
Name
layout
Type
string
varsayılan assembled
Description
Parçaların her çıktı formatında ve küçük resimde nasıl düzenleneceği.
Kullanılabilir değerler:
- assembled: Parçalar, kaynak modelde bulundukları yerde kalır.
- on_plate: Parçalar düz bir şekilde yerleştirilir ve yapı tablasına yayılır, dilimlemeye hazır hale gelir — web uygulamasının On Plate görünümüyle aynı düzenleme.
Her iki düzende de, bir kesimden arta kalan çökmüş bir ince parça veya nokta benzeri parça, dışa aktarmadan önce kaldırılır, böylece elde ettiğiniz her parça yazdırılabilir olur. Sahne nesnelerini destekleyen formatlar, parça başına bir nesne tutar; stl bunları tek bir katı halinde birleştirir.
Name
connectors
Type
boolean
varsayılan false
Description
Her kesimde geçme (mortise-and-tenon) bağlayıcılar ekler, böylece yazdırılan parçalar birbirine uyar.

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

Name
connector_type
Type
string
varsayılan cube
Description
Her kesim yüzeyindeki bağlayıcının şekli.
Kullanılabilir değerler: cube, cylinder.
Name
connector_size
Type
number
varsayılan 0.5
Description
Kesim yüzeyine göre bağlayıcı boyutu.
Geçerli aralık: 0.1 ila 0.8.
Name
connector_height
Type
number
varsayılan 0.1
Description
Bağlayıcının kesim yüzeyinden ne kadar uzandığı, kesim yüzeyine göre.
Geçerli aralık: 0.1 ila 0.8.

Dönüş Değerleri

Yanıtın result özelliği, yeni oluşturulan Auto Split görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik prompt: mode değeri by_parts veya by_color olduğunda prompt zorunludur.
- Prompt hiçbir bölme tanımlamıyor veya çok fazla parça içeriyor: by_parts / by_color, 1 ila 10 adlandırılmış parça kabul eder. Modeli tek parça halinde tutmayı isteyen veya 10'dan fazla parça adlandıran bir açıklama reddedilir. Hiçbir ücret alınmaz.
- Desteklenmeyen girdi görevi: input_task_id, Meshy 6 veya Meshy 7 ile oluşturulmuş, desteklenen bir türde başarıyla tamamlanmış bir göreve atıfta bulunmalıdır.
- Referans görseli yok: by_color, yüklenen bir görselden oluşturulmuş bir girdi gerektirir.
- Aralık dışı bağlayıcı: connector_size veya connector_height, 0.1 ila 0.8 aralığının dışında.
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
input_task_id mevcut değil veya hesabınıza ait değil.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. by_parts ve by_color istekleri ayrıca hesap başına dakikada 12 istek olan bir prompt ayrıştırma sınırını paylaşır.
Name
503 - Service Unavailable
Description
Prompt tabanlı bölme (by_parts ve by_color) geçici olarak kullanılamıyor. Daha sonra tekrar deneyin veya bundan etkilenmeyen mode: "auto" seçeneğini kullanın. Hiçbir ücret alınmaz.

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/split/:id

Auto Split Görevini Alma

Bu uç nokta, bir Auto Split görevini kimliğine göre alır.

Parametreler

Name
id
Type
path
Description
Alınacak Auto Split görevinin kimliği.

Dönüş Değerleri

Auto Split Task nesnesi.

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

DELETE/openapi/v1/print/split/:id

Bir Auto Split Görevini Sil

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

Yol Parametreleri

Name
id
Type
path
Description
Silinecek Auto Split görevinin kimliği.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan kredi iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. İşçinin (worker) zaten başlatmış olduğu bir görev için kredi iadesi yapılmaz, bu nedenle çalışma sırasında silmek hem krediyi 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ö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öner.

Request

DELETE

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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/v1/print/split

List Auto Split Tasks

Bu uç nokta, Auto Split görevlerinin bir listesini almanızı sağlar.

Parametreler

İsteğe bağlı özellikler

Name
page_num
Type
integer
Description
Sayfalama için sayfa numarası. 1 ile başlar ve varsayılan değeri 1'dir.
Name
page_size
Type
integer
Description
Sayfa boyutu sınırı. Varsayılan değer 10 öğedir. İzin verilen maksimum değer 100 öğedir; daha büyük değerler 100 olarak sınırlandırılır.
Name
sort_by
Type
string
Description
Sıralama yapılacak alan. Kullanılabilir değerler:
- +created_at: Oluşturulma zamanına göre artan sırayla sıralar.
- -created_at: Oluşturulma zamanına göre azalan sırayla sıralar.

Dönüş Değerleri

Auto Split Görev Nesneleri'nin sayfalanmış bir listesini döndürür.

Request

GET

/openapi/v1/print/split

curl https://api.meshy.ai/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/split/:id/stream

Bir Auto Split Görevini Akışla Al

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Auto Split görevi için gerçek zamanlı güncellemeleri akış olarak sunar.

Parametreler

Name
id
Type
path
Description
Akışı alınacak Auto Split görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

Auto Split Görev Nesneleri akışını Server-Sent Events olarak döndürür.

Her message olayı, Bir Auto Split Görevini Getir tarafından döndürülen tam görev nesnesini taşır; bu, consumed_credits, zaman damgaları ve prompt_ignored değerlerini de içerir. Görev PENDING veya IN_PROGRESS durumundayken kareler arasında değişen alanlar progress, status, started_at ve preceding_tasks'tir; model_urls, thumbnail_url ve part_count ise görev SUCCEEDED durumuna ulaştığında ortaya çıkar. Bir error olayı yalnızca status_code ve message taşır, bu nedenle status değerini okumadan önce olay adına göre dallanma yapın.

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split Görev Nesnesi

Bir Auto Split görevi yalnızca aşağıdaki özellikleri taşır. Diğer görev nesnelerinin içerdiği üretim-prompt alanları (name, object_prompt, texture_prompt ve benzerleri), tekil model_url ve texture_urls bir bölme işlemi için asla doldurulmaz ve döndürülmez. Görev çalışırken doldurulan özellikler (thumbnail_url, model_urls, zaman damgaları) her zaman mevcuttur; değerleri olana kadar boştur, bu yüzden anahtar kümesi PENDING ile SUCCEEDED arasında değişmez.

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı. Görev kimlikleri için uygulama ayrıntısı olarak k-sıralanabilir bir UUID kullansak da, kimliğin biçimiyle ilgili herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Görevin türü. Değer print-split olur.
Name
model_urls
Type
object
Description
Bölünmüş modele indirilebilir URL'ler, talep edilen her biçim için bir tane. Sahne nesnelerini destekleyen biçimler her parçayı ayrı bir nesne olarak tutar; stl ise bunları tek bir katı nesnede birleştirir. Bir biçim talep edilmediyse o biçime ait özellik atlanır.
- Name
  glb
  Type
  string
  Description
  Bölünmüş modele GLB biçiminde indirilebilir URL.
- Name
  obj
  Type
  string
  Description
  Bölünmüş modele OBJ biçiminde indirilebilir URL.
- Name
  fbx
  Type
  string
  Description
  Bölünmüş modele FBX biçiminde indirilebilir URL.
- Name
  stl
  Type
  string
  Description
  Bölünmüş modele STL biçiminde indirilebilir URL. Tüm parçalar tek bir katı nesnede birleştirilir; ayrı ayrı seçilebilir parçalar için 3mf isteyin.
- Name
  usdz
  Type
  string
  Description
  Bölünmüş modele USDZ biçiminde indirilebilir URL.
- Name
  blend
  Type
  string
  Description
  Bölünmüş modele Blender biçiminde indirilebilir URL.
- Name
  3mf
  Type
  string
  Description
  Bölünmüş modele 3MF biçiminde indirilebilir URL.
Name
thumbnail_url
Type
string
Description
Bölünmüş modelin, her parçanın farklı bir renkte gösterildiği, talep edilen layout düzenindeki render edilmiş önizlemesine indirilebilir URL.
Name
prompt_ignored
Type
boolean
Description
Bir by_parts veya by_color isteğinin prompt alanı hiçbir parça adı belirtmediğinde true olur; bu durumda Meshy modeli otomatik olarak böler — sonuçtaki parça adları sizin değil Meshy'nin belirlediği adlardır. PENDING durumundan itibaren mevcuttur. auto görevlerinde ve prompt'un takip edildiği her durumda atlanır.
Name
part_count
Type
integer
Description
Bölme işleminin ürettiği yazdırılabilir parça sayısı. Sahne nesnelerini destekleyen biçimler, parça başına bir nesne taşır; stl bunları tek bir katı nesnede birleştirir, ancak sayım yine de parça sayısını bildirir. Segmentasyonun yazdırılabilir bir parçaya dönüştüremediği çökmüş ince parçalar, dışa aktarmadan önce dosyalardan kaldırılır ve sayıma dahil edilmez.
Name
progress
Type
integer
Description
Görevin ilerleme durumu. Görev henüz başlamadıysa bu özellik 0 olur. Görev başarıyla tamamlandığında bu değer 100 olur.
Name
status
Type
string
Description
Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biridir.
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
created_at
Type
timestamp
Description
Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.
Name
started_at
Type
timestamp
Description
Görevin başladığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa bu özellik 0 olur.
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
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 bölümüne bakın. Model sağlayıcısının güvenlik denetimi giriş modelini reddederse, görev task_error.type değeri invalid_input ve code değeri provider_content_refused ile başarısız olur. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. Her zaman mevcuttur: görev kabul edildikten sonra 10, FAILED görevler için ise 0 olur çünkü başarısızlık durumunda ücret iade edilir. Bir görevi hâlâ PENDING durumundayken silmek de ücretin iadesini sağlar.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}