Auto Split API

Bir 3D modeli ayrı ayrı basılabilir parçalara bölün — otomatik olarak, isimlendirdiğiniz parçalara göre veya renk bölgesine göre — isteğe bağlı bağlantı elemanlarıyla; bir kesimin geride bıraktığı ince bölgeler, her parçanın sağlam basılması için her zaman güçlendirilir.

Bölme sonucu, girdi dokusunu korumaz. Auto Split, dokulu girdileri kabul eder, bu nedenle modeli should_texture: false ile yeniden oluşturmanız gerekmez. Kesilen parçaları yeniden oluşturur ve her birine düz bir vertex rengi atar; hiçbir girdi doku haritası, dışa aktarılan formatlardan hiçbirine taşınmaz.

POST/openapi/v1/print/split

Bir Auto Split Görevi Oluştur

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ünmüş modeli döndürür.

Parametreler

  • Name
    input_task_id
    Type
    string
    Zorunlu
    Description

    Modeli bölünecek başarılı bir görevin ID'si. 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 (ai_model meshy-6, meshy-7, meshy-7.1 veya latest) üretilmiş olmalıdır. Low-poly ve Smart Topology (meshy-t2) modelleri desteklenmez. Dokulu bir model kabul edilir, ancak dokusu sonuca taşınmaz.

  • Name
    mode
    Type
    string
    varsayılan auto
    Description

    Modelin parçalara nasıl ayrılacağı.

    Kullanılabilir değerler:

    • auto: Kesimleri Meshy seçer. prompt göz ardı edilir.
    • 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 üretilmiş 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

    Hangi dilde olursa olsun, bölünecek parçaları 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 (figürü ve tabanı ayır) veya head, torso, left arm, right arm, legs (baş, gövde, sol kol, sağ kol, bacaklar). Tek bir parça adlandırmak da geçerlidir: adlandırmadığınız her şey kalan tek bir parça olur, bu yüzden the head (baş), web uygulamasında olduğu gibi modeli baş ve geri kalan olarak ikiye böler. En fazla 600 karakter. İki başarısızlık modu vardır: hiç bölme istemeyen bir açıklama veya 10'dan fazla parça adlandıran bir açıklama 400 ile reddedilir ve hiçbir ücret alınmaz; Meshy'nin hiç okuyamadığı bir açıklama auto moduna geri döner, görev yine de çalışır ve ücretlendirilir, ve yanıtı prompt_ignored: true taşır.

  • 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 ile düzenlenmiş tek bir katı nesnede 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 modeldeki konumlarında kalır.
    • on_plate: Parçalar düz bir şekilde yerleştirilir ve baskı tablasında yayılarak dilimlemeye hazır hale getirilir — 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 dilim veya nokta benzeri parça, dışa aktarmadan önce kaldırılır, böylece elde ettiğiniz her parça basılabilir olur. Sahne nesnelerini destekleyen formatlar parça başına bir nesne tutar; stl bunları tek bir katı nesnede birleştirir.

  • Name
    connectors
    Type
    boolean
    varsayılan false
    Description

    Basılan parçaların birbirine uyması için her kesime geçme-zıvana bağlantı elemanları ekler.

Yalnızca şu durumlarda geçerli connectors = true
  • Name
    connector_type
    Type
    string
    varsayılan cube
    Description

    Her kesim yüzeyindeki bağlantı elemanı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ğlantı elemanı boyutu.

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

  • Name
    connector_height
    Type
    number
    varsayılan 0.1
    Description

    Bağlantı elemanının kesim yüzeyine göre ne kadar uzağa uzandığı.

    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 Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik prompt: mode, by_parts veya by_color olduğunda prompt zorunludur.
    • Prompt hiçbir bölme tanımlamıyor veya çok fazla parça belirtiyor: by_parts / by_color, 1 ila 10 adlandırılmış parça kabul eder. Modeli tek parça halinde tutmak 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 üretilmiş, desteklenen bir türde başarılı bir göreve işaret etmelidir.
    • Referans görsel yok: by_color, yüklenen bir görselden üretilmiş bir girdi gerektirir.
    • Aralık dışı bağlantı elemanı: 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" 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 Getir

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek Auto Split görevinin kimliği.

Döndürülenler

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 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 ID'si.

Görev Durumu

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

Zaten IN_PROGRESS durumundaki bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlattığı bir görev için kredi iade edilemez, bu nedenle çalışma devam ederken silmek hem krediyi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Bitiş durumundaki (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

Auto Split Görevlerini Listele

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'den başlar ve varsayılan olarak 1'dir.

  • 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'e sabitlenir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralama için kullanı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öndürülenler

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

Auto Split Görevini Akışa Alma

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışa 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 Getirme tarafından döndürülen tam görev nesnesini taşır; buna consumed_credits, zaman damgaları ve prompt_ignored de 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 ve part_count 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 üretim promptu alanları (name, object_prompt, texture_prompt vb.), tekil model_url ve texture_urls, bir split için asla doldurulmaz ve döndürülmez. Görev çalışırken doldurulan özellikler (thumbnail_url, model_urls, zaman damgaları) her zaman mevcuttur; bir değer alana 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 şeklindedir.

  • Name
    model_urls
    Type
    object
    Description

    Bölünmüş modele indirilebilir URL'ler, istenen her format için bir tane. Sahne nesnelerini destekleyen formatlar her parçayı ayrı bir nesne olarak tutar; stl bunları tek bir katı gövdede birleştirir. İstenmeyen formatlara ait özellik atlanır.

    • Name
      glb
      Type
      string
      Description

      Bölünmüş modele GLB formatında indirilebilir URL.

    • Name
      obj
      Type
      string
      Description

      Bölünmüş modele OBJ formatında indirilebilir URL.

    • Name
      fbx
      Type
      string
      Description

      Bölünmüş modele FBX formatında indirilebilir URL.

    • Name
      stl
      Type
      string
      Description

      Bölünmüş modele STL formatında indirilebilir URL. Tüm parçalar tek bir katı gövdede birleştirilir; ayrı ayrı seçilebilir parçalar için 3mf isteyin.

    • Name
      usdz
      Type
      string
      Description

      Bölünmüş modele USDZ formatında indirilebilir URL.

    • Name
      blend
      Type
      string
      Description

      Bölünmüş modele Blender formatında indirilebilir URL.

    • Name
      3mf
      Type
      string
      Description

      Bölünmüş modele 3MF formatında indirilebilir URL.

  • Name
    thumbnail_url
    Type
    string
    Description

    İstenen layout düzeninde, her parçanın farklı 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 promptunda 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örevleri için ve prompt'un takip edildiği durumlarda atlanır.

  • Name
    part_count
    Type
    integer
    Description

    Bölme işleminin ürettiği yazdırılabilir parça sayısı. Sahne nesnelerini destekleyen formatlar her parça için bir nesne taşır; stl bunları tek bir katı gövdede birleştirir ve sayım yine de parçaları raporlar. Segmentasyonun yazdırılabilir bir parçaya dönüştüremediği çökmüş kırıntılar, dışa aktarmadan önce dosyalardan çıkarı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 olacaktır. Görev başarılı olduğunda 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 andaki zaman damgası, milisaniye cinsinden.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı andaki zaman damgası, milisaniye cinsinden. Görev henüz tamamlanmadıysa bu özellik 0 olacaktır.

  • Name
    task_error
    Type
    object
    Description

    Başarısız görevler için hata detayları. Eksiksiz task_error nesne referansı için Hatalar bölümüne bakın.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen kredi sayısı. Her zaman mevcuttur: görev kabul edildikten sonra 10, FAILED görevler için ise 0 — çünkü başarısızlık durumunda ücret iade edilir. Bir görevi hâlâ PENDING durumundayken silmek de ücretini iade eder.

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
}