Auto Split API

Bir 3D modeli ayrı ayrı basılabilir parçalara böler — otomatik olarak, isimlendirdiğiniz parçalara göre ya da renk bölgesine göre — isteğe bağlı bağlayıcılarla; bir kesim sonucunda oluşan ince bölgeler her zaman güçlendirilir, böylece her parça sağlam bir şekilde basılır.

Auto Split şu anda yalnızca texture içermeyen modelleri desteklemektedir. Görselden 3D'ye ve Çoklu görselden 3D'ye için girdiyi should_texture değeri false olarak ayarlayarak oluşturun. Texture içeren bir girdi 400 ile reddedilir. Texture desteği progress durumundadır.

POST/openapi/v1/print/split

Auto Split Görevi Oluşturma

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

Parametreler

  • Name
    mode
    Type
    string
    varsayılan auto
    Description

    Modelin parçalara nasıl bölüneceği.

    Kullanılabilir değerler:

    • auto: Kesimleri Meshy seçer. prompt göz ardı edilir.
    • by_parts: prompt içinde belirttiğiniz yapısal parçalar (baş, kollar, gövde gibi) boyunca keser.
    • by_color: prompt içinde belirttiğiniz renk bölgeleri boyunca keser. Girdinin, yüklenen bir görselden oluşturulmuş olması gerekir (Görselden 3D'ye veya Çoklu görselden 3D'ye); diğer girdiler 400 ile reddedilir.
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 tanımlar. Meshy bundan 1 ile 10 arası parça adı okur; bu nedenle modeli tanımlamak yerine parçaları adlandırın — örneğin figürü ve tabanı ayır veya baş, gövde, sol kol, sağ kol, bacaklar. En fazla 600 karakter. İki tür başarısızlık durumu vardır: bir bölme gibi okunan ama ikiden az parça adı içeren bir tanım (örneğin ayrı parçalara böl) 400 ile reddedilir ve herhangi bir ücret alınmaz; Meshy'nin hiç okuyamadığı bir tanım ise auto'ya geri döner, görev yine de çalıştırılır ve ücretlendirilir, yanıtında prompt_ignored: true bulunur.

  • Name
    target_formats
    Type
    array
    varsayılan ["glb"]
    Description

    Bölünen modelin dışa aktarılacağı formatlar. Her parça, her formatta ayrı bir nesnedir. 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, usdz, blend, 3mf.

    3mf dilimleyiciler için yazılır: her parça için bir nesne, her biri kendi filament yuvasında olur; böylece Bambu Studio dosyayı ayrı ayrı renklendirilmiş, tek tek seçilebilir parçalar olarak açar (arşiv bir Bambu Studio proje yapılandırması taşır; diğer dilimleyiciler yalnızca geometriyi okur). Meshy'nin diğer baskı formatları gibi bu da milimetre cinsindendir ve bu uç nokta hedef boyut almadığı için tüm model, en uzun kenarı 150 mm olacak şekilde ölçeklendirilir — bu, diğer baskı formatı dışa aktarımlarının kullandığı ve her yaygın baskı tablasına uyacak şekilde seçilmiş aynı üst sınırdır. layout: "on_plate" ile bu üst sınır, düzenlenmiş tablanın tamamına uygulanır; böylece dosya dilimlemeye hazır olur. assembled ile ise parçalar kaynak modeldeki konumlarında kalır ve onları dilimleyicide siz düzenlersiniz.

    stl, ayrı parçaları taşıyamadığı için desteklenmez.

  • 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 modeldeki konumlarında kalır.
    • on_plate: Parçalar düz bir şekilde baskı tablasına yayılır ve dilimlemeye hazır hale gelir — web uygulamasının On Plate görünümüyle aynı düzenleme.

    Her iki düzende de dışa aktarılan dosyalar, her parça için bir nesne dışında başka hiçbir şey içermez: bir kesimden geriye kalan çökmüş bir ince parça veya nokta benzeri bir parça, dışa aktarmadan önce kaldırılır; böylece dosyada bulduğunuz her nesne basılabilirdir.

  • Name
    connectors
    Type
    boolean
    varsayılan false
    Description

    Basılan parçaların birbirine oturması için her kesime geçme (mortise-tenon) tipi bağlayıcılar ekler.

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 ile 0.8 arası.

  • Name
    connector_height
    Type
    number
    varsayılan 0.1
    Description

    Bağlayıcının kesim yüzeyinden ne kadar dışarı uzandığı, kesim yüzeyine göre.

    Geçerli aralık: 0.1 ile 0.8 arası.

Dönüş Değerleri

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

Başarısızlık Durumları

  • 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 ikiden az parça adlandırıyor: by_parts / by_color için en az iki adlandırılmış parça gerekir (örneğin baş, gövde, taban); ayrı parçalara böl gibi genel bir talimat reddedilir. Herhangi bir ücret alınmaz.
    • Desteklenmeyen girdi görevi: input_task_id, desteklenen bir türde ve Meshy 6 veya Meshy 7 ile oluşturulmuş, başarılı bir göreve işaret etmelidir.
    • Dokulu girdi: Girdi modelinin textureları var. Şu an için yalnızca texture'sız modeller desteklenir.
    • Referans görsel yok: by_color, yüklenen bir görselden oluşturulmuş bir girdi gerektirir.
    • Desteklenmeyen format: target_formats içinde stl bulunuyor.
    • Aralık dışı bağlayıcı: connector_size veya connector_height, 0.1 ile 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. Herhangi 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

Bir Auto Split Görevini Alma

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Alınacak Auto Split görevinin kimliği.

Dönüş Değerleri

Auto Split Görevi 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 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.

Dönüş Değerleri

Başarılı olduğunda 200 OK 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

// Returns 200 Ok on success.
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 değerinden başlar ve varsayılan olarak 1 değerini alır.

  • Name
    page_size
    Type
    integer
    Description

    Sayfa boyutu sınırı. Varsayılan olarak 10 öğedir. İzin verilen maksimum değer 100 öğedir; daha büyük değerler 100 ile 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ırada sıralar.
    • -created_at: Oluşturulma zamanına göre azalan sırada 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ış Olarak Aktar

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

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

Her message olayı, Bir Auto Split Görevini Al tarafından döndürülen tam görev nesnesini taşır; buna consumed_credits, zaman damgaları ve prompt_ignored da dahildir. Görev PENDING veya IN_PROGRESS durumundayken kareler arasında değişen alanlar progress, status, started_at ve preceding_tasks'tır; model_urls, thumbnail_url, part_count ve parts ise görev SUCCEEDED durumuna ulaştığında görünür. Bir error olayı yalnızca status_code ve message taşır, bu yüzden status alanını 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 prompt oluşturma alanları (name, object_prompt, texture_prompt ve benzerleri), tekil model_url ve texture_urls, bir bölme (split) işlemi için hiçbir zaman doldurulmaz ve döndürülmez. Görev çalışırken doldurulan özellikler (thumbnail_url, model_urls, zaman damgaları) her zaman mevcuttur ve bir değere sahip olana kadar boş kalır; bu nedenle anahtar kümesi PENDING ile SUCCEEDED arasında değişmez.

  • Name
    id
    Type
    string
    Description

    Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev id'leri için k-sıralanabilir bir UUID kullansak da, id'nin biçimi hakkında herhangi bir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Görevin türü. Değer print-split'tir.

  • Name
    model_urls
    Type
    object
    Description

    Bölünmüş modele indirilebilir URL'ler, istenen her format için bir tane. Her parça, dosyada ayrı bir nesnedir. İlgili format istenmediyse bu formata ait özellik atlanır.

    • Name
      glb
      Type
      string
      Description

      Bölünmüş modelin GLB formatındaki indirilebilir URL'si.

    • Name
      obj
      Type
      string
      Description

      Bölünmüş modelin OBJ formatındaki indirilebilir URL'si.

    • Name
      fbx
      Type
      string
      Description

      Bölünmüş modelin FBX formatındaki indirilebilir URL'si.

    • Name
      usdz
      Type
      string
      Description

      Bölünmüş modelin USDZ formatındaki indirilebilir URL'si.

    • Name
      blend
      Type
      string
      Description

      Bölünmüş modelin Blender formatındaki indirilebilir URL'si.

    • Name
      3mf
      Type
      string
      Description

      Bölünmüş modelin 3MF formatındaki indirilebilir URL'si: her parça ayrı bir nesne olarak, kendi filament yuvasında, milimetre cinsinden, en uzun kenarı 150 mm olacak şekilde ölçeklendirilmiş ve bir Bambu Studio proje yapılandırması içerir.

  • Name
    thumbnail_url
    Type
    string
    Description

    İstenen layout düzeninde, her parçanın ayrı bir renkte gösterildiği bölünmüş modelin render edilmiş önizlemesine indirilebilir URL.

  • Name
    prompt_ignored
    Type
    boolean
    Description

    Bir by_parts veya by_color isteğinin prompt'unda hiçbir parça belirtilmediğ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 durumlarda atlanır.

  • Name
    part_count
    Type
    integer
    Description

    Bölünmüş modeldeki basılabilir parça sayısı — dışa aktarılan dosyalardaki her nesne için bir tane. Segmentasyonun basılabilir bir parçaya dönüştüremediği çökmüş ince kesitler, 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'dan 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 detayları. task_error nesnesinin tam referansı için Hatalar sayfasına bakın.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen kredi sayısı. Her zaman mevcuttur: görev kabul edildiğinde 10, FAILED görevlerde 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
}